When producing a theme, we try not to limit the website owner’s options within the WordPress Dashboard. The owner may wish to enable an option down the track and be disappointed if they can’t.

The downside for the designer and developer is they may put in work for elements that are never used. The upside is happy clients and return business.

Like most things web, the site’s purpose will dictate that some things just aren’t feasible. Consider this as a series of guidelines that you can adapt for your purposes.

This is a giant list of everything we could think of. It makes the task of designing for WordPress look a lot more daunting than it actually is. The theme test unit contains posts with every type of content listed below.

For the purposes of this post, we focused on our internal WordPress framework.

The website basics

The frame of the website includes the header, footer and any sidebars for website owners to add widgets. The frame may change on various pages throughout the site.

Some typical items that need to be designed for the site are:

• Menus, including hover states and any drop downs or mega menus, if applicable
• Headings and sub headings: HTML can have up to six levels of headings and sub headings. To keep code semantic in our framework, it allows
  • 5 levels of headings within a page (with the page title being the top level)
  • 4 levels of headings within a post (on archive pages, the post title is a second level heading)
• Form input fields, including
  • label placement
  • error message placement
  • focus states (when the user’s cursor is in the input)
  • submit buttons
    • hover states
    • focus states
    • active states (when the button is clicked)
  • an example of a typical layout can be found on our CSS framework’s form demo page (hit the submit button to view error messages).
• link colours
  • default
  • visited (if different from default)
  • hover state
  • focus state (for users navigating the page via keyboard)
    As mentioned in a recent post, we tend to reverse the foreground and background colours for the focus state.
  • active state (when the link is being clicked, frequently the same as hover state)
• Footer, typically containing
  • links to website policies
  • declaration of copyright,
  • links to main pages or a site map.

Widgets

Widgets are the various elements that appear in the sidebar, such as recent posts.

Each widget has a title and the contents described below

• List Widgets
  Most widgets are a list of links. Commonly these are styled in the same fashion but, if the design demands it, they can be made to look quite different.
  • Archives of months/categories
    • Option: Display as drop down
    • Option: Show or hide post count
    • Option for categories: show hierarchy.
  • Links/blog roll
    • Option: show link image (if no image, title is displayed)
    • Option: show link title
    • Option: show link description
    • Option: show link rating
  • Pages/custom menu, shown as hierarchy. Options do not affect design.
  • Recent post titles
    • Option: number of posts to display
  • Meta, links to site’s admin, RSS feed and similar
  • RSS Feed, can also be used to show recent posts. Shows title and an extract from the post.
    • Option: number to display
    • Option: display post author
    • Option: display post date
  • Recent Comments.
    Actually two links per list item; one to the comment and one to the commenter’s webpage.
    • Option: Number of comments to display
• Other widgets
  • Search form, includes input and a submit button
  • Text widget, can include any HTML
  • Calendar: one month with links to dates on which there were posts
  • Tag cloud

Plugins can be used to add other widgets to your page, for example a mailing list subscription form.

Archives and Search Results

WordPress includes the following archives of posts.

• Main archive – archive of posts from all categories by all authors
• Date based archives (by year, month and day)
• Category archives
• Tag archives
• Author archives
• Search results by search term

It is possible for the designer to include a description or author bio on the page. If you add this, you need to allow for the element to be removed if no description/bio is defined.

The archives are a list of posts, while the designer may remove them, they typically include

• title,
• category,
• tags (if added by website owner),
• author,
• number of comments,
• date of post,
• a short excerpt, the beginning or full text of the post
• a ‘read more’ link

Additionally, links to older and newer posts are displayed.

Search results display both pages and posts containing the search term in their title, excerpt or content.

Single Posts

Single posts typically display

• a feature image or thumbnail (if enabled by the designer)
• title
• category
• tags (if defined by website owner)
• author
• comments (if enabled)
• comment form (if open)
• date of post
• full text of the post
• links to the next & previous posts
• links to the next and previous page of comments (if applicable)

it is also possible to display a variety of information about the author if it has been defined.

Some plugins add extra content to the contents of this page. Designing for the gazillions of plugins available is impossible so discussing plugins with your client upfront will be helpful.

