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.
Comments
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.
Boomboom says
I finally got to finish all the articles in detail. Thanks again Nick. Hope to see more Genesis Articles.
Nate says
Great article! Thanks Nick!
zimbrul says
This help us a lot to better understand Genesis. Hope to see more.
PS. Very interesting the way to add “related posts” after the article without a plugin.
I’m currently changing the design of my site with Streamline 2.0 and I found these tutorials very useful.
Angie says
I need to create a site that has the sidebar styled differently on several different pages, mainly 3 different colors on the different inside pages (which is also different on the home page). If they are all called the same thing “sidebar” how do I style them differently without creating different sidebars? Or do I? I am new at this…obviously…HELP!
nickthegeek says
Angie, thanks for taking the time to comment. You should check out my tutorial on body class. Body class is the simplest way to target CSS to parts of your site.
Bamajr says
The genesis_structural_wraps is really frustrating me. The “inner” div & corresponding .wrap was created in the functions.php file. Now I’m building a landing page where I need the “inner” div & corresponding .wrap to go away. How does one keep the “inner” div & corresponding .wrap from being loaded, in one-off scenarios, such as this?
nickthegeek says
You cannot do that with hooks. you wold need to build your own custom template using the contents of the genesis/lib/framework.php file as the starting point for your customization.
Luke Rumley says
This is almost unrelated to this post, but this post is where I realized what happened. I am working with the new Apparition theme, which forces the full-width content layout to all pages/posts. I am fighting an uphill battle to go back to the 3-column (too late to turn back, you know), and I commented out the following lines from functions.php:
/** Unregister layout settings */
genesis_unregister_layout( ‘content-sidebar’ );
genesis_unregister_layout( ‘content-sidebar-sidebar’ );
genesis_unregister_layout( ‘sidebar-sidebar-content’ );
That gave me back my layout selectors under Genesis -> Theme Settings, and of course I had to style them up. However, when I picked a new default layout, it wouldn’t stick! It kept flipping back to full-width as the default. I felt like Curly chasing oysters (too obscure?). Then I found this powerful little line in functions.php, commented it out, and all was well:
// add_filter( ‘genesis_pre_get_option_site_layout’, ‘__genesis_return_full_width_content’ );
Jonathan says
Looks like there is some code issues with this code in your post,
genesis_structural_wrap( $context = ”, $output = ‘
Naturalny says
I had problems with default layout options in genesis 20.0, unregistered it and used your codes, works great thanks