Genesis Explained Framework Actions

In the first part of this series, Genesis Explained: The Framework, I explained in general how the Framework works, and I showed the contents of a single file to show how the hooks look in the Framework. In the second part, Genesis Explained: Actions, I explained how add/remove actions work, the technical rules around them. This post is intended to tie these other two posts together, bridging the gap between the theoretical actions and the Framework.

Let’s start by talking files. Genesis does a great job of using directory structure to organize files. Here is the directory structure found in Genesis, with a very brief description of what the files within the directory do

• genesis: contains all files and directories. The files exposed in this directory are general template files, mostly loading other files in the framework. The header.php and footer.php are core framework files with hooks.
  • images: all the images used with the Genesis theme, since you should be using a child theme this doesn’t do much
  • lib: contains the core files for the Framework, the init.php file loads all the other files and the framework.php file contains the core hooks used by the framework
    • admin: files related to admin operations
      • images: images used in the admin part of the site
    • classes: files with php classes used by the theme
    • css: loads styles for the admin section of the site
    • functions: general or helper functions used in the theme and child themes. I will be writing a post that discusses many of these in the future
    • js: handles script loading for the theme, includes admin, comment, and menu scripts
    • languages: handles translation files
    • shortcodes: all the short codes built into the theme
    • structure: handles the output on the front end of the site, the remainder of this article will be dealing with this directory
    • tools: tools used by Genesis to handle some special functions
    • widgets: the theme specific widgets

As you can see, if you choose to look through Genesis, the directories will help you quickly identify the files you are looking for. I could write several tutorials on each directory, but this one focuses on integrating the actions with the Framework, which means looking in the structure directory.

The files in this directory include almost every action used in Genesis. A question I’m often asked is “how do you know exactly what code removes a given element on the site?” Because I know what directory has the original action. If I don’t know the answer off the top of my head (after a year I do know a lot of the functions by rote) I can quickly find it. Let’s look at the files in the structure directory.

• archive.php: has actions specific to archive pages like the archive title output
• comments.php: has actions specific to the comments on the site like the comment form
• footer.php: the footer actions, including the new widgeted footer
• header.php: the actions that load on hooks in the header.php including the site title
• layout.php: actions that handle loading the sidebars
• loops.php: handles the 3 loops available in Genesis: standard, custom, and grid loops
• menu.php: controls the menu output
• post.php: essentially this is everything that loads inside the loop
• search.php: actions specific to search pages
• sidebar.php: the hooks and actions that create the sidebars if they are loaded by the layout.php file

Again, you can see how easy it is to find the code you are looking for based on the file structure. The names are essentially an index for the functions.

Working with Genesis Hooks

Ok, enough of the preliminary details. You came here for specific examples on how to work with the hooks. I’m going to break this section down into three parts: removing actions, moving actions, and modifying actions. In each section I will give a specific example from Genesis files with explanations on what is happening and how you can use that information to do this on your own with other actions.

Removing Actions

This is the easiest part. In the previous article I explained how removing an action is a matter of having the exact same action, but with “remove” instead of “add.” All you really need to do is find the action you want to remove, copy it into your child theme functions.php file, and change “add” to “remove.” There is a tutorial on Dev.SP on removing the post info, but let’s say there wasn’t and you needed to remove that from your site. What do we know about this? Well we know it is in the loop, we know that because it appears on every post in an archive view (one that shows multiple posts on a page). Ok now look at the files, which one says it deals with loop actions? Yep the post.php file, so open that up and have a look, try to see if you can find the right code.

add_filter('genesis_post_info', 'do_shortcode', 20);
add_action('genesis_before_post_content', 'genesis_post_info');
/**
 * Add the post info (byline) under the title
 *
 * @since 0.2.3
 */
function genesis_post_info() {

	if ( is_page() )
		return; // don't do post-info on pages

	$post_info = '[post_date] ' . __('By', 'genesis') . ' [post_author_posts_link] [post_comments] [post_edit]';
	printf( '<div class="post-info">%s</div>', apply_filters('genesis_post_info', $post_info) );

}

Ok, now we have the code needed, there is a filter, an action, and a function. The filter is for another tutorial, so let’s ignore that for now. We don’t need to function to remove or move an action, so we can ignore that. All we need is line two from this. Copy that into the functions.php of your child theme and change “add” to “remove.” This is what you will get

