Bricks Builder Useful Functions And Tips

Some useful functions and tips available in Bricks theme that I always use.

Please note that I only use them in Bricks v1.5 beta and above. Some of them might not be available in older version.

Bricks Builder Check

bricks_is_frontend()

• Simply check if currently in frontend, return true.

bricks_is_builder_call()

• If current request call via AJAX or REST by Bricks, return true.
• I always use this to do some rendering in the backend builder screen. Help me decide which way to retrieve the correct post Id when I am using filter on Bricks element. Sometimes your element filter output works well in frontend but not rendering in backend builder mode, then I will use this function to check and get the correct post Id from somewhere else.

Bricks Builder Query Loop

Query loop is very useful in Bricks Builder. With the below available functions, I feel much much much more comfortable when doing some customization via codes.

global $bricks_loop_query

• $bricks_loop_query stores all executed query loop in a page.
• It’s an Array and the keys are unique query_id.
• query_id is not fixed / persistent, will be changed upon page refresh.
• Query loop array will be added into $bricks_loop_query “just in time”. Which means you cannot get future query from $bricks_loop_query if it’s not executed yet.
• $bricks_loop_query will be destroyed / unset after completed the loop. (You wouldn’t be able to retrieve it with the query_id key after the loop)

\Bricks\Query::get_loop_object_type( $query_id )

• Example return results are “post”, “term”, “user” etc.
• Do you know that actually we can pass a query Id as the parameter to get the looping object type? It’s very handy in certain scenarios.
• Without providing $query_id, It will return the current looping object’s type.

\Bricks\Query::get_loop_object( $query_id )

• Return the object itself. (WP_Post object, WP_Term object etc)

• It will return the current looping object if no $query_id provided.

\Bricks\Query::get_loop_object_id( $query_id )

• Directly extract the Id of the query object.
• Same like previous function, returning current looping object’s Id if no $query_id provided.

\Bricks\Query::is_looping()

• Return true if use this on a looping element rendering filter.
• Please note that it will be false if using on query filters like bricks/posts/query_vars
• Usually I will use in bricks/element/settings filter, to change some element’s settings dynamically if it’s looping.
• You can also check if a specific element_id is looping now. \Bricks\Query::is_looping( ‘vfiqrn’ )

Below example remove the term link in a specific query loop

// Disable post_terms_category term link in a specific query loop
add_filter( 'bricks/dynamic_data/post_terms_links', function($has_links, $post, $taxonomy){
	if( $taxonomy !== 'category' || ! \Bricks\Query::is_looping('vfiqrn') ) return $has_links;

	return false;
}, 10, 3);

\Bricks\Query::is_any_looping()

• I just found this function recently. It can return the nearest or I can say current looping query Id.
• The unique query Id is the key of global $bricks_loop_query array I explained earlier.
• With this super useful function, I wrote my helper function to get any level or parent query loop Info when needed.
• This can retrieve the current looping query Id even in bricks/element/settings filter! You can easily use this to achieve nested query loop in a more flexible and dynamic way. Use case will be shared in future.

Below is my own helper function to get the parent / father query loop query Id when necessary.

// My own helper function to get looping parent query Id by level

function itchy_get_bricks_looping_parent_query_id_by_level( $level = 1 ) {
	global $bricks_loop_query;

	if ( empty( $bricks_loop_query ) || $level < 1 ) {
		return false;
	}

	$current_query_id = \Bricks\Query::is_any_looping();
	
	if ( !$current_query_id ) { 
		return false;
	}
	
	if ( !isset( $bricks_loop_query[ $current_query_id ] ) ) {
		return false;
	}

	$query_ids = array_reverse( array_keys( $bricks_loop_query ) );

	if ( !isset( $query_ids[ $level ] )) {
		return false;
	}

	if ( $bricks_loop_query[ $query_ids[ $level ] ]->is_looping ) {
		return $query_ids[ $level ];
	}

	return false;
}

Now, I can use itchy_get_bricks_looping_parent_query_id_by_level() to get “father” of current loop, or itchy_get_bricks_looping_parent_query_id_by_level(2) to get “grandfather” of current loop. Please use this only within the query loop before completed, otherwise you will be getting false result because of destroy function.

Bricks Builder Element’s Post Id

In many cases, you might find that some dynamic data wouldn’t work as expected in Bricks but the logic or code actually correctly written. Especially when you use get_the_ID() to retrieve current post Id. This is because Bricks got it’s own logic to decide what should be the correct post Id when rendering the element, and Bricks will save this into each element’s property named post_id. ($element->post_id)

Generally, based on my understanding, this post_id can be easily changed by using bricks/builder/data_post_id filter. (I did show how to use this in my Bricks Builder popup modal tutorial.)

Based on my experimental experiences, I feel this way is much more reliable if we really need to change the $element->post_id.

<?php

// If I need to change the $element->post_id to global $product->get_id()
global $product;

// Just to make sure it's a WC_Product object so I can use get_id()
if( !is_a( $product, 'WC_Product') ) return;

\Bricks\Database::set_page_data( $product->get_id() );

