Form Structure
Settings forms are defined when registering your module:FLBuilder::register_module('MyModule', array(
'tab-key' => array(
'title' => __( 'Tab Title', 'text-domain' ),
'sections' => array(
'section-key' => array(
'title' => __( 'Section Title', 'text-domain' ),
'fields' => array(
'field-key' => array(
'type' => 'text',
'label' => __( 'Field Label', 'text-domain' ),
),
),
),
),
),
));
Hierarchy
Tabs (General, Style, Advanced)
└── Sections (grouped settings)
└── Fields (individual inputs)
Tabs, Sections, and Fields
Complete Example
From the Button module:FLBuilder::register_module('FLButtonModule', array(
'general' => array(
'title' => __( 'General', 'fl-builder' ),
'sections' => array(
'general' => array(
'title' => '',
'fields' => array(
'text' => array(
'type' => 'text',
'label' => __( 'Text', 'fl-builder' ),
'default' => __( 'Click Here', 'fl-builder' ),
'preview' => array(
'type' => 'text',
'selector' => '.fl-button-text',
),
'connections' => array( 'string' ),
),
'icon' => array(
'type' => 'icon',
'label' => __( 'Icon', 'fl-builder' ),
'show_remove' => true,
'show' => array(
'fields' => array( 'icon_position', 'icon_animation' ),
),
),
'icon_position' => array(
'type' => 'select',
'label' => __( 'Icon Position', 'fl-builder' ),
'default' => 'before',
'options' => array(
'before' => __( 'Before Text', 'fl-builder' ),
'after' => __( 'After Text', 'fl-builder' ),
),
),
),
),
),
),
'style' => array(
'title' => __( 'Style', 'fl-builder' ),
'sections' => array(
'colors' => array(
'title' => __( 'Colors', 'fl-builder' ),
'fields' => array(
'bg_color' => array(
'type' => 'color',
'label' => __( 'Background Color', 'fl-builder' ),
'show_reset' => true,
'show_alpha' => true,
),
),
),
),
),
));
Common Field Types
Text Fields
'title' => array(
'type' => 'text',
'label' => __( 'Title', 'text-domain' ),
'default' => '',
'placeholder' => __( 'Enter title...', 'text-domain' ),
'maxlength' => 100,
'preview' => array(
'type' => 'text',
'selector' => '.my-title',
),
'connections' => array( 'string' ),
),
Select Fields
'alignment' => array(
'type' => 'select',
'label' => __( 'Alignment', 'text-domain' ),
'default' => 'left',
'options' => array(
'left' => __( 'Left', 'text-domain' ),
'center' => __( 'Center', 'text-domain' ),
'right' => __( 'Right', 'text-domain' ),
),
),
Color Fields
'text_color' => array(
'type' => 'color',
'label' => __( 'Text Color', 'text-domain' ),
'default' => '',
'show_reset' => true,
'show_alpha' => true,
'responsive' => true,
'preview' => array(
'type' => 'css',
'selector' => '.my-module',
'property' => 'color',
),
'connections' => array( 'color' ),
),
Media Fields
'photo' => array(
'type' => 'photo',
'label' => __( 'Photo', 'text-domain' ),
'show_remove' => true,
'connections' => array( 'photo' ),
),
Link Field
'button_link' => array(
'type' => 'link',
'label' => __( 'Button Link', 'text-domain' ),
'placeholder' => 'https://example.com',
'show_target' => true,
'show_nofollow' => true,
'show_download' => true,
'preview' => array(
'type' => 'none',
),
'connections' => array( 'url' ),
),
Icon Field
'icon' => array(
'type' => 'icon',
'label' => __( 'Icon', 'text-domain' ),
'show_remove' => true,
'show' => array(
'fields' => array( 'icon_size', 'icon_color' ),
),
),
Measurement Fields
'width' => array(
'type' => 'unit',
'label' => __( 'Width', 'text-domain' ),
'default' => '300',
'responsive' => true,
'slider' => array(
'px' => array(
'min' => 0,
'max' => 1000,
'step' => 10,
),
),
'units' => array( 'px', '%', 'vw' ),
'preview' => array(
'type' => 'css',
'selector' => '.my-module',
'property' => 'width',
),
),
Compound Fields
'heading_typography' => array(
'type' => 'typography',
'label' => __( 'Typography', 'text-domain' ),
'responsive' => true,
'preview' => array(
'type' => 'css',
'selector' => '.my-heading',
),
),
Conditional Logic
Show/Hide Fields
Control field visibility based on other field values:'click_action' => array(
'type' => 'select',
'label' => __( 'Click Action', 'text-domain' ),
'default' => 'link',
'options' => array(
'link' => __( 'Link', 'text-domain' ),
'lightbox' => __( 'Lightbox', 'text-domain' ),
),
'toggle' => array(
'link' => array(
'fields' => array( 'link_url' ),
),
'lightbox' => array(
'fields' => array( 'lightbox_content' ),
'sections' => array( 'lightbox_settings' ),
),
),
),
Field Dependencies
Use theshow parameter to display fields when another field has a value:
'enable_icon' => array(
'type' => 'select',
'label' => __( 'Enable Icon', 'text-domain' ),
'default' => 'no',
'options' => array(
'yes' => __( 'Yes', 'text-domain' ),
'no' => __( 'No', 'text-domain' ),
),
'toggle' => array(
'yes' => array(
'fields' => array( 'icon', 'icon_position' ),
),
),
),
Field Properties
Common Properties
These properties work with most field types:| Property | Type | Description |
|---|---|---|
type | string | Field type (required) |
label | string | Field label |
default | mixed | Default value |
help | string | Help text below field |
description | string | Description text |
placeholder | string | Placeholder text |
preview | array | Live preview configuration |
connections | array | Themer connection types |
responsive | bool | Enable responsive editing |
Preview Configuration
'preview' => array(
'type' => 'refresh',
),
Real-World Form Examples
- Button Module
- Heading Module
FLBuilder::register_module('FLButtonModule', array(
'general' => array(
'title' => __( 'General', 'fl-builder' ),
'sections' => array(
'general' => array(
'title' => '',
'fields' => array(
'text' => array(
'type' => 'text',
'label' => __( 'Text', 'fl-builder' ),
'default' => __( 'Click Here', 'fl-builder' ),
'connections' => array( 'string' ),
),
'click_action' => array(
'type' => 'select',
'label' => __( 'Click Action', 'fl-builder' ),
'default' => 'link',
'options' => array(
'link' => __( 'Link', 'fl-builder' ),
'lightbox' => __( 'Lightbox', 'fl-builder' ),
),
'toggle' => array(
'link' => array(
'fields' => array( 'link' ),
),
'lightbox' => array(
'sections' => array( 'lightbox' ),
),
),
),
'link' => array(
'type' => 'link',
'label' => __( 'Link', 'fl-builder' ),
'show_target' => true,
'show_nofollow' => true,
),
),
),
),
),
'style' => array(
'title' => __( 'Style', 'fl-builder' ),
'sections' => array(
'colors' => array(
'title' => __( 'Colors', 'fl-builder' ),
'fields' => array(
'text_color' => array(
'type' => 'color',
'label' => __( 'Text Color', 'fl-builder' ),
'show_reset' => true,
'show_alpha' => true,
),
'bg_color' => array(
'type' => 'color',
'label' => __( 'Background Color', 'fl-builder' ),
'show_reset' => true,
'show_alpha' => true,
),
),
),
),
),
));
FLBuilder::register_module('FLHeadingModule', array(
'general' => array(
'title' => __( 'General', 'fl-builder' ),
'sections' => array(
'general' => array(
'title' => '',
'fields' => array(
'heading' => array(
'type' => 'text',
'label' => __( 'Heading', 'fl-builder' ),
'connections' => array( 'string' ),
),
'tag' => array(
'type' => 'select',
'label' => __( 'HTML Tag', 'fl-builder' ),
'default' => 'h2',
'options' => array(
'h1' => 'h1',
'h2' => 'h2',
'h3' => 'h3',
'h4' => 'h4',
'h5' => 'h5',
'h6' => 'h6',
),
),
'link' => array(
'type' => 'link',
'label' => __( 'Link', 'fl-builder' ),
'show_target' => true,
'show_nofollow' => true,
),
),
),
),
),
'style' => array(
'title' => __( 'Style', 'fl-builder' ),
'sections' => array(
'colors' => array(
'title' => '',
'fields' => array(
'color' => array(
'type' => 'color',
'label' => __( 'Color', 'fl-builder' ),
'show_reset' => true,
'show_alpha' => true,
'responsive' => true,
),
'typography' => array(
'type' => 'typography',
'label' => __( 'Typography', 'fl-builder' ),
'responsive' => true,
),
),
),
),
),
));
Responsive Settings
Many field types support responsive editing:'width' => array(
'type' => 'unit',
'label' => __( 'Width', 'text-domain' ),
'responsive' => true, // Enable responsive breakpoints
'default' => '100',
),
// Desktop value
$settings->width
// Tablet value
$settings->width_medium
// Mobile value
$settings->width_responsive
Themer Connections
Enable dynamic content with Themer:'title' => array(
'type' => 'text',
'label' => __( 'Title', 'text-domain' ),
'connections' => array( 'string', 'html' ),
),
'photo' => array(
'type' => 'photo',
'label' => __( 'Photo', 'text-domain' ),
'connections' => array( 'photo' ),
),
'link' => array(
'type' => 'link',
'label' => __( 'Link', 'text-domain' ),
'connections' => array( 'url' ),
),
Best Practices
Organization
- Group related settings in sections
- Use clear, descriptive labels
- Order fields logically
- Keep tabs focused and concise
User Experience
- Provide sensible defaults
- Add helpful descriptions
- Use conditional logic to reduce clutter
- Enable live preview when possible
Performance
- Use ‘none’ preview for heavy operations
- Limit ‘refresh’ preview types
- Keep default values lightweight
- Avoid complex calculations in forms
Accessibility
- Use clear, descriptive labels
- Provide help text for complex settings
- Ensure logical tab order
- Test with keyboard navigation
Next Steps
Frontend Rendering
Learn how to use settings in your frontend templates