Tutorial: Thesis 1.2+: customising with hooks

[kristarella]

Hey Guys!

I know there was a bit of panic when Thesis v1.2 came out and suddenly your changes to the core files were gone and you weren't sure where to put them back in.

The bad news is that you'll have to do a bit of shuffling to put your custom code back in. The good news is that this version of Thesis is freakin' awesome. It's possibly the best WP theme on the internet, customising is going to be easier now (with the hooks that Chris has provided) and these customisations will be fairly future proof — no overwriting when you upgrade and no more shuffles.

The key to customising Thesis is the files in the custom folder — custom.css and custom_functions.php. Most of you are familiar with the CSS, and there's some documentation in the user manual. I'll talk about functions.

Open that custom/custom_function.php in your plain text (or html) editor. You'll see that there's already a sample function there for you to use.

PHP Code:

function custom_bookmark_links() {
...
} 


When creating your own function, the name of the function can be anything starting with a letter or underscore (try to make it a unique name to reduce the likelihood of a plugin using the same name); the parentheses after it are for parameters (you don't have to use parameters now, but put the parentheses in); the curly braces are the very important bits — everything inside them defines what the function does.

The bookmark links function puts a list of social cookmarking links wherever you tell it to. You could call this function somewhere in your theme by inserting,

PHP Code:

<?php custom_bookmark_links(); ?>

in your theme code. However, Chris has added a bunch of hooks for you to use. The idea of hooks is that you basically tell WP to insert your code where the hook is. Many plugins have made use of the wp_head and wp_footer hooks, which is the same idea.

The method of "telling" WP to insert this code is to use

PHP Code:

add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] ); 


So, by adding

PHP Code:

add_action('thesis_hook_after_post', 'custom_bookmark_links'); 


in custom_functions.php the bookmark link will be added after the post. It will automatically be inserted above the tags (if you've got them turned on) and the comment link. If you want it to go after those, you can add a priority. The default priority is 10 (which the tags and comment link have inherited), so you need to use a number larger than 10 to move the bookmark link down.

PHP Code:

add_action('thesis_hook_after_post', 'custom_bookmark_links', '11'); 


So, to throw some code into your theme, the best way to do it is to find the suitable hook (see the image and list below) and put it in custom_functions.php like so,

PHP Code:

function my_custom_function() {
    echo 'html code goes in here';
}

add_action('thesis_hook_name', 'my_custom_function', '1 for top priority >10 for lower priority'); 


This is the list of available hook names in Thesis:

wp_head

thesis_hook_before_container

//inside #header
	thesis_hook_before_title
	thesis_hook_after_title
	
//inside #content
	thesis_hook_before_content
	//inside .format_text.entry-content
		thesis_hook_before_post
		thesis_hook_after_post
	thesis_hook_after_content
	
	thesis_hook_before_archive_info
	thesis_hook_after_archive_info
	
//inside #sidebars
//before MM box
	thesis_hook_before_sidebars
//after MM box
	thesis_hook_after_multimedia_box
	//inside #sidebar_1.sidebar ul.sidebar_list
		thesis_hook_before_sidebar_1
		thesis_hook_after_sidebar_1
	//inside #sidebar_2.sidebar ul.sidebar_list
		thesis_hook_before_sidebar_2
		thesis_hook_after_sidebar_2

//inside #footer
	thesis_hook_footer
	wp_footer
	
thesis_hook_after_container

I've included some of the ID and class details, so you know where to apply CSS.

Here's an image of where the hooks go into your web page (approximately):



NB When adding to the custom_functions.php file, please add your code after the last

PHP Code:

<?php
}

that's already in there. Or add it before the bookmark_links function, but not in between. This tag opens the PHP again and closes the example function.

[indianguru]

kristarella, you rock!! An excellent post. Thanks.

[patch]

Amazing post! Thanks for taking the effort, kristarella This will save a lot of us a lot of time.

[jcherfas]

Brilliant. Thanks so much for doing this. Bookmarked to (re)read, learn and inwardly digest.

[indianguru]

Maybe this could help. I have included my custom_functions.php file that uses the following hooks -

• wp_head
• thesis_hook_after_title
• thesis_hook_before_sidebar_1
• thesis_hook_after_post
• thesis_hook_footer

