Genesis Explained Layout Functions

As promised in my previous post in the Genesis Explained series, I’m going to be going through the genesis/lib/functions/layout.php file today. I intentionally went out of order with this because it is helpful to be familiar with the concept of sidebars and the functions Genesis uses regarding them before trying to understand layouts. There are 9 functions in the file and only 1 is part of an existing hook. The rest involve creating, removing, and checking layout options. This is very helpful in working with Genesis since you can select layouts for individual posts, pages, and terms. This means you can create whole new layouts without resorting to templates.

First things being first, let’s look at the layout functions

• genesis_create_initial_layouts: The only function that is part of a hook, created the default layouts
• genesis_register_layout: registers a new layout
• genesis_set_default_layout: sets a default layout
• genesis_unregister_layout: removes an existing layout option
• genesis_get_layouts: returns an array of all registered layout options
• genesis_get_layout: returns information about a specific layout
• genesis_get_default_layout: returns default layout
• genesis_site_layout: returns the selected layout
• genesis_structural_wrap: creates a wrapper div

Many of these functions are back end operators, but there are some really cool front end features too. Before we get into that I want to quickly go through the default layouts, so breaking with tradition check out the first function, which is part of an action hook.

genesis_create_initial_layouts()

This is a series of “genesis_register_layout()” functions creating the initial layouts. Looking at this code will help clarify how that function works, which we’ll get into later, but also tells us the correct ID for all the defaults, which we need to know if we will unregister any layouts or need to setup a conditional action based on the current layout. Here they are in a nice pretty list (name: ID).

• Content/Sidebar: content-sidebar
• Sidebar/Content: sidebar-content
• Content/Sidebar/Sidebar: content-sidebar-sidebar
• Sidebar/Sidebar/Content: sidebar-sidebar-content
• Sidebar/Content/Sidebar: sidebar-content-sidebar
• Full Width Content: full-width-content

Now a bit about naming conventions. The labels could have been anything, it doesn’t have to accurately describe the layout. PHP doesn’t care so long as you get the information correct on both ends. Where it matters is the developer and user experience. The label needs to be brief and descriptive so the user will understand what each option does more or less intuitively. The ID should reflect the label using web standards (lower case, no spaces, doesn’t start with a number). Sure it could be “one, two, three, …” but that makes it harder when writing the code. By following a naming convention like “Sidebar/Content” and “sidebar-content” then it is much more intuitive resulting in cleaner code and less debugging.

genesis_register_layout( $id = ”, $args = array() )

This is a deceptively simple function. The first arg sets the ID. remember, this should follow web standards and describe your layout. The second is optional, but you should use it. $args are passed as an array and ideally will have both the ‘label’ and ‘img’ value filled in. If not provided your layout will get the label “No Label Selected” and a blank image. The image can be anything, but I like to work with the concept of blending the options for a better end user experience, so I recommend taking the existing full width content and breaking it down into sections like the other layout options to accurately reflect that layout. Here is a sample code, assuming the image is places in an images/layouts/ directory for the child theme

	genesis_register_layout( 'top-sidebar-content-sidebar', array(
		'label' => __('Top/Sidebar/Content/Sidebar', 'genesis'),
		'img' => CHILD_URL . '/images/layouts/tscs.gif',
	) );

One more bit, a kind of bonus if you would. You could add additional strings in the array if you want. Those will be returned for use later if you need them. Normally I don’t worry about that but it is something that could theoretically be done.

genesis_set_default_layout( $id = ” )

Developer’s Friend

Ever setup a site and have the client break it because they clicked reset or changes options? Using defaults like this makes for a quick recovery

This function does tow important things. It sets a default layout, it unsets the existing default. The default only applies when a theme is first activates or if the “reset” button is pressed in the Genesis Theme Settings.

So how do we use this? Well it is simple as pie (not to be confused with pi, which is very not simple)

genesis_set_default_layout( 'top-sidebar-content-sidebar' );

That will set the layout we created previously as the default. That’s all. Now if your client clicks the reset button to see what happens, at least this option stays safe.

genesis_unregister_layout( $id = ” )

Remember in the previous article when I talked about removing a sidebar? How confusing would it be to remove the sidebar-alt but leave those options that should show the sidebar-alt? This function exists to get rid of layouts you don’t need.

genesis_unregister_layout( 'sidebar-sidebar-content' );

That one removes the Sidebar/Sidebar/Content layout, make a set of those to clear out any of the other layouts you don’t want/need in your theme.

genesis_get_layouts()

Notice that this function doesn’t have any args, it is a “getter” that means it returns something so you can use it. There are no options because there is no way to change what is being returned, and that’s ok. It exists to give you an object (array) with all the layouts and the associated information, like the ID, label, and image. Mostly this is a helper function used in creating the user selectable layout options in wp-admin screens.

genesis_get_layout( $id )

This returns a specific layout. You could just use genesis_get_layouts() and then retrieve your specific layout from that, but that is an extra step you don’t need to take. The information returned is an object (array) as well.

genesis_get_default_layout()

Returns the default layout. Again, this is mostly a helper function used in Genesis admin. You could theoretically use it to create many other functions, including something that checks to see if the current layout has been changed.

genesis_site_layout()

This is a very helpful functions that returns the current selected layout. This will return the Genesis Theme Settings selected option if it isn’t being overridden by the archive/singular selected option. You need to use this with your hooks if you add new layouts. For example:

add_action( 'genesis_before_content_sidebar_wrap', 'child_top_sidebar' );
function child_top_sidebar() {

$layout = genesis_site_layout();

if( 'top-sidebar-content-sidebar' == $layout ) {

    echo '<div id="top-sidebar">';
        dynamic_sidebar( 'top-sidebar' );
    echo '</div>';

}
}

genesis_structural_wrap( $context = ”, $output = ‘

‘, $echo = true )

This is a new to Genesis 1.6 function. It helps create a wrap in or around elements. You might want to use this for the top-sidebar. The first step is to make sure the theme supports it.

add_theme_support( 'genesis-structural-wraps', array( 'top-sidebar' ) );

The code above could be amended like

    genesis_structural_wrap( 'top-sidebar', 'open' );
        dynamic_sidebar( 'top-sidebar' );
    genesis_structural_wrap( 'top-sidebar', 'close' );

This would nest it in a simple div with the class .wrap. You can change the markup in the “open” and “close” to create your unique html divs, IDs, classes, …

This wraps up the functions subseries in the Genesis Explained series. Next we are diving into the admin folder and learning how to work with meta boxes in the theme settings and the posts, pages, and terms.

For now, remember to subscribe so you don’t miss any updates, and add your thoughts to the child theme wish list.