WordPress supports post formats which can be used to alter the display for the post depending on it’s content. The theme designer can choose to enable none, some or all of these. Possible post formats are:

• standard
• aside
• gallery
• link
• image
• quote
• status
• video
• audio
• chat

Single pages

WordPress allows multiple page templates to be included within a theme, common templates include:

• A standard page layout (required)
• A home page
• Special purpose landing pages

Pages typically display

• a feature image or thumbnail (if enabled by the designer)
• title
• comments (if enabled)
• comments form (if open)
• full text of the page
• links to the next & previous pages of comments (if applicable)

Attachment pages

An attachment page is linked to from an image or other media file.

• The full sized image, or a link to the media file
• A caption
• the next/previous attachment – if applicable.
• title
• date uploaded
• comments (if enabled)
• links to next / previous page of comments (if applicable)

Post and page content

The WordPress visual editor allows website owners to add numerous items to their post content, including

• bulleted and numbers lists,
• block quotes
• left, right, centre or justified alignment of text,
• links
• headings & subheadings – up to five levels in our framework
• images (left, right or centre aligned)
• images with captions  (left, right or centre aligned)
• video – either uploaded or embedding a youtube video.
• audio – either uploaded or embedding from elsewhere
• links to next/previous pages (if the page/post is split across pages)

If the website owner knows HTML, they can add other items using the HTML editor.

The layout test post on the theme test data page contains everything the website owner can add.

If the theme author enables it, each post and page may include a featured image/thumbnail. This may be displayed wherever post content appears.

Pull out quotes and other decretive elements can be added at the theme designers desecration.

Comments

Comments are generally displayed in the same manner on both pages and posts. WordPress allows for comments to be

• Paginated
• Nested
  By default WordPress allows comments to be nested up to ten levels deep. As the theme designer you can disable this or limit it to a lower number.
  We tend to limit it three or four levels deep.
• display avatars or not.
  As these are enabled and disabled in the dashboard, it is important for the comment design to allow for both scenarios.

The design of individual comments are dictated by the designer. Comments typically include

• name of the commenter
• the contents of the comment
• date and time of the comment
• avatar (if enabled)
• reply to this comment link (if enabled)
• When commenters submit a comment, if the comment needs to be moderated by the admin the text “You comment is awaiting moderation” is displayed.

The comment form

Users that aren’t logged in will see a comment form requesting:

• their name (required),
• their email address (required),
• their website (optional, the theme designer can remove this)
• the comment (required)
• a submit button

If the user fails to fill in the form correctly, our framework displays error messages next to each field.

If the website owner has required users register before leaving a comment, in place of the comment form logged out users will see the text “You must be logged in to post a comment.” In our framework, we display a login form below this text.

Users that are logged in will see the text “Logged in as username. Log out?” and a form requesting the comment followed by a submit button.

Not found pages

If a search term returns no results or a visitor enters a URL incorrectly, a no results/file not found page will be displayed.

Anything can be displayed on this page, by default our framework includes:

• a one line explanation of what’s happened,
• a search form,
• a site map.

Additional items

The theme designer may wish to add additional items & content to their WordPress site. For the most part your imagination is the limit.

Updates

• 28 Sep, 2011 – added a:active as suggested by Edward Caissie below
• 28 Sep, 2011 – change heading level details for posts, brain freeze.

If you have any code suggestions, you can fork the theme on Github and submit a pull request.

Along with the standard features you would expect in a WordPress framework, it includes

• templates for the Theme My Login plugin,
• custom default code for Formidable / Formidable Pro plugins,
• custom html output for the Grunion Contact Form plugin, and,
• a child theme starter.

Never use the framework proper to set up a theme, set up a child theme instead.

• Copy the files from the starter directory into the base folder of your child theme
• Create the sub-directory assets in your child theme
• Copy the framework’s assets/child/ directory into the assets directory of your child theme

See the WordPress codex page on child themes for more information.

More documentation to come!

The Soupgiant base WordPress themes are now available on GitHub. There’s no documentation at this stage, I’ll write up a blog post with details in the coming weeks.

There are two parts to the theme

