The functions.php template is not a display template, so it is not like the other templates we have covered, but it is a very important file even though it does not directly display content on your web site. Chiefly, the functions.php file is where the special sauce that makes your theme tick goes. It is the place where you can put what has traditionally been called "library code.'' If in your templates you find repeating code or need some special functionality, this is where it can go. WordPress automatically includes this file during execution so the functions are available in all of your template files.
So far in the examples, you have probably seen all the funny sandbox_post_class () and other Sandbox references and scratched your head. Here is where we will clear that up. The Sandbox theme comes with a whole slew of functions that provide all the semantic CSS hooks, microformat code snippets, and other functionality that makes Sandbox a great starting spot.
The stock functions.php theme is very well commented. Each function and logic block of a function has a one line comment explaining what it does. This makes functions.php easy to modify and extend. However, the majority of these functions will not need to be modified in your production site, unless you have very specific needs. Most of them simply add to the template files to create a hook-rich HTML template for your CSS styling skills.
For example, the function sandbox_post_class () creates the CSS classes for each post in your templates that show posts. In truth, these posts may actually be over-classed, meaning that more classes are assigned to the post than you could ever possibly use. And, that is not optimized for a high-traffic web site, because you are sending HTML that you are not using. But let's face it; your web site is not experiencing the same high traffic volumes as the big guys, so it is probably not worth optimizing these functions too much because the plentiful CSS hooks offer a great convenience for styling.
What we really like about this function is that it provides classes for nearly all the metadata about your post. Consider this HTML code:
<div class="hentry p1 post publish author-david category-generic category-othercategory tag-awesome tag-verycool y2009 m06 d22 h21" id="post-3">
This is the encapsulating div for a singular post, either in the loop or on the single.php display. This post is multi-classed with a wealth of information. The hentry class is in there for Atom feed compliance.
In a loop, each post is assigned an incrementing number; for example, this example is classed p1, meaning it is the first post in the loop. This is not related to the actual WordPress post ID, but is strictly ordinal in the display. You could use this class to create a gradient down the page of gradually fading color, as the ordinal post class increases.
The post class is your generic hook for all posts. This is where you can assign the base attributes to a post. The next class is for the status of the post. In the preceding example this post is published.
Each post is also classed with the originating author of the post. This class is prefaced with the term author- to avoid conflicts with other CSS classes. You could use this class in a multi-author blog to include a profile picture with each post.
The next set of classes is one class for each category the post is in. Again, these classes use a namespacing category- prefix for each one to avoid collisions. These classes could be effectively used to assign icons or special coloring to different categories for instant recognition, similar to the way Slashdot has icons for the different post categories.
Similarly, the next set is classes for each tag assigned to the post. Again, these classes use collision-resistant prefixing. Both the category classes and the tag classes use the slugs from their respective subsystems. They also will always be sorted in the WordPress returned sort, so cascading your CSS becomes very important when you are styling multiple categories or tags. That is, watch the order that they appear in the HTML and compare that to the order, inheritance, and specificity in your styles. css.
These next classes we think are really cool, though we have yet to have a client come forward where we can really use them to their fullest potential. These classes are for the year, month, day, and hour of the post. The previous example was written June 2, 2009, sometime after 9:00 PM, local time. You can use these classes to give various months and years different styles in a sort of magazine edition feel. What we would really like to do is have different styles based on the time of day each post is made, but no one has stepped up.
Some other potential classes that you do not see in the previous example including private and password-protected posts, have the CSS class protected assigned. Also, every other post has an alt class assigned for you to zebra stripe, or alternate the background colors of your posts if desired.
Finally, if you have not been able to get the styles assigned that you need through these classes, each post is also assigned an ID. This post-id is the actual WordPress post ID from the Control Panel. But really, what is missing from these CSS hooks? Possibly the local weather from when you were publishing the post, but with a little ingenuity and a web service, these could even be included in your CSS classes. We will leave this as an exercise for the reader.
The Sandbox theme includes a similar function to to assign classes to the body tag of each page. In addition, many other helper functions can help with cleaning up the user experience or overriding the default WordPress behavior of certain features.
When modifying the Sandbox functions you have to make a choice. Sometimes, if you are making minimal changes to the file, you can just modify the file directly, accepting that this will break any upgradeability of the theme. Alternatively, you can include your own custom_functions.php from the functions.php file and make all your own custom changes here. The caveat is that if you overwrite the functions.php file, either through a theme update or other user error, you have to remember to put the include back in that file before your head gets too bloody from beating it against the wall wondering why your custom functions are not running. In practice, we have successfully used both of these scenarios.
The most likely function in the Sandbox theme to be overridden or rewritten is the sandbox_ globalnav() function. In the default Sandbox theme, this function is used to create a nice unordered list of the pages in your site, devoid of whitespace, wrapped inside a div with an ID of menu. This is a great start but may not cover all the various needs of your client and so it will probably be rewritten. Depending on the scope of changes, there are a couple of paths we have chosen in the past.
One, we have modified this function directly, because the changes required were not severe. Two, we have commented out this function call entirely and rewritten it to meet the needs of the site. Three, we have commented out this function call altogether in the header. php file and started over on global navigation from scratch directly in the header template. As it reads over and over in the Sandbox comments and support documents, the Sandbox theme is a playground and is meant as a starting point to build your own wondrous theme, so do not take the functions set forth as the best way of doing something. It is merely a means to an end.
Some of the more advanced themes and the premium theme frameworks include their own control panels to modify theme settings. These other theme frameworks are covered later in this chapter. However, the theme control panel code resides in the functions.php file.
For example, the Thematic theme framework functions.php is a list of includes of other function files. This logically breaks up and separates the different facets of the theme framework and keeps the files manageable. This theme also includes a basic control panel to control some of the theme settings.
To create your own theme control panel, you have to register your theme control panel functions with WordPress. In addition, you have to create the HTML form for your control panel within your functions. php file. This is one of the reasons we like the way Thematic has broken up the files into separate areas of concern because the mixing of PHP and HTML code never turns out pretty or readable. It is best to keep this information separate and in maintainable file sizes.
Creating your own theme control panel is outside the scope of this book, but it is definitely a great feature to have and most of the premium theme frameworks are including this functionality. Having a theme control panel helps your WordPress theme bridge that gap from blogging engine to full-fledged content management platform for the average user. As a coder, WordPress is easily extendible through the code and the vast WordPress functionality, but for the average user, who is probably your client, not having to deal with code is crucial.
Was this article helpful?
The success of a blog lies in the content. It is the content and the key words that consistently attract potential customers. Great blog content literally means something different on every blog. Great blog content is researched and not impulsive. You cannot treat the blog as an experimental playground and expect it to work for you. It is designed to mean business and make you presence felt online and you have to ensure it performs the way you want it to.