Custom template
 


WordPress Themes typically consist of three main types of files, in addition to images and JavaScript files.

  • The stylesheet called style.css, which controls the presentation (visual design and layout) of the website pages.
  • WordPress template files which control the way the site pages generate the information from your WordPress database to be displayed on the site.
  • The optional functions file (functions.php) as part of the WordPress Theme files.

Child Themes
The simplest Theme possible is a child theme which includes only a style.css file, plus any images. This is possible because it is a child of another theme which acts as its parent.
 

Theme Stylesheet

In addition to CSS style information for your theme, style.css provides details about the Theme in the form of comments. The stylesheet must provide details about the Theme in the form of comments. No two Themes are allowed to have the same details listed in their comment headers, as this will lead to problems in the Theme selection dialog. If you make your own Theme by copying an existing one, make sure you change this information first.

The following is an example of the first few lines of the stylesheet, called the stylesheet header, for the Theme "Twenty Ten":

/*
Theme Name: Twenty Ten
Theme URI: https://wordpress.org/
Description: The 2010 default theme for WordPress.
Author: wordpressdotorg
Author URI: https://wordpress.org/
Version: 1.0
Tags: black, blue, white, two-columns, fixed-width, custom-header, custom-background, threaded-comments, sticky-post, translation-ready, microformats, rtl-language-support, editor-style, custom-menu (optional)

License:
License URI:

General comments (optional).
*/

NB: The name used for the Author is suggested to be the same as the Theme Author's wordpress.org username, although it can be the author's real name as well. The choice is the Theme Author's.

The comment header lines in style.css are required for WordPress to be able to identify a Theme and display it in the Administration Panel under Design > Themes as an available Theme option along with any other installed Themes.

Stylesheet Guidelines

  • Follow CSS coding standards when authoring your CSS.
  • Use valid CSS when possible. As an exception, use vendor-specific prefixes to take advantage of CSS3 features.
  • Minimize CSS hacks. The obvious exception is browsers-specific support, usually versions of IE. If possible, separate CSS hacks into separate sections or separate files.
  • All possible HTML elements should be styled by the Theme, both in post/page content and in comment content.
    • Tables, captions, images, lists, block quotes, et cetera.
  • Adding print-friendly styles is highly recommended.
    • You can include a print stylesheet with media="print" or add in a print media block in your main stylesheet.

Functions File

A theme can optionally use a functions file, which resides in the theme subdirectory and is named functions.php. This file basically acts like a plugin, and if it is present in the theme you are using, it is automatically loaded during WordPress initialization (both for admin pages and external pages). Suggested uses for this file:

The default WordPress theme contains a functions.php file that defines many of these features, so you might want to use it as a model. Since functions.php basically functions as a plugin, the Function_Reference list is the best place to go for more information on what you can do with this file.

Note For Deciding When To Add Functions To Functions.PHP or a Specific Plugin: You may find that you need the same function to be available to more than one parent theme. If that is the case, the function should be created in a plugin instead of a functions.php for the specific theme. This can include template tags and other specific functions. Functions contained in plugins will be seen by all themes.

Template Files

Templates are PHP source files used to generate the pages requested by visitors, and are output as HTML. Template files are made up of HTML, PHP, and WordPress Template Tags.

Let's look at the various templates that can be defined as part of a Theme.

WordPress allows you to define separate templates for the various aspects of your site. It is not essential, however, to have all these different template files for your site to fully function. Templates are chosen and generated based upon the Template Hierarchy, depending upon what templates are available in a particular Theme.

As a Theme developer, you can choose the amount of customization you want to implement using templates. For example, as an extreme case, you can use only one template file, called index.php as the template for all pages generated and displayed by the site. A more common use is to have different template files generate different results, to allow maximum customization.

Template Files List

Here is the list of the Theme files recognized by WordPress. Of course, your Theme can contain any other stylesheets, images, or files. Just keep in mind that the following have special meaning to WordPress .

