MethodBackgroundControls

Overview

Image and video background management with media upload, resolution selection, position alignment, display sizing, repeat options, and parallax toggle.

• File: lib/blocks/components/MethodBackgroundControls.js
• Panel context: Typically rendered inside a “Background Media” PanelBody

Props

Controls

Image Selection (base breakpoint only)

• UI: MediaUpload with Select/Change/Reset buttons and image thumbnail preview.
• Attribute: bgImg (top‑level object, not inside responsiveSettings)

When an image is selected, the component builds a bgImg object containing all available WordPress image sizes with their URLs and dimensions:

{
  id: 123,
  full: { url: '...', width: 1920, height: 1080 },
  large: { url: '...', width: 1024, height: 576 },
  medium: { url: '...', width: 300, height: 169 },
  // ...additional registered sizes
}

{
  id: 123,
  full: { url: '...', width: 1920, height: 1080 },
  large: { url: '...', width: 1024, height: 576 },
  medium: { url: '...', width: 300, height: 169 },
  // ...additional registered sizes
}

Size variants that are the same dimensions or URL as full are excluded. After selection, bgImgSize is auto‑set to large if available, otherwise full.

Image Resolution

• UI: CustomSelectControl showing available size names with dimensions as hints (e.g., “Large — 1024×576”).
• Settings key: responsiveSettings.{breakpoint}.bgImgSize
• Visibility: Shown when bgImg has been selected and the current breakpoint is enabled.

Available sizes are dynamically computed from the bgImg attribute cross‑referenced with the editor’s registered imageSizes.

Image Alignment

• UI: AlignmentMatrixControl (3×3 grid) + text label showing the current value.
• Settings key: responsiveSettings.{breakpoint}.bgImgAlign
• Default: "center center"
• Visibility: Base breakpoint only; hidden when parallax or video is active; hidden in isImg mode.

Position Offset

• UI: Two UnitControl fields for X and Y offset.
• Settings keys: responsiveSettings.{breakpoint}.bgOffsetX, responsiveSettings.{breakpoint}.bgOffsetY
• Visibility: Same conditions as Image Alignment.

Display Size

• UI: SelectControl dropdown.
• Settings key: responsiveSettings.{breakpoint}.bgDisplaySize

In standard background mode (isImg=false):

In image‑fitting mode (isImg=true):

When “Custom” is selected, additional Width and Height UnitControl fields appear.

Repeat

• UI: SelectControl dropdown.
• Settings key: responsiveSettings.{breakpoint}.bgRepeat
• Visibility: Hidden in isImg mode and when parallax/video is active.

Parallax Toggle

• UI: CheckboxControl.
• Attribute: useParallax (top‑level attribute, not in responsiveSettings)
• Visibility: Hidden in isImg mode.

The checkbox label includes a help note: “If enabled, Jarallax will be used to add parallax scrolling. Automatically enabled for background video.” When bgVideo has a value, the checkbox is forced to checked.

Background Video URL

• UI: TextControl.
• Attribute: bgVideo (top‑level attribute)
• Visibility: Only when includeVideo=true, not in isImg mode, and breakpoint is enabled.

Accepts URLs from YouTube, Vimeo, or direct video sources. Processed by Jarallax’s video extension.

Responsive Override

For non‑base breakpoints, a “Custom Background” checkbox (responsiveSettings.{breakpoint}.customBg) gates all controls. When unchecked, the breakpoint inherits from base.

Usage by Blocks