Layout Mapping Settings

Layout mapping connects your Divi Handoff Layouts to SCF/ACF Flexible Content layouts. This two-part system allows you to create multiple visual representations for the same content structure.

Understanding Layout Mapping

The layout mapping system works in two places:

1. Divi Handoff Layouts - Define which Flexible Content layout a Divi layout can render
2. Page Editor - Select which Divi Handoff Layout to use for each content row

This separation means you can:

• Create multiple Divi layouts for the same SCF/ACF layout
• Choose different visual styles per page
• Reuse content structures with different designs

Layout Mapping Meta Box

When editing a Divi Handoff Layout, the Divi Handoff Layout Mapping meta box appears in the sidebar.

Location

Divi Handoff Layouts → Edit any layout → Sidebar → Divi Handoff Layout Mapping

Settings

Setting	Type	Default	Description
Flexible Content Layout	Select	No Layout	The SCF/ACF Flexible Content layout this Divi layout renders

How to Configure

1. Go to Divi Handoff Layouts in the admin menu
2. Edit an existing layout or create a new one
3. In the sidebar, find the Divi Handoff Layout Mapping meta box
4. Select a Flexible Content layout from the dropdown
5. Publish or Update the layout

The dropdown displays all Flexible Content layouts from your SCF or ACF Pro field groups. Each option shows the layout label as defined in your field group.

tip

You can create multiple Divi Handoff Layouts that map to the same Flexible Content layout. This gives content editors the choice of different visual presentations for the same data structure.

Page Layout Selection

When editing a page that has Flexible Content fields, each Flexible Content row displays a Divi Handoff Layout dropdown.

Location

Edit any page with Flexible Content → Inside each Flexible Content row → Divi Handoff Layout dropdown

How It Works

1. Add or expand a Flexible Content row on your page
2. At the top of each row, find the Divi Handoff Layout dropdown
3. Select which Divi Handoff Layout should render this content row
4. The dropdown shows:
   • Use default layout - Uses the first available mapped layout
   • All Divi Handoff Layouts mapped to this Flexible Content type

Per-Row Control

Each Flexible Content row on a page can use a different Divi Handoff Layout. This means:

• A page with 5 content rows can use up to 5 different visual layouts
• Different instances of the same layout type can have different presentations
• Content editors control the visual style without touching the Divi Builder

The Mapping Workflow

Step 1: Create Flexible Content Structure (SCF/ACF)

Field Group: "Page Builder"
└── Flexible Content: "sections"
    ├── Layout: "Hero"
    │   ├── title (text)
    │   ├── subtitle (textarea)
    │   └── background_image (image)
    └── Layout: "Features"
        ├── heading (text)
        └── features (repeater)

Step 2: Create Divi Handoff Layouts

Create one or more Divi Handoff Layouts for each Flexible Content layout:

Divi Handoff Layout	Mapped To	Purpose
Hero - Centered	Hero	Centered text with full-width background
Hero - Left Aligned	Hero	Left-aligned text with side image
Hero - Minimal	Hero	Simple design with no background
Features - Grid	Features	3-column grid layout
Features - List	Features	Vertical list with icons

Step 3: Build Pages

On any page with the "Page Builder" field group:

1. Add Flexible Content rows (Hero, Features, etc.)
2. Fill in the content (title, subtitle, image, etc.)
3. Select the Divi Handoff Layout for each row
4. Enable Divi Handoff in the page settings
5. Publish and view

Multiple Layouts Per Content Type

One of the most powerful features of layout mapping is creating multiple visual options for the same content structure.

Example: Hero Section Variations

Content Structure (same for all):

• Title
• Subtitle
• Button text
• Background image

Visual Variations:

Layout Name	Description
Hero - Dark	Dark overlay, white text, centered
Hero - Light	Light background, dark text, left-aligned
Hero - Video	Background video instead of image
Hero - Split	Image on left, content on right

Each of these Divi Handoff Layouts maps to the same "Hero" Flexible Content layout. When adding content to a page, editors can choose which visual style fits best.

Technical Details

How Mapping Data is Stored

• On Divi Handoff Layouts: The dalb_layout_mapping post meta stores the Flexible Content layout ID
• On Pages: The dalb_layout_mapping post meta stores an array of selected Divi Handoff Layout IDs (one per Flexible Content row)

Layout Detection

When rendering a page, Divi Handoff:

1. Reads the Flexible Content field data
2. For each row, checks the selected Divi Handoff Layout
3. Queries for Divi Handoff Layouts mapped to that Flexible Content layout type
4. Renders the selected (or first available) layout with the row's field data

Common Patterns

One-to-One Mapping

The simplest pattern: one Divi Handoff Layout per Flexible Content layout.

• Hero → Hero Layout
• Features → Features Layout
• Testimonials → Testimonials Layout

Content editors don't need to make choices; each content type has one visual option.

Multiple Layout Options

Create 2-3 visual variations per content type:

• Hero → Hero Dark, Hero Light, Hero Minimal
• CTA → CTA Full Width, CTA Boxed

Content editors choose the best style for each instance.

Specialized Layouts

Create purpose-specific layouts for the same content structure:

• Team Member → Team Card, Team Full Bio, Team Simple
• Product Feature → Feature Highlight, Feature Compact, Feature with Demo

Troubleshooting

Layout Not Appearing in Dropdown

If a Divi Handoff Layout doesn't appear in the page dropdown:

1. Verify the layout is Published (not Draft)
2. Confirm a Flexible Content layout is selected in the Layout Mapping meta box
3. Ensure the page has the correct field group assigned

Wrong Layout Rendering

If the wrong layout renders on the frontend:

1. Edit the page
2. Check the Divi Handoff Layout dropdown for each Flexible Content row
3. Verify the correct layout is selected
4. Update the page

No Layouts Available

If the Layout Mapping dropdown shows no options:

1. Verify SCF or ACF Pro is installed and active
2. Check that you have at least one field group with a Flexible Content field
3. Ensure the Flexible Content field has at least one layout defined

What's Next

• Page Settings - Configure page-level Divi Handoff settings
• Global Settings - Set default behaviors and manage demo content
• Creating Handoff Layouts - Build Divi layouts for Flexible Content