SSWI — Secrets of WP Theming: Part 1

Secrets of WP Theming: Part 1,

Written in Frisco, TX on May 26, 2005 and tagged with mind.

Today I am beginning a series on some of the lesser known features of the Theme System in WordPress 1.5 , I am not sure how many parts there will be, might be just this one. But don’t count on it. Here are Part 2 and Part 3.

So lets talk about Custom Templates, and more importantly how we can bend them to our will. Now I am assuming that by now everyone has at least a passing familiarity with Templates in WP 1.5, for those who are not up-to-speed, lets cover some back-story.

In the beginning were Templates, and lo they were good.

Templates are the foundation of the WP theme system, and one of the most powerful features, in my opinion, in 1.5. A template defines the layout and “feel” of different aspects of your WP powered site.

There are a number of templates that are strictly defined in WP, they are as follows (list taken from the codex):

style.css
index.php
comments.php
comments-popup.php
home.php
single.php
page.php
category.php
author.php
date.php
archive.php
search.php
404.php

For instance, I have a template that defines the look of my index, one that defines viewing single posts and one for category listings. Each one has different structure, CSS and WP function calls based on its purpose. The one thing they all have in common is the_loop, or the bit of code that tells WP to spit out the appropriate posts for a specific area of my site.

So class, are we all caught up on templates? Good, well what happens when we want to add a page to our site that doesn’t have anything to do with our posts or categories?

Say we want to add an archives page like the one here at Sillyness to our sites?

Again we turn to Templates, more specifically Custom Templates.

Templates, Posts, Pages and Plugins

Now we have already stated that there are a number of strictly defined templates in WP. But there is also another category of templates, ones that can be anything, can be called anything and can be applied to any “Page” you create in WP. It is here with Custom Templates that the fun begins.

It is a little known fact that you can apply custom templates to blank “Pages” in WP. What I mean is that you can create a completely blank page in WordPress and then apply a custom theme laden with code to it. As an example lets look at the archives page here at Sillyness.

If you were to look at the page I created in WP named Silly Archives, the “Page Content” area would be completely blank. If you then opened my custom template you would see a whole mess o’ code, and interestingly enough the_loop is no where to be found. In fact the only WP core code that you would find would be get_header(); and get_footer();

The rest is either embedded code, or plugin calls.

So let’s get into some code.

So back to our hypothetical example. Our first step would be to create the custom template that will be applied to our Archives page. Because we do not re-invent the wheel, we will be making use of Shawn Grimes Clean Archives plugin, and my Commenter Heat Map plugin.

So first things first, every custom template must start with the following code:

<?php 
/*
Template Name: Archives Template
Description: A template for my archives pages.
*/
?>

In addition for this particular page we need to add a call to wp-blog-header.php so our opening code will actually look like this:

<?php
require('./wp-blog-header.php');
/*
Template Name: Archives Template
Description: A template for my archives pages.
*/
?>

Next we call for our header.php file and start adding our content:

<?php get_header(); ?>
<div class="main">

<h2>
Here are the archives for <?php bloginfo('name'); ?>.
</h2>

<p>
Search the archives.
</p>

<div class="search">
<form method="get" id="searchform" action="/index.php">

<input type="search" value="Search" name="search" id="s" />
<input type="submit" id="submit" name="Submit" value="Go!" />
</form>

</div>

Now you could have put some of this in the “Page Content” area of the ‘Create Page’ screen, but for this demo we want to have everything in the template, so on we go.

<?php echo srg_clean_archives(); ?>

<h2>
Commenter Heat Map
</h2>

<p>
Below is a heat map of the commenters here.
</p>

<?php cjd_comment_heat(); ?>

</div>

And finally we close with the footer call:

<?php get_footer(); ?>

And that is the entire template, now we save it as new_archive.php and upload it to our /wp-content/themes/ourtheme/ folder, then log into our WP admin area to create a new Page.

Lastly we need to create a blank Page and link it up with our new template.

So let’s go to Write > Write Page and get to business. First off we need to give our page a title, let’s say My Archives, once that is done we can skip down past the “Page Content” area to “Page Options”.

The first field should be Page Template, and in the drop down box we should find Archives Template, select that and click Create New Page. That’s it, if you have installed and activated the plugins, when you load http://my.site/my-archives/ you should see your lovely new Archives page.

Well that’s it for the first of this series. I hope you have had as much fun as I have. If you have any questions, leave them here in the comments and I will do my best to answer them.

If you post about this on Twitter, please use the hashtag #silly486.

Comments:
Blog
Twitter

clint, on March 1, 2007