// Or a much brutal way 
\Bricks\Database::$page_data['post_id'] = $product->get_id();
\Bricks\Database::$page_data['original_post_id'] = $product->get_id();
\Bricks\Database::$page_data['preview_or_post_id'] = $product->get_id();

Be careful when doing this as all the codes after above actions might cause some side effects. If you want to see how I use these in an actual scenario, please read this article in BricksLabs, WooCommerce Product Loop Template In Bricks.

Bricks Templates

\Bricks\Database::$active_templates

• This will return array to tell you which Bricks template should use for current page / post.
• Ex: header => 9, footer => 474, content => 0. Means header template ID is 9, footer template ID is 474, and no template being use for the content.

\Bricks\Templates::get_templates()

• Return all templates and their settings created in Bricks.
• You can use this to populate a dropdown options to be used in some customization scenario.

//Example function I use to build a dropdown options for Metabox select field
function itchy_get_bricks_templates() {
	$templates = \Bricks\Templates::get_templates();
	$options = [
		'0' => esc_html__( 'None', 'itchycode' ),
	];
	foreach( $templates as $template ) {
		$options[$template['id']] = "{$template['id']}: {$template['title']}";
	}
	return $options;
}

\Bricks\Templates::get_templates_by_type( $type )

• Return the template IDs in array for certain type.
• The $type parameter can be a string or array. \Bricks\Templates::get_templates_by_type( 'content') or \Bricks\Templates::get_templates_by_type( ['content', 'section'])
• Ex: \Bricks\Templates::get_templates_by_type( 'header' ) with result 9, Means I only got 1 header template with ID 9

\Bricks\Helpers::get_template_settings( $template_id )

• Return the settings (in array) defined in the Builder mode >Settings (gear icon) > Template Settings.

\Bricks\Helpers::get_template_setting( $setting_key, $template_id )

• This is just a shorthand to get the template’s setting key based on the previous result.
• Ex: \Bricks\Helpers::get_template_setting( 'templateConditions', 103 ) will directly return the templateConditions array key from \Bricks\Helpers::get_template_settings(103)

\Bricks\Element_Template::get_builder_call_additional_data( $template_id )

• Very cool function since v1.5. This will return 2 arrays with keys elements and css.
• I can easily retrieve the generated CSS from the specific template (Imagine you want to output a template via AJAX which it’s CSS not loaded yet in page load)
• Actual example please refer to my Bricks Popup Modal tutorial.

Bricks Frontend Rendering

If you decided to reuse the Bricks elements without set them up via builder mode or store in database. We can achieve this in 2 different ways.

Method 1: Initialize the element class directly

If I want to output a Bricks Button element, I must need to know what are the accepted settings and also the button element class. (\Bricks\Element_Button)

// We must need to know what settings accepted by the element and configured accordingly
$button_settings = array(
	'text' => 'Click me',
	'style' => 'primary',
	'size' => 'small',
	'icon' => array(
		'library' => 'themify',
		'icon' => 'ti-bookmark'
	),
	'iconPosition' => 'left',
	'link' => array(
		'type' => 'external',
		'url' => '#'
	),
	'circle' => true,
	'block' => true
);

// Initialize the Bricks Button class with our settings
$new_button = new \Bricks\Element_Button( ['settings' => $button_settings] );

// Setup frontend actions and filters for the element if any
$new_button->load();

ob_start();

// Enqueue the necessary scripts & styles, populate and output the HTML
$new_button->init();

echo ob_get_clean();

Method 2: Use \Bricks\Frontend::render_element( $element )

// Button Example
$button_settings = array(
	'text' => 'Click me',
	'style' => 'primary',
	'size' => 'small',
	'icon' => array(
		'library' => 'themify',
		'icon' => 'ti-bookmark'
	),
	'iconPosition' => 'left',
	'link' => array(
		'type' => 'external',
		'url' => '#'
	),
	'circle' => true,
	'block' => true
);

$button_element = array(
	'id' => \Bricks\Helpers::generate_random_id(false), // optional
	'name' => 'button',
	'settings' => $button_settings,
	'children' => [],
	'parent' => 0
);

echo \Bricks\Frontend::render_element( $button_element );


// Icon Example
// I directly placed the settings into $icon_element variable
$icon_element = array(
	'name' => 'icon',
	'settings' => array(
		'icon' => array(
			'library' => 'themify',
			'icon' => 'ti-bookmark'
		),
		'link' => array(
			'type' => 'external',
			'url' => '#'
		)
	),
	'children' => [],
	'parent' => 0
);

echo \Bricks\Frontend::render_element( $icon_element );

Bricks Dynamic Data

bricks_render_dynamic_data( $content_string, $post_id = 0, $context = 'text' )

• This function added since v1.5.5.
• Actually it’s the same as \Bricks\Integrations\Dynamic_Data\Providers::render_content( $content, $post_id, 'text' )
• Ignore the last parameter, because it wasn’t in used currently.
• Practical usage in this tutorial.

// Render a dynamic data
$rendered_content = bricks_render_dynamic_data( '{your_dynamic_data_tag}', 12 );
echo $rendered_content; // You will get post ID 12's dynamic_data