Add/Remove Sample Layouts

As of Theme Blvd framework 2.5, the functions in this article have now been deprecated and will no longer work properly. — To add or remove sample layouts, it’s best to use the themeblvd_sample_layouts filter. Here’s a good example of how to modify sample layouts, from the Spark plugin.

Function Reference: themeblvd_add_sample_layout

This function will allow you to add a sample layout available for use when creating a new layout in the Layout Builder.

Usage
themeblvd_add_sample_layout( $layout_id, $layout_name, $preview, $sidebar_layout, $elements );
Parameters
$layout_id
(string) (required) ID for the sample layout.
Default: None
$layout_name
(string) (required) Name of sample layout.
Default: None
$preview
(string) (required) URL to the preview image.
Default: None
$sidebar_layout
(string) (required) The sidebar layout to start the sample layout with - full_width, sidebar_right, sidebar_left, double_sidebar, double_sidebar_right, or double_sidebar_left
Default: None
$elements
(array) (required) This is a multi-dimensional array that consists of the elements to be added to the sample layout. See examples below.
Default: None
Examples

For this function, I do actually have some good real-world examples I can pull from. In most of the premium themes I build with this framework, I usually add in a sample layout for each particular theme. I feel like this just makes each theme a little more unique by adding in a sample layout that’s used in the theme’s live demo for the homepage. This way, each of my theme demos has a slightly different homepage.

First, let’s check out a really basic example where we simply have a sample layout with a couple elements, but no default settings or anything in those elements. When the WordPress user uses the following sample layout, they’ll end up with a new layout with a Slider element in the featured area and a Tabs element in the primary area.

$elements = array(
	array(
		'type' => 'slider',
		'location' => 'featured'
	),
	array(
		'type' => 'tabs',
		'location' => 'primary'
	)
);
themeblvd_add_sample_layout( 'my_sample_layout', 'My Sample Layout', get_stylesheet_directory_uri().'/assets/images/my_sample_layout.png', 'full_width', $elements );

Things start to get a little trickier when you want to actually add in default settings to those elements included in your sample layout. Let’s look at an actual example sample layout that’s used within one of my themes, Swagger.

See code snippit: http://snippi.com/s/0w2762a

So you can see in this last example that things start to get complicated when trying to input the default values for the elements in your new sample layout, and that’s because you need to understand how the options actually get saved if you’re going to put in default values.

One way to understand this would be to setup your sample layout the way you want manually in the Layout Builder, and then do what you always do when trying to rummage through someone else’s code – throw in some print_r()‘s!

In your Child theme’s functions.php throw in the following code snippet temporarily. This will just print out the current registered options for each element when the layouts are displayed. After you’re done, delete the code snippet.

/**
 * This will print the current options at the top of each 
 * element when it's displayed on the frontend when viewing 
 * the layout builder.
 */

function my_builder_debug( $id, $options ){
	echo '<h3>Current Element Options</h3>';
	echo '<pre>';
	echo htmlspecialchars(print_r($options, true));
	echo '</pre>';
}
add_action( 'themeblvd_element_columns_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_content_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_divider_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_headline_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_grid_paginated_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_grid_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_grid_slider_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_list_paginated_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_list_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_post_list_slider_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_slider_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_slogan_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_tabs_top', 'my_builder_debug', 10, 2 );
add_action( 'themeblvd_element_tweet_top', 'my_builder_debug', 10, 2 );

Now view your layout on the frontend.

You can see there which options are actually present in each layout element and use that as a guide for how you’d format the “defaults” of your elements array. You don’t have to set all of the options; you only need to feed in the options you want to address.

So, for example, if we were adding in a sample layout that had a slider and a slogan element we wanted to change just the “button_text” for the slogan we would set it up like this:

$elements = array(
	array(
		'type' => 'slider',
		'location' => 'featured'
	),
	array(
		'type' => 'slogan',
		'location' => 'primary'
		'defaults' => array(
			'button_text' => 'My Starting Button Text'
		)
	)
);
themeblvd_add_sample_layout( 'my_sample_layout', 'My Sample Layout', get_stylesheet_directory_uri().'/assets/images/my_sample_layout.png', 'full_width', $elements );

Function Reference: themeblvd_remove_sample_layout

This function will allow you to remove one of the framework’s default sample layouts by the IDs referenced in the article, Default framework sample layouts.

Usage
themeblvd_remove_sample_layout( $layout_id );
Parameters
$layout_id
(string) (required) ID of sample layout to remove.
Default: None
Examples

This is a pretty straight forward example. Let’s say we just want to remove the “Business Homepage #1” sample layout so the WordPress user cannot select it when creating a new layout.

themeblvd_remove_sample_layout( 'business_1' );

Taking this further what if you feel like the whole concept of sample layouts is going to confuse your client, and you’d prefer to just remove them all.

themeblvd_remove_sample_layout( 'business_1' );
themeblvd_remove_sample_layout( 'business_2' );
themeblvd_remove_sample_layout( 'business_3' );
themeblvd_remove_sample_layout( 'business_4' );
themeblvd_remove_sample_layout( 'magazine_1' );
themeblvd_remove_sample_layout( 'magazine_2' );
themeblvd_remove_sample_layout( 'agency' );
themeblvd_remove_sample_layout( 'portfolio' );
themeblvd_remove_sample_layout( 'showcase' );
themeblvd_remove_sample_layout( 'orman' );
themeblvd_remove_sample_layout( 'mcalister' );
themeblvd_remove_sample_layout( 'webtreats' );

After doing this, assuming you haven’t added any of your own custom sample layouts, no sample layouts will exist. So now, when the WordPress user is adding a new layout in the Layout Builder, the entire Sample Layout feature won’t exist.