• Soupgiant Parent Theme
  We use this as the parent theme across multiple projects. Any bug fixes or new features applied to this theme will be available to all child themes.
• Soupgiant Child Theme
  Starting point for each project. Once duplicated for the project, CSS styling and per project PHP customisations are applied/overridden in the child theme. Most projects require a custom header.php & footer.php.

As I say, documentation to come.

Update: We’re currently updating our themes to use WordPress 3.1 features, make wider use of the API and to make child themes easier. Subscribe to our RSS feed and you’ll be notified when these are published.

Attention WordPress Wizards & Gurus. Is it possible to “get WordPress to write a custom field into a javascript variable”?

– source

While I wouldn’t be so bold as to claim I’m either a wizard or a guru, I happen to know the answer to @iamcracks question.

A while back I wrote a two part tutorial on using JavaScript the WordPress way, the code below builds on that. The first step is to load the JavaScript in functions.php using wp_enqueue_script() as detailed in the earlier tutorial:

<?php
function brt_load_scripts() {
  if (!is_admin()) {
    wp_enqueue_script(
      'brt-sample-script', //handle
      '/path/2/script.js', //source
      null, //no dependancies
      '1.0.1', //version
      true //load in html footer
    );
  }
}

add_action('wp_print_scripts', 'brt_load_scripts');
?>

This outputs the html required for the JavaScript when wp_footer() is called in footer.php

Localising the script is done using the function wp_localize_script() it takes three variables:

• $handle – (string) the handle defined when registering the script with wp_enqueue_script
• $javascriptObject – (string) name of the JavaScript object that contains the passed variables.
• $variables – (array) the variables to be passed

To pass the site’s home page and the theme directory, we’d add this function call below the wp_enqueue_script call above:

<?php
...
wp_localize_script('brt-sample-script', 'brtSampleVars', array(
  'url' => get_bloginfo('url'),
  'theme_dir' => get_bloginfo('stylesheet_directory')
  )
);
...
?>

The output html would be:

<script type='text/javascript'>
/* <![CDATA[ */
var brtSampleVars = {
  url: "http://bigredtin.com",
  theme_dir: "http://bigredtin.com/wp-content/themes/bigredtin"
};
/* ]]> */
</script>
<script type='text/javascript' src='/path/2/script.js?ver=1.0.1'></script>

Accessing the variables within JavaScript is done using the standard dot notation, for example brtSampleVars.theme_dir to access the theme directory.

Using a post’s custom fields is slightly more complicated so I’ll write out the code in full:

<?php
function brt_load_scripts() {
  if (is_singular()) {
    wp_enqueue_script(
      'brt-sample-script', //handle
      '/path/2/script.js', //source
      null, //no dependancies
      '1.0.1', //version
      true //load in html footer
    );

    the_post();
    $allPostMeta = get_post_custom();
    wp_localize_script('brt-sample-script', 'brtSampleVars',
    array(
      'petersTwitter' => $allPostMeta['myTwitter'][0],
      'joshsTwitter' => $allPostMeta['joshsTwitter'][0]
      )
    );
    rewind_posts();
  }
}

add_action('wp_print_scripts', 'brt_load_scripts');
?>

Only pages and posts have custom fields so the check at the start of the function has become is_singlular() to check the user is on either a post or a page, earlier we were testing if the user was anywhere on the front end. The arguments for wp_enqueue_script have not changed.

the_post() needs to be called to start the loop and initiate the $post object so the associated custom fields can be accessed in the following line and put in an array.

With the custom fields easily available, the information can then be passed to wp_localize_script() as earlier demonstrated. The final step is to rewind the loop so next time the_post() is called, from either single.php or page.php, the post data is available.

The html output from the sample above would be:

<script type='text/javascript'>
/* <![CDATA[ */
var brtSampleVars = {
  petersTwitter: "@pwcc",
  joshsTwitter: "@sealfur"
};
/* ]]> */
</script>
<script type='text/javascript' src='/path/2/script.js?ver=1.0.1'></script>

In brief, Mullenweg believes that, because WordPress is released under the GPLv2 license, all themes and plugins developed for WordPress must also be released under the same license. Pearson disagrees.