Just one of Chris’ many gifts, a good amount of people are experienced and know alot, but only a handful of them can relate it with clear understanding so that the unlearned can grasp it, and better yet impliment it.

I’m quite anxious to learn from this series, and do my best to pass it on…

Chris J. Davis, on March 1, 2007

Yeah sorry about that. I am going to be publishing a revised version of each of these articles on the codex when I am done.

Basil, on March 1, 2007

Wish I’d had this before I went slogging through codex.wordpress.com. This makes a little more sense than what I found there.

skippy, on March 1, 2007

Great work, Chris. Thanks for sharing.

seriocomic, on March 1, 2007

I for one am very appreciative of the time and effort people such as yourself take to document these basic, yet somewhat confusing topics. Thanks :)

Jennifer, on March 1, 2007

Oh this is going to be great Chris. Thank you so much for providing the information!

Shawn Grimes, on March 1, 2007

Nicely done Chris. You’ve taken something that has been trivial to quite a few people and turned it into an easy process. Thanks for the pimpage too.

Arno, on March 1, 2007

If there is one thing missing in the WP package right now, this is this kind of greatly understandable explanations and documentation ! Well done Chris !

Indranil, on March 1, 2007

Thank you for the great post. Couldn’t come at a sweeter time :)

kartooner, on March 1, 2007

Fantastic, Chris. Thanks for taking the time to outline this!

Joachim Guanzon, on March 1, 2007

This is great, thanks, now I can start making my own and not relying on editing default templates.

Steve Smith, on March 1, 2007

Nice work Chris. I’ve been meaning to do a tutorial like this for a while, but you beat me to it. Well done.

Root, on March 1, 2007

There is something about templates in WP that is deeply unfathomable when you get started - and so simple once you understand it - this is a really great tutorial bridging that gap, explaining the mysteries and hopefully helping folk step over their apprehension. :)

char, on March 1, 2007

Oh for peets sake I went through Codex too and I got a little lost so I resulted to reading books on CSS and whatnot and I’m sure this will definately help shed some light ;)

David, on March 1, 2007

I found the best way was to deconstruct a template that looked the most like what I was going to end up with when I was done, but this series will probably be way better… Good stuff.

Oliver, on March 1, 2007

Great write up! This information will definitely get beginners started.

craig, on March 1, 2007

Well done, Chris! Another feather in your cap, to be sure.

Aaron Brazell, on March 1, 2007

Excellent. I love it when people think outside the box.

Brendan, on March 1, 2007

Chris,

Nice work. You explain the basics well - which I can never do right. Very cool article. :)

Margi, on March 1, 2007

Nice! Thank you so much for explaining in a straight-forward, clear manner. I look forward to future articles as well.

Jalenack, on March 1, 2007

Flawless article, great job. I was trying to figure this out only yesterday. Although, I’m wondering if the srg_nice_archives() function could be pulled off without ~50 queries. My query total on my archives is 81…Thanks in any case!

Steve, on March 1, 2007

Great tutorial. How do you get that slick OS X style form box on your archives?

Matthew Bischoff, on March 1, 2007

Thanks for the tips in creating a wordpress theme from scratch.

Sphinx7, on March 1, 2007

Way Cool. That was really straight forward and easy to understand. Looking forward to the other articles in the series.

Cheers!

Hector, on March 1, 2007

hey, this was great. I’m not a code-kid myself, so I found the article very useful. and thanks to Problogger’s Darren for pointing it out.

Ray, on March 1, 2007

Very good.

Kates, on March 1, 2007

When I did my first theme, I had a hard time figuring out how to make a template. Took me a week to learn it. I wish your post has come earlier. You explained very well. Better than the codex had.

Julia, on March 1, 2007

Thank you for these very clearn and timesaving instructions.

Tyler, on March 1, 2007

Great write up. Thanks.

Mark Boulton, on March 1, 2007

I dont use Wordpress but non-the-less a really great post.

Aaron, on March 1, 2007

What a read, this is going to help me alot on my next wordpress theme! haha, thanks Chris!

SG, on March 1, 2007

I had a little trouble following the example, and a simple clarification might be in order. My starting page was my original archives.php page, and the template name contained in the file is simply “Archives” The original page was still there, and the FIRST instance of the template named “Archives” was selected on on the write-page screen. The second one, in a file renamed new_archives.php, was ignored.

In the example, the name change is evidently from “Archives” to “Archives template ” which I didn’t recognize as a change.

All fixed now, but certainly wouldn’t be without the article, for which MANY THANKS!

Regards..
sg

Mahdi, on March 1, 2007

Hi Mamnon misham Aghe ye sari be weblog man bezanid

