The Sandbox

Thank you for reading me. I was last revised 12 August 2006 @ 19:48.


Table of Contents


1. Introduction

The Sandbox is a lot of things. For example, it's

But it's a lot more. What began as Scott's leftovers has become a well-crafted, semantics-based theme. Andy's added his innovative semantic class generating functions. Semantic markup is really what this theme is all about.

So what can you do with the Sandbox?

The real feature of the Sandbox is its markup. The use of class-generating functions in the body, post div, and comment/trackback/ping li tags create an truly semantic, extendible backbone for any theme. As Andy said, Given straightforward markup with plenty of selectors, there isn’t much that can’t be accomplished with CSS and a decent browser.

And the implementation of the hAtom microformat means we're looking forward (and pleasing the barons at Technorati). You might be able to improve on our markup, but, well, who wants to work that hard?


2. Class functions

The three semantic class generating functions used in the Sandbox are charted below, outlining what semantic classes are generated by each function (“Class”), how it relates to WordPress (“WordPress Tag”), and the usage of these classes (“Usage”). For more on the WordPress Tag aspect, read the Conditional Tags article on the WordPress Codex.

2.a. sandbox_body_class()

The sandbox_body_class() function is definied in the functions.php file. It has no parameters. It adds semantic classes to the body tag relative to the page that is being displayed. It is used in the header.php file as follows:

<body class="<?php sandbox_body_class(); ?>">

The chart below lists the classes added to the body tag by this function.

sandbox_body_class()
CSS example
body.single div.sidebar { display: none; }
Class WordPress Tag Usage
archive is_archive() When any archive page is displayed, i.e., applies to category-, date-, and author-based archive pages
attachment is_attachment() When the post subpage containing an attachment is displayed, as set with "Linked to Page" in the post editor
author is_author() When a author archive page is displayed
author-[name] is_author('nicename') When a specific author archive page is displayed, where [name] is the author's login name, e.g., author-admin
category is_category() When a category archive page is displayed
category-[name] is_category('nicename') For a specific category, where [name] is the category slug, e.g., category-useful-links
d01–31 gmdate('d') The current day of when the page is displayed (Offset to GMT)
date is_date() When a date archive page is displayed, e.g., by month, by year
h00–h24 gmdate('h') The current hour of when the page is displayed (Offset to GMT)
four04 is_404() When a request results in zero posts, i.e., a 404 error page
home is_home() When the home page is displayed
m00–m12 gmdate('m') The current month of when the page is displayed (Offset to GMT)
loggedin N/A When the page is displayed by a logged-in user
page is_page() When a page is displayed
page-author-[name] is_page() For a page by a specific author, where [name] is the user's login name, e.g., page-author-admin
paged is_paged() When whatever is displayed is "paged," e.g., page 2 of the index
search is_search() When the results of a search are displayed
single is_single() When a single post is displayed
s-author-[name] is_single() & is_author() For a single post published by a specific author, where [name] is the user's login name, e.g., s-author-admin
s-category-[name] is_single() & is_category() For a single post published in a specific category, where [name] is the category slug, e.g., s-category-news
s-d01–31 gmdate('d') For a single post published on a specific day (Offset to GMT)
s-h00–h24 gmdate('h') For a single post published at a specific hour (Offset to GMT)
s-m00–m12 gmdate('m') For a single post published in a specific month (Offset to GMT)
s-y2006 gmdate('Y') For a single post published in a specific year (Offset to GMT)
wordpress N/A When anything is displayed; a class that is always applied
y2006 gmdate('Y') The current year of when the page is display (Offset to GMT)

2.b. sandbox_post_class()

The sandbox_post_class() function is definied in the functions.php file. It has no parameters. It adds semantic classes to each post div relative to the post that this div wraps. It is used in many of the theme files as follows:

<div id="post-<?php the_ID(); ?>" class="<?php sandbox_post_class(); ?>">

The chart below lists the classes added to each post div tag by this function.

sandbox_post_class()
CSS example
div.category-news .entry-title { background: url(news.png); }
Class WordPress Tag Usage
alt N/A For odd-numbered posts, e.g., 1st, 3rd, 5th, etc.
author-[name] is_author('usernicename') For any specific author, where [name] is the user's login name, e.g., author-admin
category-[name] is_category('nicename') For any specific category, where [name] is the category slug, e.g., category-news
hentry N/A For the hAtom 0.1 specification, applied every post
p[n] N/A For counting posts relative to the top of the page, where [n] is the number, e.g., p1 for the first post, p2 for the second post, p3 for the third post, etc.
post N/A A general class, applied to every post
publish N/A For any published post, as contrasted with an unpublished draft
h00–h24 gmdate('h') For a post published at a specific hour (Offset to GMT)
d01–31 gmdate('d') For a post published on a specific day (Offset to GMT)
m00–m12 gmdate('m') For a post published in a specific month (Offset to GMT)
y2006 gmdate('Y') For a post published in a certain year (Offset to GMT)

2.c. sandbox_comment_class()