This situation has never affected us directly at Soupgiant so we haven’t needed to, and this is important, ask our lawyer if my interpretation is correct. This is a layman’s opinion and should be treated as such.

The battle comes down to these clauses in the GPLv2 license:

You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works.

–source GPLv2 license

Due to the second clause quoted above, I believe that Mullenweg is wrong. WordPress themes can operate on other blogging platforms with minimal changes. This has been done before with the Sandbox theme for WordPress which was successfully ported to Movable Type.

WordPress themes output HTML with a series of calls to the blogging platform. To output the post’s title and contents in our base theme, we use the code:

<h2 class="entry-title"><?php the_title() ?></h2>
<div class="entry-content">
    <?php the_content("Continue reading " . the_title('', '', false)); ?>
</div>

To output the same HTML in a Movable Type theme, we would output:

<h2 class="entry-title"><$mt:EntryTitle$></h2>
<div class="entry-content">
    <$mt:EntryBody$> <$mt:EntryMore$>
</div>

In terms of a page’s output, the above code is a minor part of the page. The theme’s template is mostly made up of HTML and CSS, HTML and CSS operate in the browser and not in the blogging platform. It’s for that reason that I believe that Pearson is correct in this case.

I acknowledge that WordPress hooks may complicate the matter but these hooks output such a minor part of a theme’s HTML, that I consider the theme uses the platform but isn’t derived from the platform. I’ve left plugins out of this discussion as these are a more complicated matter: they can output HTML or they can build on the platform.

The above said, were I to release a WordPress theme I would probably release it under the GPL as a hat tip and thank you to the community that has assisted me so much. However, if the theme was as complicated as the Thesis theme, I may feel differently about the matter when it’s crunch time.

Again, this is a layman’s opinion and should be treated as such. If you have a layman’s opinion too, we’d love to hear it in the comments.

For the uninitiated, these functions allow you to add JavaScript and CSS files to the header (or footer, in later versions of WP) without running of the risk of another plugin adding the same file, that is, you avoid the following:

<script type="text/javascript" source="http://.../a-plugin/jQuery.js"></script>
<script type="text/javascript" source="http://.../a-plugin/plugin.js"></script>
<script type="text/javascript" source="http://.../my-theme/jQuery.js"></script>
<script type="text/javascript" source="http://.../my-theme/theme.js"></script>

If you develop themes or plugins for WordPress and are unaware of these functions, you should refer to the codex to get the low down on at least wp_enqueue_script, and wp_enqueue_style – these register and queue the files, the wp_register_* functions register the file ready to be queued for output.

The Rant

Despite the value these functions can add to themes and plugins, they are under-utilised in development. The functions have wider adoption in plug-in development, but it’s still well below 100%. In theme development adoption is virtually non-existent (at least in the themes I’ve used).

This failure to code properly is evenly spread across both free and paid themes. I?m happy to look the other way for free themes. After all, the motivation behind the theme may have been to learn WordPress development.

In commercial themes, particularly those above the US$30-$35 price point, it’s downright frustrating that these products haven’t been developed properly.

When someone purchases a theme, they shouldn’t have to debug the product to find out why a JavaScript framework is being included twice. The reason for the purchase is that they either don’t want to, or know how to, develop.

Avoiding costly mistakes

Evaluating a commercial theme on behalf of a client triggered this rant. At $195, it’s quite expensive in the world of WordPress. As I was viewing the source code of the online demo, I discovered the faux pas. We’ll advise against using that theme as a starting point. In fact, within short time we’d found a theme $195 cheaper that would do the job.

Looking at the source code of a demo site is usually enough to tell you how the theme is inserting its scripts:

• Both <link> and <script> tags will use single quotes around attributes (‘), rather than double quotes (“),
• CSS <link> tags will have an ID attribute ending in -css, eg: id=’shadowbox-css-css’, and,
• JavaScript and CSS files include the version number as a query string eg jQuery.js?ver=1.3.2 (although a hook can be used to remove this)

Making sure that the wp_register_script, wp_register_style, wp_enqueue_script, and, wp_enqueue_style are included properly will save time, bandwidth and also avoid some detrimental conflicts.