Moshu, on March 1, 2007

If the file created resides in the themes/ourtheme/ folder as a Page Template it doesn’t really need the require('./wp-blog-header.php'); line at the top…

Chris J. Davis, on March 1, 2007

Hey Ron,

Apparently Shawn changed the function call when he released his update. I will make that change in the tutorial.

Chris J. Davis, on March 1, 2007

Hey Ron,

That is great to hear that you were able to sort things out. I apologize that I wasn’t able to respond faster to your questions though.

That is a very good point about Kubrick, I will take that into consideration. And I am overjoyed that you are able to find these little diddies helpful. I love what I do, and it makes it that much better when someone is helped by it.

Ron Pemberton, on March 1, 2007

Hi Chris,
I figured out the alignment issue involving Kubrick default. I had inserted the following thinking it would work;

But, It should be removed and replaced with;

What was vexing me so much - besides the fact I’m still novice in areas - is that Kubrick has widecolumns, and narrowcolumns etc.,etc..
Anyway, the intial came from the suggested starting CSS over at Shawn’s site. I respectfully submit the suggestion of adding this little tidbit about Kubrick/Clean Archives installation into your already Most Excellent tutorial. It would help any future noobs like me, who haven’t complete mastery yet.
Again, I would like to compliment your tutorials. Your writing and content presentation style are great!

Thank you,
Ron

Ron Pemberton, on March 1, 2007

I figured out what I did wrong. In your example above the function call says srg_nice, and it should be srg_clean. i didn’t know to change this - but, thats what I get for installing plug-ins and hacks at 3am.You might want to point this out to complete idiots like me.
Thanks Ron

Ron Pemberton, on March 1, 2007

Ok, now teach me why my div examples didn’t showup in the post???!!

Ron Pemberton, on March 1, 2007

Hi chris,

I wondering if you could help me position eveything correctly. I’m using the Kubrick Default, and the month/year are hanging off the left side. I have looked at your CSS, as well as Shawns. You have yours positioned in a div called content, right? Do I need to create this in my CSS, I only have a div called main.

www.ronpemberton.com/archives/

Any help would be appreciated. Thanks Ron

siUUL, on March 1, 2007

thank’s alot for knowledge! learn more about wp theme!

Ron Pemberton, on March 1, 2007

First I would like to thank for your work. It is greatly appreciated by me. I followed your well written instructions and had no problem understanding anything - but, I now get just the top half of my page and the following error message across the bottom of my screen;

Fatal error: Call to undefined function: srg_nice_archives() in /home/ronpembe/public_html/wp-content/themes/default/clean_archives.php on line 29

What exactly did I do wrong? Everything looks exactly as in your tutorial.

Jeremy, on March 1, 2007

Have you ever noticed that WP sometimes has features in the Admin that go missing? well, here i was, completly woking on this awesome tutorial ( thank you! ) and now I seem to be missing the option to select a template. oddness.

Jeremy, on March 1, 2007

ok,.. so either i didnt have things config’d correctly with my custom template - thus causing it not to give me the option to select one,.. or WP was just having a moment. Either way i have it working. :)

lowell, on March 1, 2007

wow this is awesome tutorials I’ve really learned a lot from you Chris, thanks so much I really do apprecaite it…

lowell, on March 1, 2007

hello chris thank you so much for your awesome tutorials

but I have a question… I created a new theme or index.php and I put it outside the wordpress and it works fine but I want to remove the sidebar I just don’t know how to do it…

maybe you could help me on this…

thank you so much

heres the link my blog www.kissofheaven.com/blog
heres the index.php that I want to remove the sidebar www.kissofheaven.com/index.php

appreciate your help….

DefCoins, on March 1, 2007

Thanks Chris - I’m totally new to this game and have learnt a lot from this post of yours!!!

Brent, on March 1, 2007

Very good tutorial, been trying to figure this out for weeks now. Thanks!

Arny, on March 1, 2007

Great tutorial, I’m looking forward to the next installment! My Wordpress install is in dire need of sprucing up and this tutorial will sure help.

Gaia, on March 1, 2007

A very nice tutorial. I had an old Kubrick with a ton of mods & am now trying to get it up on K2. It’s a bit complicated, but your instructions helped me to understand Michael a bit. ;-)

Gaia

blahgKarma, on March 1, 2007

Is there any chance this technique requires users to engage the Permalink feature in WP? I followed the tutorial verbatim, but may be missing some little step, as I don’t seem to be able to display the archives. Not real sure what URL to point the browser to for displaying the page…

Sorry for the stupid question…

Thanks,

Chris