In my previous post, What Are Hooks and How Do You Use Them?, I explained that hooks are simply placeholders within the Thesis code where you can insert your own code to add extra content or functionality to your theme. These pieces of code are called functions and, in this post, I'm going to explain the basics of writing one.
Now, functions can be incredibly long and complex—and far beyond my ability to understand them. But it's quite amazing how much you can actually accomplish with just the basics (especially when it's so easy to steal get the more complex bits of code from other resources to mix in with the basics.
So, with no further ado, here's what you need to know to get started writing functions that you can use to customize your Thesis theme. The example creates a simple text box with a border that you can insert in any of your hooks. I'll put all the pieces together at the end if you want to try it out yourself—you can just copy and paste it into your own custom_functions.php file.
Name the function
"Naming" might not be the technically correct term for what I'm doing here, but it helps me understand it. This is the opening statement of the function.
Note: You'll often see bits of code that begin with <?php. The reason I'm not showing it here is because when you install Thesis, the custom_functions.php file already has that line at the top, so I don't want to duplicate it.
The bit highlighted in yellow is the actual name of the function, so that will change for each new function. (I'm not sure of all the rules, but you can't use spaces, and I recommend you keep everything lowercase.) The rest must be exactly the same as what's above.
Turn off PHP.
The basic language for writing functions is PHP. However, they will also include HTML/XTHML, CSS, and JavaScript (and possibly other languages I have zero knowledge of). So, when you're going to start writing something in one of these, you have to close the opening PHP tag (that line at the top of the file).
That's all you need for that.
Add the HTML code for the box.
I'm also using inline CSS styles here instead of importing styles from the custom.css file just to keep the example shorter.
Isn't this a nice custom function?
</div>
Turn the PHP back on.
Close the function.
Note that every time you open a bracket, at some point you're going to have to close it. This one closes the opening bracket in the first line where we named the function. Think of them as wrappers for the function as a whole.
Now that we have the function, we have to put it somewhere. (No jokes, please. :) This is where we come back to hooks. We just have to pick one and add our new function into it. Here, I'm adding it to the area right above the post headline.
In English, this is saying to take the contents of the function called custom_text_box and add it into the thesis_hook_before_headline hook. You can also try replacing that hook with others (full list here) to see what happens.
Note: Correct syntax is essential when writing code. If you miss a comma or use a colon instead of a semi-colon, the function will not work. It might also break the entire page. So if you get some hideous error message when you upload your custom_functions file, there's a good chance it's a simple syntax error. That's why it's REALLY IMPORTANT that you always save a backup copy of a working version of that file so you can replace it if necessary.
Also note that wherever single quotes (') or double quotes (") appear, these must be plain-text quotes. If you copy code from a program that uses curly quotes (“ ”), you'll have to replace them with plain quotes. (I've set up this blog so if you copy the code from the rendered page, the quotes will paste in properly.)
The Complete Code
Here are all the pieces put together.
?>
<div style="width: 400px; font-family: arial; font-size: 16px; font-weight: bold; color: #2361a1; padding: 12px; border: 3px solid #ccc; margin-bottom: 20px;">
Isn't this a nice custom function?
</div>
<?php
}
add_action('thesis_hook_before_headline','custom_text_box');
And that's it! As you can see, once the elements are broken down, it's really not that difficult to build a basic function for adding content to your Thesis theme. In future, I'll be posting samples for more interesting functions but it's always a good idea to understand the basic structure that's making it work and to help you troubleshoot when something doesn't work.
If you have any questions about this post, please send them to me and I'll address them as soon as possible.
Sign up for the Thesis newsletter to get more great tips, delivered right to your Inbox!
Posted in Code Sample,How To,Thesis
{ 29 comments… read them below or add one }
Nice one! I like how you’ve simplified the writing of a function, but not tried to dumb it down so much that no one will recognise the proper terms for PHP things when they see them. Good work!
Regarding naming functions (and I think that is the best way to describe it, I don’t know of a fancy term for naming) the only other rule that’s essential as far as I know is that you can’t use numbers or symbols at the start of the name. So, you can use
function sidebar3(), but notfunction 3sidebar().Thanks, Kristarella. That’s high praise indeed, coming from someone as experienced with Thesis as yourself! And thanks for the info about the function naming—good to know.
Good tutorial. I have learned a little by practice with project of adding some adsense ads in different zones. So I sort of got it.
My nagging question was about the naming. From your example it seems that the name can be anything that makes sense like
‘ads’ or ‘custom_text’
and add location to it
‘before_header’
so it looks like
before_header_ads
and that becomes the function at top of script
here is script for ad before header (pub-ID redacted)
/* AD BEFORE HEADER */
function before_header_ads() { ?>
<?php }
add_action('thesis_hook_before_header', 'before_header_ads');
but your 'box', with its HTML is a little different.
can you reconcile?
Hi Bill.
Thanks for your comment. You don’t need to add the location into the function name at all. The only place you need to have the location is in the first part of the add_action statement, where you’re identifying what hook you want to put it in. If you haven’t read this article about hooks yet, you might find it helpful:
http://www.techforluddites.com/2010/01/thesis-hooks.html
While there’s nothing wrong with having the location info in the function name (if it helps you identify what the function is about), it’s not necessary. So you could have just kept the name of your function as “header_ads” if you wanted, and then your add_action statement would be:
add_action(‘thesis_hook_before_header’,'header_ads’);
“thesis_hook_before_header” is the part that says where the content is going.
Does that make sense?
Thanks again for the question—I’m sure other readers will appreciate the clarification as well.
Very nice tutorial. Thanks
Do you know how to do so that the text box only appare on the home page ore a certain blog post.
Thanks Nicklas. I’m actually working on a post about that right now that will be live tomorrow. So I hope you’ll check back then!
Well, I ended up posting it a little sooner than expected. This should answer your question:
http://www.techforluddites.com/2010/01/thesis-applying-functions-only-to-specific-pages.html
Thanks for this post! One of the things I’m always wondering about, though, is this: when someone suggests you add something to, say, the functions_php file, how do you then alter those instruction to add it instead to the custom_functions_php file?
For example, here is what I’ve been told to put into my functions_php file…it’s just some code to get thumnails working in a php-enabled widget that is showing a post excerpt.
add_theme_support( ‘post-thumbnails’ );
set_post_thumbnail_size( 200, 200 );
Does this then change to something like:
This is what I am trying to understand. How to take other folks directions about how to customize something in wordpress and then translate it to do it in the custom thesis files, instead.
Hi Kayle.
Have you tried just adding the code into the custom_functions.php file as is? If they’re new functions being added, which seems to be the case, I would expect them to work okay like that. Otherwise, I’d like to see the page that has the full instructions to see if they say anything else that would apply.
The other thing is that Thesis already has a built-in thumbnail function for cropping your post images. Is there a reason you can’t use that?
By the way, there seems to be a line missing from your comment after “Does this then change to something like:” Not sure what you were suggesting as an alternative.
Feel free to email me at Thesis@TechForLuddites.com if you want to get into this in more depth.
Hi Elizabeth,
I did try just adding it as-is, but it did not work. I noticed most of the custom php file items started with the word “function “, then what it does, so that’s what I was wondering, whether that needed to be added at the start of each of those lines. And maybe whether I needed the php end tag, as well.
I know that the functions.php file looks quite different in it’s set up than the custom_functions.php file, for example…no function calls, no php start or end tags, etc.
Originally I tried just calling the thumbnail right inside the php that I placed in the widget, (code is below so you can see it as requested), but that didn’t work because which was what I first thought of adding, only works in the main WP loop. So that’s why the added function was needed.
I just don’t like that I had to add something to the functions_php file and would prefer to do it the Thesis Way!
This in in a PHP widget:
query(‘tag=featured&showposts=1&orderby=date’);
while ($featuredPost->have_posts()) : $featuredPost->the_post();
?>
Vendors We Love
<a href="”>
<a href="”>Read the full article →
oh, shoot, it stoped it when it hit some html; I’ll skip the html and put the rest in so you can see it here:
query(‘tag=featured&showposts=1&orderby=date’);
while ($featuredPost->have_posts()) : $featuredPost->the_post();
?>
(some html for the widget header)
<a href="”>
(some html for the read more tag, which does not appear automatically)
is there some magic to stopping what I’m putting into this box from disappearing?
okay, so removing all the php tags…they are in the right places, just pretend they are there…maybe you can see what is happening in my widget:
$featuredPost = new WP_Query();
$featuredPost->query(‘tag=featured&showposts=1&orderby=date’);
while ($featuredPost->have_posts()) : $featuredPost->the_post();
the_post_thumbnail();
< the_excerpt();
I added these lines to functions.php:
add_theme_support( 'post-thumbnails' );
set_post_thumbnail_size( 200, 200 ); // for a 200×200 thumbnail.
Hi Kayle.
It’s really hard to troubleshoot a snippet of code out of context. If you want to email me a link to the site you’re working on, I’ll be happy to take a look and send you any more questions I may have. Also, if you could include a link to the page that has the instructions for adding the thumbnail code so I can check that out, that would be helpful.
If you’re not already registered with the DIYthemes Forums (www.diythemes.com/forums), I highly recommend you do and then you can also post the question there. There are a lot of people there who are much more experienced PHP coders than me who may have a really quick answer for you. (I’m still very much in learning mode myself!)
In the meantime, here’s one thing I would try adding to custom_functions.php with the info you’ve given now. It creates a new function that calls the two lines of code and, by putting them in the before_html hook, should run them right at the beginning of rendering any page.
function widget_thumbnails() {
add_theme_support( ‘post-thumbnails’ );
set_post_thumbnail_size( 200, 200 ); // for a 200×200 thumbnail.
}
add_action (‘thesis_hook_before_html’,'widget_thumbnails’);
I have no idea if that will actually work, but it doesn’t hurt to try (as long as you make sure you keep a backup of your working custom_functions.php file in case this causes a problem)!
Kayle, you need to escape your code for it to show up in comments properly (i know, we always learn the hard way!).
You should be able to just paste
add_theme_support( ‘post-thumbnails’ );
set_post_thumbnail_size( 200, 200 );
into the end of custom_functions.php (as long as there is no
?<before it, if there is, delete it).Um, I meant as long as there is no
?>Hi Elizabeth,
Sorry for gumming up your post with so many lost functions. Actually everything I’ve given you is everything I needed to do this, there was no more to it, and I am a regular on the forums at DIY (fabulous people there). The only reason I raised it with you is that you have this wonderful posting about the basic use of the custom_functions_php, and oftentimes, translating instruction that involve changing other files into ones that work in the thesis custom file is something I’m sure a lot of people have trouble with. I think your suggestion is a very good one and I should try it out…this is exactly what general instructions won’t tell you, and we need this info. to build up a site without driving everyone nutty along the way! I will email you what I’m working with and what my site is; feel free to take a look, but no pressure, I will eventually get it figured out. Meanwhile it’s working, it’s just not where it should be.
Oh, you’re not gumming anything up! I’m just not experienced enough to be able to look at something on its own (e.g. without seeing the site) and totally get what you need to do. But kristarella (one of MY gurus!) seems to confirm my original inclination that you should be able to use the code as is in custom_functions.php. Maybe there’s something else in your file, like she mentions, that is preventing it from “taking”.
That’s interesting…so I should be able to just stick it in there? No start or end php tags, no nothing? Because I just added it to the bottom, and that definitely did not work.
oh my goodnesss….I tried it again, and this time it worked. I’m embarrassed!
I’m also making a note about how to make my code appear in comments; thanks Kristarella! It’s wonderful to get so much help from a master.
Maybe it worked cuz she said so, huh? : ) Can’t WAIT to play with this widgetized php’ed rockin’ sidebar excerpt ability…I think it’s going to be a super cool addition to my thesis sites!
You could try adding it to the top of the file, right after the opening <?php — that way you’ll know nothing else in the file is interfering with it, which may be what’s happening with it now at the bottom of the file.
By the way, the reason the functions look different, I think, is because custom_functions.php comes with an opening <?php tag right at the top of the file. So when people write new functions they don’t need that unless they use an ending PHP tag to write some html, in which case they another opening one to start the PHP again. Whereas, I think when people post examples for functions.php, they usually assume the code stands on its own, so each section needs those opening and closing tags.
That’s great!
It’s like when you hold off going to the doctor for ages when your foot hurts and, when you finally go, your doctor says, “let’s way a few more days and see if it gets better.” And it always does…
Glad it worked and I’m also glad kristarella popped in to share her expertise!
You guys cracked me up ;-) Very flattered.
great post! love it. One can do so much with a simple copy and paste and a few basics.
Thanks so much for this tutorial! It was exactly what I needed!
Hi there,
I just found this code and it works great! Just one question though…how do I get this custom box to appear on the home page only?
Thanks so much.
Maria, check out the post below. It should have the code you need. If you still have problems, don’t hesitate to send me an email at Thesis@TechForLuddites.com.
http://www.techforluddites.com/2010/01/thesis-applying-functions-only-to-specific-pages.html
Good luck!
This was very helpful, thank you.
Thank you for this explanation. Highly appreciate your clear instructions!
{ 5 trackbacks }