Here's the code:

PHP Code:

<?php
function custom_bookmark_links() {
    global $post;
?>
<ul class="bookmark_links">
    <li><a href="http://del.icio.us/post?url=<?php the_permalink() ?>&amp;title=<?php urlencode(the_title()) ?>" title="Bookmark this post on del.icio.us">Bookmark this article on del.icio.us</a></li>
</ul>
<?php
}


/* To add RubyLearnings favicon */
function thesis_favicon() {
echo "\n<link rel=\"icon\" type=\"image/ico\" href=\"http://rubylearning.com/images/favicon.ico\" />\n";
}
add_action('wp_head', 'thesis_favicon', 99);


/* To add PeepCode banner after title */
function sponsor_header() {
echo "<a title=\"Support our sponsors, Support our site!\" href=\"http://peepcode.com/\"><img src=\"http://rubylearning.com/images/header.jpg\" width=\"960\" height=\"139\" style=\"border: 0px none ;\" alt=\"PeepCode\" /></a>";
}
add_action('thesis_hook_after_title', 'sponsor_header');


/* To add Recent Posts widget in sidebar 1 */
function rl_recent_posts() {
  if (!dynamic_sidebar(1)) {
    thesis_widget_recent_posts('Popular', 'Popular Posts', 8);
  }
}
add_action('thesis_hook_before_sidebar_1', 'rl_recent_posts');


/* To add a link to my Twitter id after every post */
function custom_twitter_links() {
?>
<ul class="bookmark_links">
    <li><a href="http://twitter.com/IndianGuru" title="Follow me on Twitter to communicate and stay connected">Follow me on Twitter</a> to communicate and stay connected.</li>
</ul>
<?php
}
add_action('thesis_hook_after_post', 'custom_twitter_links');


/* To add my own footer */
function rl_footer() {
echo "<p><small>Copyright &copy; 2006-2008 RubyLearning Blog | Built with <a href=\"http://diythemes.com/thesis/\" title=\"Thesis Theme from DIYThemes\">Thesis Theme</a> | Valid: <a href=\"http://validator.w3.org/check/referer\">XHTML</a> | <a href=\"http://rubylearning.com/blog/sitemap.xml\" title=\"sitemap\">Sitemap</a></small></p>";
}
remove_action('thesis_hook_footer', 'thesis_attribution');
add_action('thesis_hook_footer', 'rl_footer');

[kristarella]

Thanks folks! Glad you found it helpful.

Thanks for sharing you code indianguru

[patch]

Hey IndianGuru,

Thanks for sharing your code too

I am just thinking aloud, but is it possible then to use custom functions to activate the thesis_widget_recent_posts in the sidebar.php?

thesis_widget_recent_posts('asides', 'Recent Asides', 6);

edit: I just re-read IndianGuru's code and discovered that it is already there

[scottyworm]

Great Post kristarella. Thank you for bringing further clarity to the customization process.

I was hoping someone could help with some custom function syntax...

I have utilized hooks & a custom function to insert a snippet of HTML directly before each post ('thesis_hook_before_post'). The code I have implemented works nicely (thanks to the information provided in this post) but I wish to RESTRICT this from showing up on the HOME page (which provides a summary of my recent blog posts). I would imagine that I would add some logic (i.e. an IF statement) to my custom function that would stop my HTML snippet from showing up on my home page. But I am not familiar with php code (or available thesis function calls).

Is there an available function to call to restrict my HTML snippet from rendering on my home page...something like [if (!home-page()..]? Or is there another way to accomplish this?

Any help would be greatly appreciated. Thanks.

[phoenixreguy]

See that? It's me in Phoenix giving Kristarella a standing ovation. Bravo!

(And thanks Satish for including your custom_functions file!)

[kristarella]

Originally Posted by scottyworm

Is there an available function to call to restrict my HTML snippet from rendering on my home page...something like [if (!home-page()..]? Or is there another way to accomplish this?

Good guess Scotty! Wordpress has some conditional tag stuff built in so you just need to do something like the following inside your function.

PHP Code:

if (is_home()) {
echo 'html code';
} 


Originally Posted by phoenixreguy

See that? It's me in Phoenix giving Kristarella a standing ovation. Bravo!

Hehe, thanks Jay