In the previous part of the series, Framework Actions, I explained where to look for Genesis Actions, and how to remove, move, or alter them using hooks. In this continuation of that article I will be explaining how to work with your own functions, and a couple of really cool tricks with using existing functions in the actions, and Genesis functions outside the actions. If you haven’t read the entire series, you may find it helpful to start at the beginning, I’ve setup the tag archive to make it easier to go through the entire Genesis Explained series in order.
Using your own functions
Working with the Genesis functions is fine, but what about when you want to add something else to the site? You have tow rite your own function and hook that in with the add_action() instruction code. (remember, the add/remove actions are really just instructions on where to add the code). This scares a lot of people. Writing a function sounds like a monumental task, especially to folks not familiar with php. The good news is that it is really pretty easy. The function breaks down into a few key parts, a template of sorts. Lets looks at a generic function
function generic( $arg='foo' ) {
echo $arg;
}
This is as simple as it gets. Line 1 includes 4 of 6 parts to a basic function. The word “function” is the first part, it tells php “this is a function you need to remember so you can use it later.” the next part “generic” is the function name. It is how you call for the code to be executed instead of having to write a whole lot of code every time. Of course, with this function it doesn’t save much coding, but in real functions it will.
Let’s talk function names for a second. “generic” is a terrible name for a function. It is too short, non-descriptive, and … well generic. The length itself isn’t a problem. PHP doesn’t require a minimum number of characters, the shortness is a problem because it prevents it from being unique and descriptive.
A function name must be unique. You can’t have two functions with the same name, if you do then you will get an error that will break your site. This is why the code in the dev.sp and support forums will include functions like “child_do_title” it is unlikely that a plugin author is using the “child” prefix. I personally use the “ntg” prefix on my custom code so I will know right away that I wrote the code for that. A child theme will typically use the child theme name or abbreviation, this makes it less likely to cause a problem with two functions having the same name.
A function should also be descriptive. This isn’t mandatory. I could have a function “child_function_a” that handles the title output, and so long as I don’t have another function with that name it will work, but I’m unlikely to remember that name when I need it and will probably forget what it does. “child_do_title” is much better because it tells me that it is a function in my child theme and it “does the title” or outputs the title. If I write a function documentation block then I’ll know all I need to know a year from now when I’m looking at my theme, but that is really another tutorial.
OK, so that side note aside, the next part of the function ( $arg = ‘foo’ ) is the “argument” for the function. Functions don’t require the argument, and a function can have multiple arguments. In this case I am providing a “default” value for my argument, but it can be overridden when the function is called. If I don’t have an argument it will be written like “function generic() { }” and most of the time that is what you will do. On a side note, this function only “echos” the argument. That means it puts that value in where the function is, so if I run that function it will be replaced with “foo” unless I write it into my code like “generic(‘bar’);” then my defined $arg is replaces and it will put “bar” on the screen instead of “foo.” This will make more sense when we get to using the function in the hook.
After the argument is the curly brace to start the function “{” everything after this is the “guts” of the function, the code that will be run when the function is invoked (more on this later). The “guts” would be the “echo $args;” line and this section ends with the closing curly brace “}” so the php engine knows to stop.
That is really the entire function, but if you are like me when I first started, you are thinking “yeah but I don’t know php, I can barely code in html and css, so this doesn’t help me.” Good news, if you can code html and want to use html then just jump into html.
function generic_html() { ?>
Now I'm in html, this will print out using whatever <strong>html</strong> markup I give it.
<?php }
You can even merge html and php like you might when editing a template file with another theme
function generic_html_php() { ?>
<p>See, still in html, no need for any fancy php, unless I need something dynamic, like the date <?php echo date(); ?>.</p>
<p>Pretty easy, and that date function loads inline just like it would in a template file</p>
<?php }
Using your own actions
OK, so you can write a simple function now, but you need to add it to Genesis right? Well that’s the easy part, just write the instructions on what to do with your function. Need to have the code executed before the header?
add_action( 'genesis_before_header', 'generic' );
That can be edited using the techniques in the previous two articles to adjust the position anywhere relative to the other hooks/actions.
So now you have a basic idea of how to add out own code to Genesis via hooks, but there is still a good deal to learn.
Working with Existing Functions
A common task is integrating a plugin with Genesis. Typically a plugin will include directions like “open your template file and add this code where you want it to appear.” This is a daunting task because the files aren’t in the child theme, and in Genesis it only has a single line “genesis();” so how is this done? By actions like everything else. Depending on what you are doing this can be extremely easy. Let’s look at the Add to Any plugin. This is generally pretty easy to integrate and should work automatically, but let’s say you want to control where the code goes relative to the post meta. The instructions say to add some code to your template files via the editor.
<?php if( function_exists('ADDTOANY_SHARE_SAVE_KIT') ) { ADDTOANY_SHARE_SAVE_KIT(); } ?>
You can’t do that with Genesis directly, so you need to add it as an action. This can be done like this
add_action( 'genesis_after_post_content', 'child_do_add_to_any' );
/**add the add to any function after post content if the function exists*/
function child_do_add_to_any() {
if( function_exists('ADDTOANY_SHARE_SAVE_KIT') )
ADDTOANY_SHARE_SAVE_KIT();
}
That’s easy enough, but we can streamline this by combining the function and action. Remember, the “callback function” part of the action instruction just say what code to use, any function will work so long as the function exists, so you can do this instead
if( function_exists('ADDTOANY_SHARE_SAVE_KIT') )
add_action( 'genesis_after_post_content', 'ADDTOANY_SHARE_SAVE_KIT' );
Invoking Genesis Functions without Hooks
Invoking a function is fancy-speak for telling a function to run. If you have edited templates in the past, you are probably use to invoking functions without knowing it. If you add or something similar to a file the you are invoking that function. When you use a hook, you are also invoking a function, you are telling it to load in a specific part of the site before it runs. This means the hooked functions are interchangeable with “normal” functions. Just like you can use another function in a hook, you can use Genesis functions outside the hook.
A great way to do this is in a custom home.php file. You might be editing a child theme with a custom home.php file, but you want a “normal” blog to display after the widgeted content. If you look in the genesis/lib/structure/loops.php file you will find that genesis_do_loop() invokes genesis_standard_loop(), so you can just add this in your home.php file where you want the posts to display
<?php genesis_standard_loop(); ?>
This works for any Genesis function. If you want to put the nav menu on the home page even though it isn’t being used elsewhere, you could add it like this
<?php genesis_do_nav(); ?>
I hope the hooks make more sense after these last three articles. There is a lot to go through so I’d appreciate some feedback on the content of the posts. Do I need to break this up into smaller bites (are the posts to long), are there enough examples, and is the “techno-speak” simplified without being pedantic (talking down to you)? What other topics would you like to see explained in more detail? Is there anything in the actions that needs more explanation?
Moving forward I will be writing a sub series on filters and then focusing on some of the important Genesis functions.
Genesis Responsive Header Updated
Genesis Responsive Header
How I Make Custom Fields Easier in Genesis
How I Added Custom Fields to the Genesis Responsive Slider
A Better Home Page
Feedback: you’re doing great! Keep the lessons flowing….
Suggestion: instead of random examples, you might consider also a running example….some custom construct or theme element that requires implementing all or most of your lessons. And yes, I’ve got a suggestion or two on useful examples…..
What examples would you suggest?
Oh, and the posts are NOT too long….I think you’ve got it just right. But I’d welcome it if you’d step up the frequency to one new post per hour!
Oh, a softball question!
1) Building a custom homepage that displays the most recent post in full, with comments and with page navigation and/or pagination, all while staying within the best Genesis-friendly practices
2) Those same pages with images dropped into the various pages (home, blog, etc.) conditionally upon which page it displayed (for purposes of identification)
3) How to, or whether to, modify a Genesis plugin….specifically, how to modify the Featured Posts Widget to facilitate other display options….Comments, especially!
4) Effectively dividing up the components of a daily post into separate widget areas….so as to display the main text (or excerpt) in one widget area, the comments in another, and a special feature or custom field item (video, slideshow, or a polldaddy POLL) in yet another….Then the layout can be manipulated in the theme stylesheet.
Hey, you asked! In other words, I nominate myself as guinea pig….with all the items I have been struggling with over the past two weeks and all the questions you have been generous helping me with in the StudioPress support forum!
Mark, I think those are great topics, and would probably be something worth their own tutorial series, but I don’t know that any would really lend to this series. I do like the idea of a running theme, like a shop project using different joints to teach proper joinery techniques, but with an end project as the goal. I might look into a “child theme creation” tutorial that teaches how to make a simple child theme with many of the ready made Genesis parts and a few cool advanced tricks to do that with when this series is done.
Yes!!! Please!!!
I wonder if you had a chance to implement this great idea yet? It’s been a year. (not too long, I realize). I couldn’t actually find anything like that on your site, but am looking forward to finishing this excellent tutorial and going through others I found here. So far, so good!
Btw, can’t wait for your upcoming e-book.
Ana, This is going to be a part of the new eBook, but not something I’m specifically publishing on the site.
The tutorials are excellent, and I think that they will be very helpful to a lo of newcomers to Genesis. I know they would have helped me get to grips with the concepts much more quickly if they’d been around last year when I first got on board.
I think that your idea about a child theme creation tutorial would be a great ‘next step’ as a it would represent a logical progression for most people – once we’ve been shown the mechanics of creating a child theme ‘properly’ there’d be no looking back either for we users, or the Genesis developers.
Nick
Excellent job on the tutorials. They are the perfect length and simplified enough. Agree on maybe a child theme creation project. I would guess to say the showcase at Studiopress are 90% custom genesis.
Thanks
Not to be a party-pooper here, but it seems although a child-theme tutorial would be great…most of the Genesis child themes are very slim and sparse. A homepage and a stylesheet. Oh, and maybe a few functions to tweak meta, comments, etc…..now if that homepage featured the most current blog post with comments, that would be a great child theme project!
Or….a tutorial on writing or modifying a plugin for Genesis…that would be interesting as well….
Keep up the great work, Nick….
I understand why you feel that those are the most useful, but they are most useful to a very specific need, that isn’t helpful to the majority of developers getting into Genesis. Again, thanks for the idea, but I do not wish to write a tutorial on a very limited and specific topic that I have no need to implement at this time.
I think it is much better to adopt the mindset of working with Genesis, rather than trying to hack it about to make it fit in with the models which we may have previously learned. Once you understand the philosophy behind Genesis, then it becomes clear that the fact that a child theme appears so simple is testament to the efficiency of the framework, rather than a limitation. It does take some getting used to, but is well worth the investment, I have found.
you explain things so well and I can actually follow along! A real example like Mark said would make it that much better. 🙂
I’d love to see a specific example on how add a leaderboard advertising space on all pages of a site. I’ve used the Blissful theme and the “home-top” php to add a leaderboard to the landing page, but am having trouble moving it to all pages.
This series is great. Having not built a website in 10 years when I used to use Dreamweaver, I decided to use wordpress for my first site and was lucky enough to choose Studiopress as my theme . What’s great about your tutorials is that you are explaining php along with the hooks etc. This is helping to get a better overall picture of how all these parts work together.
I agree that some concrete examples would help. I’m totally new here and trying to figure out what is functional and what is conjectural is difficult — impossible to distinguish between the two. It’s like a double negative in a sentence when you don’t know the value of anything said, compound processing for the newbie even though this obviously makes perfect sense to those who already understand.
This is a universal problem…you see this in text books that the school board swears is superb but that the freshman has such difficulty with. It separates an expert from a good teacher.
Using a child theme project to apply these tutorials is a GREAT idea! As a newbie, it would help to be able to have a real world example to experiment on. You can read through the tutorials and say OK, I think I understand that, but until you actually apply it, it doesn’t really sink in.
I read “How to Build Your Own Wicked WordPress Themes” and they used Thematic as their framework. As I was reading it, I kept thinking, I wish someone would write a similar book on child themes using the Genesis framework.
Trying to learn PHP, WordPress and the Genesis framework all at once is quite a challenge, but as someone posted earlier, all the pieces will eventually come together.
In the meantime, thanks for a great series, looking forward to your e-book.
Jeff,
I am pretty excited about the “frankentheme” I’m working up for the eBook. I am making a point of using custom meta boxes, custom post types, taxonomies, and creating an admin menu to show how to do as many techniques as possible. Each section is explained with internal code documentation and I’m writing up everything for an appendix in the book too.It should really help get users up to the next level for their custom work.
Hi Nick,
I think this tutorial might be exactly what I was looking for and, if so… WHEW! If you don’t mind me processing “out loud,” I want to see if I’m understanding this correctly. I came from working on sites that didn’t use hooks/filters, so if I wanted to add something new, I just went into that file – or created a file – and starting ing away. With Genesis, though, where I get a little stuck is when I find a great tutorial (the desandro Masonry one, for ex.) and it gives me html to add somewhere, none of which has Genesis-looking things in it. So my quandary has been, how do I add it to a Genesis file? If I’m reading post this correctly, then I would add the “generic_html” function (changing the name from generic, of course) and then insert all that fabulous html between the php tags? Is it really that simple and I’ve been making things way too complicated or am I oversimplifying it? Fingers & toes are crossed that it’s the former.
Thanks for this site and all these tutorials. They’re perfect for someone like me – not quite “advanced” but definitely not a beginner, either. Also, I hate to be contrary, but I kind of like that you don’t have linked examples. Normally I really do need them because I am such a visual learner it’s ridiculous. But in the case of your posts, you are explaining what all these things actually do, which is way better than handing me a few lines of code and saying “here, go do this, this is what it looks like.” If I understand what something does and how it works, I understand that the possibilities are endless. A working example leaves my brain with the idea that there is only one way to use something. In the case of this post, for example, I would assume that this code only worked for whatever you put inside of it and I wouldn’t even consider that I could add my own html or php inside.
Sorry – that should say “I started “div”-ing away. I made the mistake of putting it in the little bracket guys and it got stripped out. Oops!
Thanks a lot for these tutorials.
I finally understand how Genesis works and I already put what I’ve learned in practice. The level is just perfect for someone who knows a bit about WP and programming but nothing about Genesis and PHP.