🧱 Blocks and widgets

🧱 Blocks and widgets#

sc-videos provides two distinct blocks and several widgets. This page explains the differences and when to use each.

📊 Two blocks, two use cases#

Video Player block

Video block

Purpose

Play the video that is this content

Embed a video from elsewhere in the site

Where it appears

Video content pages only

Any content type with blocks

URL source

Parent content's videoUrl field

Referenced Video's catalog metadata

Data model

Reads from properties (content fields)

Stores href[] in block data

Edit affordance

In-block VideoURLWidget + fetch

In-block VideoInput (object browser)

Grid support

No

Yes

When to use the Video Player block#

Use the Video Player block when you're editing a Video content item and want to display its video. This block is pre-configured in the Video content type's default layout. you don't need to add it manually.

The block reads the video URL from the content's videoUrl field (via the IRemoteVideo behavior) and renders the player. Changes to the URL update the content, not block data.

When to use the Video block#

Use the Video block when you want to embed a video on a non-Video page (a Document, a News Item, an Event, etc.). The block lets you pick an existing Video content item via the object browser.

The block stores a reference to the Video in its own href[] block data. The same Video can be embedded on multiple pages.

🔧 Widget roles#

VideoURLWidget#

The main editing widget for the videoUrl field. Appears in two places:

  1. Content type sidebar: Volto's form engine renders it automatically for the videoUrl field (because the backend's JSON schema provider returns widget: "VideoURL").

  2. In-block EditForm: the Video Player block's edit mode embeds it directly in the block area for a more prominent editing experience.

Both instances bind to the same content field (properties.videoUrl) via onChangeField, so they stay in sync.

VideoMetadataWidget#

A hidden widget for the _metadata JSON field. It stores the raw metadata returned by the provider. Renders no visible UI. it's purely a data carrier used by the event subscribers and the metadata preview.

VideoInput#

An in-block placeholder component (not a form widget). Used by the Video block to let editors pick a Video from the object browser. It opens the browser filtered to Video content only and calls the block's dataAdapter when an item is selected.

🔄 How they connect#

        flowchart TD
    subgraph "Video content page"
        A["VideoPlayerBlock (Edit)"]
        B["EditForm"]
        C["VideoURLWidget"]
        D["Content sidebar"]
        E["VideoURLWidget (sidebar)"]
        A --> B
        B --> C
        D --> E
        C -.->|"onChangeField('videoUrl')"| E
    end

    subgraph "Any other page"
        F["VideoBlock (Edit)"]
        G["VideoInput"]
        H["Object Browser"]
        I["dataAdapter"]
        F --> G
        G --> H
        H --> I
        I -->|"onChangeBlock(block, {href: [...]})"| F
    end

See also

Contents