remove_action('genesis_before_post_content', 'genesis_post_info');

If you look at the tutorial on Dev.SP, you will find that is the exact code you need to add to your functions.php file to remove this. Pretty easy.

Moving Actions

The first part of moving an action is removing the action. Think of it like a cut and paste in Microsoft Word. If you want to move some code, first you cut it, then you add in back in where you want it. Another helpful tutorial on Dev.SP shows how to move the navigation menus. Let’s see if we can use our new knowledge to replicate that by looking at the code. First we need to know what file to look in. Since we are dealing with the menu the answer should be pretty apparent … yep, menu.php. For this we want to move the primary navigation. Nothing to fancy, we just want it above the header instead of below it. Did you find the code for the primary nav menu yet? I’m not going to copy it all here, but this is the relevant part

add_action('genesis_after_header', 'genesis_do_nav');
/**
 * This function is responsible for displaying the "Primary Navigation" bar.
 *
 * @uses genesis_nav(), genesis_get_option(), wp_nav_menu()
 * @since 1.0
 */
function genesis_do_nav() {

So we know how to remove this, just copy the action into the child theme functions.php file, and change “add” to “remove” but now we want it to be put somewhere else, so paste the code again and change the hook. With some effort you can memorize all the hooks, but there is a handy hook reference in the Dev.SP site and also in my first part in this series. Since we want to go before the header, we can change it from “genesis_after_header” to “genesis_before_header.” This is the code we end up with

remove_action('genesis_after_header', 'genesis_do_nav');
add_action('genesis_before_header', 'genesis_do_nav');

A quick check of the tutorial and we will find that is exactly what is happening.

Modifying Actions

This is the hardest thing when dealing with Genesis Actions. You have to remove the existing action, then create your own function to replace it. One of the most common changes done in child themes is the need for a custom loop. This can be done in several ways, but for the sake of this example we are going to remove the existing loop and replace it with a custom loop using genesis_custom_loop().

Since we are working with loops, which file should we open. If you said footer.php then you are on crack or something. Of course it is loops.php. The code is right at the top of the file

add_action('genesis_loop', 'genesis_do_loop');

That was easy. This loads a function that decides which loop to load, we will be bypassing that. I’m going to skip to the final code so I can explain what I would add to the child theme, and how this can be done with other actions

remove_action('genesis_loop', 'genesis_do_loop');
add_action('genesis_loop', 'child_do_loop');
function child_do_loop() {
    global $query_string;

    $args = array ( 'cat' => -1, 'order' => 'ASC' );

    $args = wp_parse_args( $query_string, $args );

    genesis_custom_loop( $args );
}

Ok, if you have been following along you know the first line just removes the existing loop function. The second line ads out custom loop function. It must have a unique name. I often change “genesis” to “child” and call it good. If this were added in a archive.php file I might go with “child_do_archive_loop” instead. Also notice that line 3 defines the function and it exactly matches the function name in the action, this is very important as well.

The guts of this are creating the $args for the custom loop. The first part makes the existing query something that can be used inside the function. Any variable not defined in the function needs to be declared global before you can use it. If I wanted to use the $post->ID, a very common need, then I would also need to make $post global. You can make more than one variable global by using comma separated variables

global $post, $query_string;

Moving on, the next lines defines the $args I’m going to use for the custom query. These are the same args used in WP_Query or query_posts().

Since I want to keep the existing query, I need to merge that with the $args I defined. The wp_parse_args() function does exactly this.

With my newly merged $args I can now run the genesis_custom_loop(), which basically takes the args to build a new query and then run that loop using the exact same hooks that are found in the standard loop.

To change some functions, you might be best starting by copying the existing function, giving it a new name, and editing it to what you need it to be. As I said before, there are other options to modifying a function. In some future parts of this series I will be explaining filters, which can let you make big changes without removing, adding, modifying actions.

For now you can find actions in the Genesis files and then remove, move, or modify them. That’s a pretty good start. In the next part of the series I will be dealing with some other cool tips and tricks for working with actions including how to add new actions, using existing functions, and using functions outside the normal actions.

Have anything to add, I’d love to hear from you. I’m also looking for other topics that might need more explanation.