Skip to main content

Layout mapping system

The layout mapping system is the core mechanism that connects your SCF/ACF Flexible Content layouts to Divi visual designs. Understanding this system helps you create flexible, maintainable page designs.

What is Layout Mapping?​

Layout mapping creates a connection between:

  1. SCF/ACF Flexible Content Layout - The content structure (fields and data)
  2. Divi Handoff Layout - The visual design (how content appears)

When a page with Flexible Content is rendered, Divi Handoff looks up the mapping and uses the corresponding Divi layout to display the content.

┌─────────────────────────────────┐
│ SCF/ACF Flexible Content Layout │
│ "Hero Section"                  │
│ ├── Title (text)                │
│ ├── Description (textarea)      │
│ └── Background (image)          │
└─────────────────────────────────┘
               │
               │ Layout Mapping
               ▼
┌─────────────────────────────────┐
│ Divi Handoff Layout             │
│ "Hero Layout - Full Width"      │
│ ├── Section (background)        │
│ ├── Row                         │
│ │   └── Handoff Text (title)    │
│ │   └── Handoff Text (desc)     │
└─────────────────────────────────┘

Divi Handoff Layouts​

Divi Handoff Layouts are a custom post type (divi_handoff_layout) that you build using the Divi Builder. They serve as visual templates for rendering Flexible Content.

Key Characteristics​

  • Built with Divi 5 - Use all Divi modules, sections, and styling options
  • Contains Handoff modules - Special modules that auto-bind to Flexible Content sub-fields
  • Mapped to SCF/ACF layouts - Connected via the Layout Mapping meta box
  • Reusable - One Divi Handoff Layout can render many pages

Creating a Divi Handoff Layout​

  1. Go to Divi Handoff Layouts in the WordPress admin menu
  2. Click Add New
  3. Enter a descriptive title (e.g., "Hero Section - Centered")
  4. Open the Divi Builder
  5. Build your layout using Handoff modules or standard Divi modules
  6. In the Layout Mapping meta box, select the SCF/ACF layout this design represents
  7. Publish

One-to-Many Relationships​

A powerful feature of layout mapping is that you can create multiple Divi Handoff Layouts for the same SCF/ACF layout:

SCF/ACF Layout: "Hero Section"
     │
     ├── Divi Handoff Layout: "Hero - Full Width"
     ├── Divi Handoff Layout: "Hero - Split Screen"
     └── Divi Handoff Layout: "Hero - Video Background"

When content editors add a "Hero Section" to a page, they can choose which visual design to use. This provides:

  • Design flexibility - Different pages can look different
  • Consistent content - All hero sections have the same fields
  • Easy updates - Change a layout once, all pages using it update

How Mapping Works on Pages​

When editing a page with Flexible Content:

  1. Content editor adds a Flexible Content layout row (e.g., "Hero Section")
  2. A dropdown appears asking which Divi Handoff Layout to use
  3. Editor selects from available mapped layouts
  4. Editor fills in the content fields
  5. On the frontend, Divi Handoff renders the content using the selected visual layout
Page Editor View:
┌─────────────────────────────────────────────┐
│ Flexible Content: Page Sections             │
│ ┌─────────────────────────────────────────┐ │
│ │ + Add Row: Hero Section                 │ │
│ │                                         │ │
│ │ Divi Handoff Layout: [Hero - Centered ▼]│ │
│ │                                         │ │
│ │ Title: [Welcome to Our Site           ] │ │
│ │ Description: [We help businesses grow ] │ │
│ │ Background: [image.jpg                ] │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

The Layout Mapping Meta Box​

On Divi Handoff Layouts, a meta box appears that lets you select which SCF/ACF layout this visual design represents:

FieldDescription
SCF/ACF Pro Flexible Content LayoutDropdown showing all available Flexible Content layouts from your field groups

The dropdown displays layouts in the format:

Field Group Name - Flexible Content Field - Layout Name

For example:

  • Page Sections - Sections - Hero Section
  • Page Sections - Sections - Team Member
  • Page Sections - Sections - Testimonial

Page Settings for Divi Handoff​

For Divi Handoff to render on a page, you must enable it in the page settings:

  1. Edit the page
  2. Find the Divi Handoff Settings meta box
  3. Check Enable Divi Handoff on this page
  4. Configure additional options (sidebar, header, footer visibility)
  5. Save/Update the page

Without enabling Divi Handoff, the page will render normally without the Flexible Content visual layouts.

Mapping Best Practices​

Use Descriptive Names​

Name your Divi Handoff Layouts clearly:

  • ✅ "Hero Section - Full Width Dark"
  • ✅ "Team Member - Card Style"
  • ✅ "Testimonial - Quote with Photo"
  • ❌ "Layout 1"
  • ❌ "New Layout"

Create Variations​

For important content types, create multiple visual variations:

  • Hero sections - Full width, split screen, video background
  • Team members - Card, list, featured
  • Testimonials - Quote style, video, carousel item

Test Your Mappings​

Before publishing:

  1. Create a test page
  2. Add each Flexible Content layout type
  3. Verify each Divi Handoff Layout renders correctly
  4. Check all sub-fields display properly

What's Next​