style.css
The main stylesheet. This must be included with your Theme, and it must contain the information header for your Theme.
rtl.css
The rtl stylesheet. This will be included automatically if the website's text direction is right-to-left. This can be generated using the the RTLer plugin.
index.php
The main template. If your Theme provides its own templates, index.php must be present.
comments.php
The comments template.
front-page.php
The front page template, it is only used if you use a static front page.
home.php
The home page template, which is the front page by default. If you use a static front page this is the template for the page with the latest posts.
single.php
The single post template. Used when a single post is queried. For this and all other query templates, index.php is used if the query template is not present.
single-.php
The single post template used when a single post from a custom post type is queried. For example, single-books.php would be used for displaying single posts from the custom post type books. index.php is used if the query template for the custom post type is not present.
page.php
The page template. Used when an individual Page is queried.
category.php
The category template. Used when a category is queried.
tag.php
The tag template. Used when a tag is queried.
taxonomy.php
The term template. Used when a term in a custom taxonomy is queried.
author.php
The author template. Used when an author is queried.
date.php
The date/time template. Used when a date or time is queried. Year, month, day, hour, minute, second.
archive.php
The archive template. Used when a category, author, or date is queried. Note that this template will be overridden by category.php, author.php, and date.php for their respective query types.
search.php
The search results template. Used when a search is performed.
attachment.php
Attachment template. Used when viewing a single attachment.
image.php
Image attachment template. Used when viewing a single image attachment. If not present, attachment.php will be used.
404.php
The 404 Not Found template. Used when WordPress cannot find a post or page that matches the query.

These files have a special meaning with regard to WordPress because they are used as a replacement for index.php, when available, according to the Template Hierarchy, and when the corresponding Conditional Tag returns true. For example, if only a single post is being displayed, the is_single() function returns 'true', and, if there is a single.php file in the active Theme, that template is used to generate the page.

Basic Templates

At the very minimum, a WordPress Theme consists of two files:

  • style.css
  • index.php

Both of these files go into the Theme directory. The index.php template file is very flexible. It can be used to include all references to the header, sidebar, footer, content, categories, archives, search, error, and any other page created in WordPress.

Or, it can be divided into modular template files, each one taking on part of the workload. If you do not provide other template files, WordPress may have default files or functions to perform their jobs. For example, if you do not provide a searchform.php template file, WordPress has a default function to display the search form.

Typical template files include:

  • comments.php
  • comments-popup.php
  • footer.php
  • header.php
  • sidebar.php

Using these template files you can put template tags within the index.php master file to include these other files where you want them to appear in the final generated page.

Here is an example of the include usage:




The default files for some template functions may be deprecated or not present, and you should provide these files in your theme. As of version 3.0, the deprecated default files are located in wp-includes/theme-compat. For example, you should provide header.php for the function get_header() to work safely, and comments.php for the function comments_template().

For more on how these various Templates work and how to generate different information within them, read the Templates documentation.

Custom Page Templates

The files defining each Page Template are found in your Themes directory. To create a new Custom Page Template for a Page you must create a file. Let's call our first Page Template for our Page snarfer.php. At the top of the snarfer.php file, put the following:


The above code defines this snarfer.php file as the "Snarfer" Template. Naturally, "Snarfer" may be replaced with most any text to change the name of the Page Template. This Template Name will appear in the Theme Editor as the link to edit this file.

The file may be named almost anything with a .php extension .

What follows the above five lines of code is up to you. The rest of the code you write will control how Pages that use the Snarfer Page Template will display. Once you have created the Page Template and placed it in your Theme's directory, it will be available as a choice when you create or edit a Page. (Note: when creating or editing a Page, the Page Template option does not appear unless there is at least one template defined in the above manner.)

Query-based Template Files

WordPress can load different Templates for different query types. There are two ways to do this: as part of the built-in Template Hierarchy, and through the use of Conditional Tags within The Loop of a template file.

To use the Template Hierarchy, you basically need to provide special-purpose Template files, which will automatically be used to override index.php. For instance, if your Theme provides a template called category.php and a category is being queried, category.php will be loaded instead of index.php. If category.php is not present, index.php is used as usual.

You can get even more specific in the Template Hierarchy by providing a file called, for instance, category-6.php -- this file will be used rather than category.php when generating the page for the category whose ID number is 6. (You can find category ID numbers in Manage > Categories if you are logged in as the site administrator in WordPress version 2.3 and below. In WordPress 2.5 the ID column was removed from the Admin panels. You can locate the category id by clicking 'Edit Category' and looking on the URL address bar for the cat_ID value. It will look '...categories.php?action=edit&cat_ID=3' where '3' is the category id). For a more detailed look at how this process works.

If your Theme needs to have even more control over which Template files are used than what is provided in the Template Hierarchy, you can use Conditional Tags. The Conditional Tag basically checks to see if some particular condition is true, within the WordPress Loop, and then you can load a particular template, or put some particular text on the screen, based on that condition.

For example, to generate a distinctive stylesheet in a post only found within a specific category, the code might look like this:


Or, using a query, it might look like this:

post;
if ( in_category( '9' ) ) {
    get_template_part( 'single2' );
} else {
    get_template_part( 'single1' );
}
?>

In either case, this example code will cause different templates to be used depending on the category of the particular post being displayed. Query conditions are not limited to categories.

Defining Custom Templates

It is possible to use the WordPress plugin system to define additional templates that are shown based on your own custom criteria. This advanced feature can be accomplished using the template_redirect action hook. More information about creating plugins can be found in the Plugin API reference.

Including Template Files

To load another template (other than header, sidebar, footer, which have predefined included commands like get_header()) into a template, you can use get_template_part(). This makes it easy for a Theme to reuse sections of code.

Referencing Files From a Template

When referencing other files within the same Theme, avoid hard-coded URIs and file paths. Instead reference the URIs and file paths with bloginfo():.

Note that URIs that are used in the stylesheet are relative to the stylesheet, not the page that references the stylesheet. For example, if you include an images/ directory in your Theme, you need only specify this relative directory in the CSS, like so:

h1 {
    background-image: url(images/my-background.jpg);
}

Plugin API Hooks

When developing Themes, it's good to keep in mind that your Theme should be set up so that it can work well with any WordPress plugins users might decide to install. Plugins add functionality to WordPress via "Action Hooks" .

Most Action Hooks are within the core PHP code of WordPress, so your Theme does not have to have any special tags for them to work. But a few Action Hooks do need to be present in your Theme, in order for Plugins to display information directly in your header, footer, sidebar, or in the page body. Here is a list of the special Action Hook Template Tags you need to include:

wp_head()
Goes in the element of a theme, in header.php. Example plugin use: add JavaScript code.
wp_footer()
Goes in footer.php, just before the closing tag. Example plugin use: insert PHP code that needs to run after everything else, at the bottom of the footer. Very commonly used to insert web statistics code, such as Google Analytics.
wp_meta()
Typically goes in the
  • Meta
  • section of a Theme's menu or sidebar; sidebar.php template. Example plugin use: include a rotating advertisement or a tag cloud.
    comment_form()
    Goes in comments.php directly before the file's closing tag (
    ). Example plugin use: display a comment preview.

    For a real world usage example, you'll find these plugin hooks included in the default Theme's templates.

    Theme Customization API

    As of WordPress 3.4, a new Theme Customization feature is available by default for nearly all WordPress themes. The Theme Customization admin page is automatically populated with options that a theme declares support for with add_theme_support() or using the Settings API, and allows admins to see non-permanent previews of changes they make in real time.

    Theme and plugin developers interested in adding new options to a theme's Theme Customization page should see the documentation on the Theme Customization API

    Untrusted Data

    You should escape dynamically generated content in your Theme, especially content that is output in HTML attributes. As noted in WordPress Coding Standards, text that goes into attributes should be run through esc_attr so that single or double quotes do not end the attribute value and invalidate the XHTML and cause a security issue. Common places to check are title, alt, and value attributes.

    In a few cases there might already be a template tag for common cases where safe output is needed. One such case involves the "title" attribute when used with the_title() for post and page titles. To avoid a security vulnerability, use the_title_attribute() instead. Here's an example of correct escaping for the title attribute in a post title link when using translatable text:

    Replace deprecated escape calls with the correct calls: wp_specialchars, htmlspecialchar with esc_html, clean_url with esc_url, and attribute_escape with esc_attr

    Translation / i18n Support

    To ensure smooth transition for language localization, use the gettext functions for wrapping all translatable text within the template files. This makes it easier for the translation files to hook in and translate the titles into the site's language. 

    Theme Classes

    Implement the following template tags to add WordPress-generated class attributes to body, post, and comment elements. For post classes, apply only to elements within The Loop.

    Template File Checklist

    When developing a Theme, check your template files against the following template file standards.

    Document Head (header.php)

    Here's an example of a correctly-formatted HTML5 compliant head area:

    
    >
        
            
            <?php wp_title(); ?>
            
            
            
            
            
        
    

    Navigation Menus (header.php)

    Widgets (sidebar.php)

    Footer (footer.php)

    
    
    
    

    Index (index.php)

    Archive (archive.php)

    Pages (page.php)

    Single Post (single.php)

    Comments (comments.php)

    Search Results (search.php)

    JavaScript

    
    

    Screenshot

    Create a screenshot for your theme. The screenshot should be named screenshot.png, and should be placed in the top level directory. The screenshot should accurately show the theme design and saved in PNG format. The recommended image size is 600x450. The screenshot will only be shown as 300x225, but the double-sized image allows for high-resolution viewing on HiDPI displays.

    Theme Options

    Themes can optionally include an options page. 

    When enabling an options page, use the edit_theme_options capability instead of switch_themes for options panels, unless the user actually should be able to switch Themes to be able to use your options panel. WordPress itself uses the edit_theme_options capability for menus, background, header, widgets, et cetera. 

    A note about network mode and Theme options:

    If you are using the edit_themes capability anywhere in your Theme, and the Theme is running on a network-enabled WordPress install (previously WordPress MU), be aware that the edit_themes capability used for accessing Theme options pages will prevent site admins in a network from seeing the options menu. Use edit_theme_options instead.

    Theme Testing Process

    1. Fix PHP and WordPress errors. Add the following debug setting to your wp-config.php file to see deprecated function calls and other WordPress-related errors: define('WP_DEBUG', true);
    2. Check template files against Template File Checklist .
    3. Do a run-through using the Theme Unit Test.
    4. Validate HTML and CSS. 
    5. Check for JavaScript errors.
    6. Test in all your target browsers. For example, IE7, IE8, IE9, Safari, Chrome, Opera, and Firefox.
    7. Clean up any extraneous comments, debug settings, or TODO items.

     


    Theme Custoization

    CSS Customization

    First things first, make a “style” directory in your Theme folder. That’s where we’ll be putting everything for CSS customization.


    Reset CSS
    Our Reset CSS is adapted from Eric Meyer’s famous Reset CSS with some minor, minor changes. Basically what it does is take all the typographical defaults of every browser and … obliterates them. You’re left with a squashy, gray mess.

    What this does is equalize the rendering of every browser, leaving you free to ignore countless individual quirks particular to each one.

    Using it is simple. Add the following lines to your style.css, at the very top, immediately after the initial comments section.
        
    /* Reset default browser styles */
    @import url('styles/reset.css');

    Reload, your page and check it what reset.css does in multiple browsers (if you can). It’s wonderfully gross, isn’t it?


    Rebuild CSS
    Our Rebuild CSS is my own personal invention adapted from an early version of the Blueprint CSS typography stylesheet and refined in the Thematic Project. What it does is swing back some vertical rhythm in our pages, but in a really smart way.

    What I’ve tried to do with this iteration of my typography-rebuild CSS is combine the best of both worlds for web typography: using Pixels for font height, with relative line-height for the main declaration on the body element, and Ems for all subsequent vertical margins (like for paragraphs and lists).

    What does this mean? It’s really easy to set your font height later—without doing any math work—and have all of your typographical elements follow suit with an appropriate vertical rhythm (the vertical space between type elements like paragraphs and lists).

    Using rebuild.css is also really easy. Just add the following lines immediately after your reset.css import.
        
    /* Rebuild default browser styles */
    @import url('styles/rebuild.css');


    The Basic WordPress Styles
    There are some elements in WordPress that you’re just going to have to style every time. What I’ve done is taken those styles and put them in there own little corner called wp.css.

    Right now, what we’ve got in there are styles for floating all the images—including handling captions and image galleries. And! preset styles for simple pull-quotes. All you need to do is add a class of left or right to the blockquote tag and you’re ready to roll.


    /* Basic WordPress Styles */
    @import url('styles/wp.css');
    All The Layouts You’ll Ever Need

    For your new theme, I’ve taken the rock-solid, indestructible layouts that shipped with the Sandbox Theme and adapted them for your new HTML structure. There are 6 in total. Each is a fluid layout (that stretches to fill the width of your browser window) but each one is easily adaptable to a fixed width layout.

    Using anyone of these layouts is simple. Immediately after your basic WordPress styles import, import one of these layouts. Here’s how to import the 3 column layout, with the content in the center.
        
    /* Import a basic layout */
    @import url('styles/3c-b.css');

    The simplest method of turning any one of these layouts into a fixed-width layout is to add a width and centering margin to the #wrapper div.
        
    #wrapper {
      margin: 0 auto;
      width: 960px;
    }


    Styling The Menu
    If you’ve never taken an unordered list (that’s the smart markup generated by wp_page_menu) and styled it to look like a menu before it can seem kinda weird. As a bonus, here’s the CSS I use when I start out creating menus for WordPress Themes.
        
    #access {
        margin: 0 0 1.5em 0;
        overflow: auto;
    }
    .skip-link {
        position:absolute;
            left:-9000px;
    }
    .menu ul {
        list-style: none;
        margin: 0;
    }
    .menu ul ul {
        display: none;
    }
    .menu li {
        display: inline;
    }
    .menu a {
        display: block;
        float: left;
    }

    It’s pretty simple.


    Making Your New Theme
    Find a theme you want to base your new theme off of. A good place to start is the default theme, but you may also want to just tweak another theme that’s closer to the look/feel you are going for.
    Copy the existing theme to a new directory in your themes directory for example if I was making a theme called “webdesign_meetup” I might copy the “default” directory into a new directory called “webdesign_meetup”.
    In your new theme directory edit the style.css file. You should see something like this in that file:

    /*
    Theme Name: WordPress Default
    Theme URI: https://wordpress.org/
    Description: The default WordPress theme based on Vskills.
    Version: 0.9
    Author: Vskills
    Author URI: https://vskills.in/
    */

    Edit the theme information. This is the information that will show up under Presentation -> Theme in the administrator.
    Go into the WordPress administrator and change your current them to the new one you just created.
    Now you can start customizing and see the affects in real time on your site!


    Wordpress Header Modifying
    The first thing you might want to do when customizing your theme is change the header. Most sites have a custom header image, usually a company logo or a picture that has to do with the theme of your site. To edit the header just go into your theme directory and edit the header.php file. The header HTML will usually be stored in this file. In some more rare cases theme authors may have placed header information in the individual page templates (if they did you’ll have to hunt around a bit more!). You’ll usually see a piece of HTML under the opening tag that’s something like lt;div id=”header”>…header content…

    . You can customize this content with your new header.

    Blog / Post Templates
    Maybe you want to display an ad at the bottom of each post, or perhaps you’d like to add or remove the author information under the post header? The place to do these things is in the single.php file. This file controls the layout of your individual post pages. Let’s examine the components of this file for the default WordPress theme:

    ?>

    This just calls your header.php template. It’s nice to use your header.php file to display all the common header HTML code for all your pages. That way you can avoid writing the same … and beginning … content over and over.

    class=”widecolumn”>


    if (have_posts()) : while (have_posts()) : the_post(); ?>

    Here is where we start “The Loop”. In WordPress each page normally has a “loop” on it that cycles through the content that should be displayed on that page. In our single.php template there would normally just be one “post”, which means the loop would just execute once to display that one post. The if (have_posts()) code first checks to see if we have a post to display, then the while (have_posts()) loops through each of the posts, the_post(); simply prepares the post for display. Most pages will have this same loop code on them. WordPress takes care of deciding what posts should go on which pages in most instances. Occasionally you’ll want to customize what posts are displayed within the loop, but we’ll cover that in a second.




    class=”alignleft”> ?>


    class=”alignright”> ?>




    Here the template is laying out some basic navigation that allows the user to move between blog posts. The previous_post_link() function places a tag that if clicked will navigate the user to the previous post in the blog. The next_post_link() is very similar.

    class=”entry”>

    class=”serif”>Read the rest of this entry »

    ’);
    ?>

    This code displays the actual post content (the content that you created under the “Writing” tab in the admin interface). The the_content(); function displays the HTML for the current “post” within “The Loop”. The argument within the function “…Read the rest of this entry…” is text that will be displayed in a
    tag at the end of the content if the content spans more than one page.

    So how do I add some author information and maybe date of the post to this?
    It’s easy! There’s a lot of information stored with each post that is accessible within “The Loop”. To see a list of all the functions you can use to get at this information visit this documentation page: https://codex.wordpress.org/Template_Tags. There you’ll see all the template functions that are available to you. So to get the author of the post we’d just call the_author();. Of course we’d want to put some HTML formating around it so we might do:

    This post was written by the_author(); ?>



    Now to put the date the post was written we could put:

    Published On ‘, ‘

    ’); ?>


    The Post Loop Customization
    The loop is powered off of the current page query. The query is generated by WordPress, typically from your URL. So if your on your site and your at /category1/a-blog-post-with-id-12 the query to get blog post id 12 in category 1. The internal mechanics of how this happens are fairly complex, so we won’t go into them. It’s enough to know that each page has a query generated for it that will grab the correct content for that page. So if you want to customize your loop and grab something besides what WordPress would do by default you need to modify the query before you call your loop.

    Let’s say you want to put just the 3 most recent blog posts on a page, maybe under some other content. On my site the home page has static content and then displays some recent blog posts. Here’s how you do it:

    ?>

    This does a new query to grab the 3 most recent posts to the blog. I can then display these posts in a normal loop:

    ?>

    Recent
    News



    the_post(); ?>

    class=”blog_post”>

       
    ?>

       


    ?>