The sandbox_comment_class() function is definied in the functions.php file. It has no parameters. It adds semantic classes to the each comment li tag (“comment” here meaning comments, trackbacks, and pingbacks). It is used in the comments.php file as follows:

<li id="comment-<?php comment_ID(); ?>" class="<?php sandbox_comment_class(); ?>">

The chart below lists the classes added to each comment li tag by this function. Again, note that "comment" includes comments, trackbacks, and pingbacks.

sandbox_comment_class()
CSS example
div.comments li.bypostauthor { border: 1px solid red; }
Class WordPress Tag Usage
alt N/A For odd-numbered comments, e.g., 1st, 3rd, 5th, etc.
bypostauthor N/A When the comment author is also the post author
byuser N/A For any comment by a registered user
c-h00–h24 gmdate('h') For a comment posted at a specific hour (Offset to GMT)
c[n] N/A For counting comments relative to the first, where [n] is the number, e.g., c1 for the first comment, c2 for the second comment, c3 for the third comment, etc.
c-d01–31 gmdate('d') For a comment posted on a specific date (Offset to GMT)
c-m00–m12 gmdate('m') For a comment posted in a specific month (Offset to GMT)
c-y2006 gmdate('Y') For a comment posted in a specific year (Offset to GMT)
comment N/A A general class, applied to every comment
comment-author-[name] N/A For a comment by a specific registered user, where [name] is the user's login name, e.g., comment-author-john
trackback is_trackback() When a comment is a trackback/pingback

3. Sandbox widgets

The Sandbox automatically loads a few Sandbox-specific widgets into the Presentation > Sidebar Widgets menu. This is to allow for true customization of the Sandbox sidebars. Two new widgets are added automatically (no need to active anything). Two default widgets (as defined in the Widgets plugin) are replaced with Sandbox-specific versions.

First fist new widget loaded is the "Home Link" widget. Placing this widget in the sidebar will generate a link back to the home page. This link, « Home by default, only appears on pages that are not the home page, though it will appear on pages of the home page, i.e., page 2 of the index.

The second new widget is the "RSS Links" widget also relates to the default "Meta" widget, which Sandbox also customizes. In the Widgets plugin default "Meta" widget, RSS links are coupled with the register, log in/log out links, and the wp_meta() function. This new "RSS Links" widget and the Sandbox-specific "Meta" widget allow widgets to emmulate the default sidebars.

And, the Sandbox also specifies its own "Search" widget, which is the same as what is in the sidebar.php file. Basically, all we've done is made everything consistent.


4. Adding skins

Every WordPress theme must have at least a style.css file, but why stop there? After activating the Sandbox theme, a new submenu of Presentation appears, Sandbox Skins. Within this admin menu you can choose from other stylesheets to "skin" the Sandbox.

By default, the Sandbox comes with the following files in the /skins/ folder:

The admin menu automatically loads any file with the extension .css in the /skins/ fodler. A corresponding file with the same name and a .png extension is used as the thumbnail. To add additional skins to the admin menu, simply place a .css file and a corresponding .png file into the /skins/ folder. To display correctly, .png thumbnails should be 300px (W) by 225px (H).

For example, I create a new stylesheet for the Sandbox called “newskin.css.” At the beginning of my newskin.css file, I add

/*
Skin Name: New Skin
Skin URI: http://get-this-skin.com/
Version: 1.0
Description: A new skin
Author: Your Name
Author URI: http://your-name.com/
Global Navigation: Y
*/

I then make a 300x225px thumbnail, which I save as “newskin.png.” The file names of the .css and the .png files must be exactly the same, except for the file extension. I then place both the newstyle.css and newstyle.png files in the /skins/ folder. Now my “New Skin” will appear in the admin menu.

The “Global Navigation” option is for developers. It has two parameters: Y or N. Y adds a list of pages (with wp_list_pages) and a “Skip to content” link. N does not add these items. Enabling this option offers greater accessibility to mobile users (e.g., PSP, mobile phones) and is SEO-friendly. Probably. In the Kubick and Spartan skins, this option is enabled but the links are hidden with CSS from conventional browsers:

div#globalnav, p.access { display: none; }

Please share your skins with the community. There will be a list of skins available at Sand Castles, the Sandbox Skins Depo. You can also find information on how to submit your skin as well as additional information on how to use them there.


5. hAtom microformat

The Sandbox implements the hAtom 0.1 microformat. hAtom is a step towards standardized, semantic blog post markup. It's best if the Microformats people explain:

hAtom is a microformat for identifying semantic information in weblog posts and practically any other place Atom may be used, such as news articles. hAtom content is easily added to most blogs by simple modifications to the blog's template definitions.

So we've modified the Sandbox “template definitions,” whatever that means. You can read the details on the hAtom Wiki. So feel good, you're a step ahead in adopting yet another standard, too. Probably.


6. License information

The Sandbox © 2006 is licensed under the GNU General Public License:

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

For more information on what exactly this means, please read the GNU General Public License. For a slightly more digestable version, check out GPL on Wikipedia.