Overview
The Theme Builder extension (fl-theme-builder-core) provides the foundation for creating custom theme layouts including headers, footers, singular post templates, and archive pages. It includes powerful field connection capabilities that allow you to display dynamic content from posts, archives, and site data.
The Theme Builder core is included in Beaver Builder Pro and above. It provides essential functionality even when the full Theme Builder add-on is not installed.
Core Classes
The Theme Builder extension consists of several key classes:
FLThemeBuilderFieldConnections
Handles the base logic for connecting fields in the builder UI to dynamic data such as post titles, custom fields, and more.
Location : fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:9
final class FLThemeBuilderFieldConnections {
static private $menu_data = array ();
static private $connected_settings = array ();
static private $page_data_object_keys = array ();
static public $in_post_grid_loop = null ;
}
FLPageData
Manages all data related to the current page including posts, archives, and site information.
Location : fl-theme-builder-core/classes/class-fl-page-data.php:9
final class FLPageData {
static private $groups ; // Property groups
static private $properties ; // Registered properties
static private $values ; // Cached values
static private $settings = null ; // Current property settings
}
FLThemeBuilderLayoutData
Handles logic for theme layout data and determines which layouts apply to the current page.
Location : fl-theme-builder-core/classes/class-fl-theme-builder-layout-data.php:8
FLThemeBuilderRulesLocation
Handles location rule logic for determining where theme layouts should be displayed.
Location : fl-theme-builder-core/classes/class-fl-theme-builder-rules-location.php:8
Field Connections
Field connections allow you to connect module settings to dynamic data sources.
Supported Connection Types
Basic Types
Compound Types
string - Text content
photo - Images and media
url - Links and URLs
html - Rich HTML content
color - Color values
border - Border settings
gradient - Gradient definitions
typography - Typography settings
background - Background properties
Supported Compound Fields
Compound fields that support field connections (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:54):
static private $supported_compound_fields = array (
'border' ,
'gradient' ,
'typography' ,
'background' ,
);
Initializing Field Connections
Field connections are initialized with hooks (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:67):
static public function init () {
// Actions
add_action ( 'wp' , __CLASS__ . '::connect_all_layout_settings' );
add_action ( 'fl_builder_before_control' , __CLASS__ . '::render_connection' , 10 , 4 );
// Filters
add_filter ( 'fl_builder_node_settings' , __CLASS__ . '::connect_node_settings' , 10 , 2 );
add_filter ( 'fl_builder_before_render_shortcodes' , __CLASS__ . '::parse_shortcodes' );
// Shortcodes
add_shortcode ( 'wpbb' , __CLASS__ . '::parse_shortcode' );
add_shortcode ( 'wpbb-if' , __CLASS__ . '::parse_conditional_shortcode' );
}
Creating Theme Templates
Layout Types
Theme Builder supports several layout types:
Singular Templates for individual posts, pages, and custom post types
Archive Templates for category, tag, and custom taxonomy archives
Header Custom header layouts (requires theme support)
Footer Custom footer layouts (requires theme support)
Part Reusable theme parts that can be hooked anywhere
404 Custom 404 error page templates
Checking Layout Support
From fl-theme-builder-core/classes/class-fl-theme-builder-layout-data.php:51:
static public function is_layout_supported ( $post_id ) {
$type = get_post_meta ( $post_id , '_fl_theme_layout_type' , true );
if ( ! $type ) {
return false ;
} elseif ( 'header' == $type ) {
return get_theme_support ( 'fl-theme-builder-headers' );
} elseif ( 'footer' == $type ) {
return get_theme_support ( 'fl-theme-builder-footers' );
} elseif ( 'part' == $type ) {
return get_theme_support ( 'fl-theme-builder-parts' );
}
return true ;
}
Working with Page Data
Property Groups
Page data is organized into groups (from fl-theme-builder-core/classes/class-fl-page-data.php:77):
self :: $groups = array (
'general' => array ( 'label' => __ ( 'General' , 'fl-builder' ) ),
'archives' => array ( 'label' => __ ( 'Archives' , 'fl-builder' ) ),
'posts' => array ( 'label' => __ ( 'Posts' , 'fl-builder' ) ),
'comments' => array ( 'label' => __ ( 'Comments' , 'fl-builder' ) ),
'author' => array ( 'label' => __ ( 'Author' , 'fl-builder' ) ),
'site' => array ( 'label' => __ ( 'Site' , 'fl-builder' ) ),
'user' => array ( 'label' => __ ( 'User' , 'fl-builder' ) ),
'advanced' => array ( 'label' => __ ( 'Advanced' , 'fl-builder' ) ),
'term' => array ( 'label' => __ ( 'Term' , 'fl-builder' ) ),
);
Adding Custom Properties
Post Property
Site Property
Archive Property
FLPageData :: add_post_property ( 'custom_field' , array (
'label' => __ ( 'Custom Field' , 'textdomain' ),
'group' => 'posts' ,
'type' => 'string' ,
'getter' => function () {
return get_post_meta ( get_the_ID (), 'custom_field_key' , true );
},
));
Add settings forms to properties for additional customization:
FLPageData :: add_post_property_settings_fields ( 'custom_field' , array (
'key' => array (
'type' => 'text' ,
'label' => __ ( 'Field Key' , 'textdomain' ),
),
'default' => array (
'type' => 'text' ,
'label' => __ ( 'Default Value' , 'textdomain' ),
),
));
Using Shortcodes
Basic Shortcode
The [wpbb] shortcode connects to field data:
// Display post title
[ wpbb post : title ]
// Display custom field
[ wpbb post : custom_field key = 'my_field' ]
// Display with default
[ wpbb post : custom_field key = 'my_field' default = 'No value' ]
// Display site info
[ wpbb site : title ]
Conditional Shortcode
The [wpbb-if] shortcode for conditional display:
// Show content if field exists
[ wpbb - if post : featured_image ]
< img src = "[wpbb post:featured_image]" />
[ / wpbb - if ]
// Show content if field doesn't exist
[ wpbb - if ! post : custom_field ]
Default content here
[ / wpbb - if ]
// With else clause
[ wpbb - if post : excerpt ]
[ wpbb post : excerpt ]
[ wpbb - else ]
No excerpt available .
[ / wpbb - if ]
CSS Variables
Field connections can output as CSS variables (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:784):
// Connect field to CSS var
static public function connect_css_var ( $data ) {
$property = FLPageData :: get_property ( $data -> object , $data -> property );
// Build CSS var key
$key = self :: get_css_var_key ( $data ); // e.g., --fl-post-title
$value = self :: get_css_var_value ( $data , $property );
// Register the var
FLBuilderCSSVars :: register ( $key , $value );
}
CSS variable format (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:814):
static public function get_css_var_key ( $data ) {
$object = $data -> object ; // 'post', 'archive', 'site'
$property = $data -> property ; // 'title', 'excerpt', etc.
$suffix = '' ; // Additional identifier
return str_replace ( '_' , '-' , sanitize_key ( "--fl- $object - $property$suffix " ) );
}
Connection Caching
Connected settings are cached to prevent redundant processing (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:526):
// Return cached connections?
if ( isset ( self :: $connected_settings [ $cache_key ] ) ) {
return self :: $connected_settings [ $cache_key ];
}
// Connect the settings
$settings = self :: connect_settings ( $settings );
// Cache the connected settings
self :: $connected_settings [ $cache_key ] = $settings ;
Query Optimization
Layout settings are connected before rendering (from fl-theme-builder-core/classes/class-fl-theme-builder-field-connections.php:410):
// Connect all layout node settings before the page renders
static public function connect_all_layout_settings () {
$layout_ids = FLThemeBuilderLayoutData :: get_current_page_layout_ids ();
while ( have_posts () ) {
the_post ();
foreach ( $layout_ids as $layout_id ) {
$data = FLBuilderModel :: get_layout_data ( $node_status , $layout_id );
foreach ( $data as $node ) {
FLBuilderModel :: get_node_settings ( $node );
}
}
}
rewind_posts ();
}
Hooks & Filters
Actions
// Before connecting all layout settings
do_action ( 'fl_builder_before_render_ajax_layout' );
// Add custom page data properties
do_action ( 'fl_page_data_add_properties' );
// Before rendering a field connection
do_action ( 'fl_builder_before_control' , $name , $value , $field , $settings );
Filters
// Modify connected node settings
apply_filters ( 'fl_builder_node_settings' , $settings , $node );
// Modify current page layouts
apply_filters ( 'fl_theme_builder_current_page_layouts' , $layouts );
// Modify cache key for connections
apply_filters ( 'fl_themer_builder_connect_node_settings_cache_key' , $cache_key , $settings , $node );
When using the fl_page_data_add_properties hook, make sure to add properties on or after the wp action to ensure WordPress query variables are available.
Examples
Complete Custom Property Example
add_action ( 'fl_page_data_add_properties' , 'my_custom_properties' );
function my_custom_properties () {
// Add property group
FLPageData :: add_group ( 'my_group' , array (
'label' => __ ( 'My Properties' , 'textdomain' ),
));
// Add post property
FLPageData :: add_post_property ( 'reading_time' , array (
'label' => __ ( 'Reading Time' , 'textdomain' ),
'group' => 'my_group' ,
'type' => 'string' ,
'getter' => function () {
$content = get_the_content ();
$word_count = str_word_count ( strip_tags ( $content ) );
$reading_time = ceil ( $word_count / 200 );
return $reading_time . ' min read' ;
},
));
// Add settings form
FLPageData :: add_post_property_settings_fields ( 'reading_time' , array (
'suffix' => array (
'type' => 'text' ,
'label' => __ ( 'Suffix' , 'textdomain' ),
'default' => 'min read' ,
),
));
}
Connecting Settings Programmatically
// Create a connection object
$connection = ( object ) array (
'object' => 'post' ,
'property' => 'title' ,
'field' => 'text' ,
);
// Get the property
$property = FLPageData :: get_property ( $connection -> object , $connection -> property );
// Get the value
$value = FLPageData :: get_value ( $connection -> object , $connection -> property );
Next Steps
Cloud Templates Learn about cloud template integration
White Label Customize branding for client sites