🧱 Volto blocks

sc-videos registers two Volto blocks. They serve different purposes and appear in different contexts.

🎬 Video Player block

The Video Player block is designed for the Video content type page. It reads the video URL directly from the parent content's videoUrl field (set via the 📋 IRemoteVideo behavior), not from block data.

Property	Value
Block ID	playerBlock
Title	Video Player
Group	video
Icon	videocamera.svg
Restriction	Only on Video content
Sidebar tab	1

Schema

Field	Widget	Default	Description
autoPlay	Boolean	false	Start the video automatically on page load.
size	image_size	l	Player width: s (small), m (medium), l (large).
align	align	wide	Horizontal alignment: left, right, center, wide, full.

Edit behavior

When the parent Video content has no videoUrl yet:

1. The block renders an EditForm: an in-block placeholder that embeds the VideoURLWidget.

2. The editor pastes a URL and clicks the arrow button to fetch metadata.

3. After a successful metadata fetch (_metadata is populated), the block transitions to the player view.

When videoUrl is already set (existing content):

1. The block renders the embedded video player.

2. The sidebar shows the schema fields (autoPlay, size, align).

Data flow

The Video Player block does not store the video URL in block data. It uses Volto's properties (parent content fields) and onChangeField to read and write the URL.

properties.videoUrl → VideoPlayerBlock View → VideoPlayer component
                    ↑
EditForm → VideoURLWidget → onChangeField('videoUrl', url)

📺 Video block

The Video block is for embedding an existing Video content item in any page. Documents, News Items, or any content type with Volto blocks support.

Property	Value
Block ID	video
Title	Video
Group	video
Icon	videocamera.svg
Restriction	Not on Video content (complementary to Video Player)
Sidebar tab	1
Grid support	Yes (registered in gridBlock.allowedBlocks)

Schema

Field	Widget	Default	Description
href	object_browser (mode: link)	.	Reference to a Video content item. Fetches Title, Description, hasPreviewImage, videoUrl as selected attributes.
autoPlay	Boolean	false	Start the video automatically.
size	image_size	l	Player width.
align	align	.	Horizontal alignment.
showCaption	Boolean	true	When true and at least one caption field is populated, render the caption below the player.
title	Text	--	Caption title. Rendered as <strong class="title"> by the Caption component.
description	textarea	--	Plain-text caption description. Line breaks are preserved and rendered as <p> elements.

The caption is rendered using the Caption component from @kitconcept/volto-light-theme as a <figcaption> inside the player's <figure>, and appears only when showCaption is true and either title or description has content.

Data adapter

When an editor picks a video via the object browser or the in-block VideoInput, the block's dataAdapter shapes the catalog item into the href[] structure:

interface VideoHref {
  '@id': string;        // Content URL
  Title: string;        // Uppercase (catalog metadata)
  title: string;        // Lowercase (ObjectBrowserWidget display)
  Description: string;
  hasPreviewImage: boolean;
  image_scales: ImageScalesSummary;
  videoUrl: string;     // External video URL
}

The title (lowercase) field is required by Volto's ObjectBrowserWidget to display the selected item label in the sidebar.

When a video is selected (via either the in-block picker or the sidebar object browser), the caption title and description are populated from the item's Title and Description, but only when those fields are currently empty, so editor overrides are never overwritten.

Edit behavior

When no video is selected (data.href is empty):

1. The block renders a VideoInput placeholder with a browse button.

2. Clicking the button opens the object browser, filtered to Video content only.

3. On selection, the dataAdapter commits the picked item to data.href[].

When a video is selected:

1. The block renders the embedded player with the video's preview image and title.

2. The sidebar shows the schema fields.

🎨 Styling schema enhancer

Both blocks share a videoSchemaEnhancer that adds the alignment schema to the block's style fieldset. The available alignment options are: left, right, center, wide, full.

The defaultStylingSchema from @kitconcept/volto-light-theme is also composed in, providing theme selection support.

See also

• 🔧 Volto widgets. The widgets used by these blocks (VideoURLWidget, VideoInput).

• 🧱 Blocks and widgets. When to use each block.

• 🎨 CSS custom properties. CSS custom properties for player theming.