Creating a Custom Theme

In this tutorial we will:

  1. Create a Theme
  2. Add index.php
  3. Add single.php
  4. Add a custom template

theme is a group of files in charge of specifying the look and behaviour of our data.

By separating the presentation, from the system, we can upgrade/update our site without drastic changes to its visual specification.

We recommend using a vanilla theme as a start. "Starkers" is a good option and can be downloaded from GitHub. We will go through how to create a theme from scratch below.

Theme's Anatomy

WordPress themes live in wp-content/themes/ by default. The themes subdirectory holds

  • Stylesheet files
  • JavaScript files
  • Template files
  • functions.php
  • Images

Template files

Templates are PHP source files used to generate the pages requested by visitors.

They contain HTML, PHP and WordPress Template Tags.

In WordPress content is displayed in the form of posts and pages. In a typical news website or magazine we would specify our articles as posts. Pages are used to present timeless information, such as the 'About' or 'Contact' sections.

The most important templates we will be dealing with are:

  • index.php - The main template, used when WordPress can't find any other templates.
  • single.php: - The single post template. Used when a single post is queried.
  • page.php: - The page template. Used when an individual Page is queried.

We can also create as many custom templates as we need.

Other files

You can add other files such as to your theme such as javasript files or default images can be added to your theme. 

A useful file to add is function.php. This can hold common function called by different template files.


A theme is defined in style.css. In this the theme details are specified in the form of comments. Those details will be the ones displayed in the Theme selection dialog.

Open a new css file and copy the comment below into the top of the file. The rest of the file can remain blank.

Theme Name: My Theme
Theme URI:
Description: This is my new theme
Version: 1.0
Author: Kaldor Ltd
Author URI:

Save the file in to your .../wp-content/plugins/my-new-custom-theme folder.

In the same Theme selection dialog each theme is assigned an image. To change the default one, save yours as screenshot.png in the theme root. The recommended image size is 600×450. The screenshot will only be shown as 300×225, but the double-sized image allows for high-resolution viewing on HiDPI displays.

With these changes, we should be able to see the following:

STEP 2: Add index.php

index.php is the default WordPress template. It is used when WordPress cannot find any other templates. Create a default template. Don't worry about this too much for now. Ideally your post will never use this template.

At the beginning of all template you should get the post/page ID. You can then use this ID to call data from the post. Use the WordPress built in function get_the_ID() to do this. An example of an index.php might be:

<?php $post_id = get_the_ID(); ?>

<body> require_once('common/header.php); ?>
<p><?php echo get_post_meta($post_id, 'body'); ?></p>
<?php require_once('common/footer.php); ?> 

'body' is the default content typed into the rich text editor in WordPress. get_post_meta is the main WordPress function to call data from a post.

STEP 3: Add single.php

single.php is the default WordPress template for posts. 

A usual structure consists of single.php displaying the content and referencing the header and the footer templates.

Another possibility is to allow the user to specify their desired template from a dropdown menu for every page in the cms, and accordingly reference it from single.php.

In the example below we have created a metabox 'Article info' in our plugin with the custom fields 'Section' and 'Template'. The custom field 'Template' has the id pugpig_templates

In your single.php you can then define which template file you want your post to use:

$post_id = get_the_ID();
$template = get_post_meta($post_id, "pugpig_templates");
if (!empty($template)) {
    switch ($template){
      case 'hero':
        Pugpig_Project_Utilities::get_template_parts( array('parts/content/hero') ); break;
      case 'roundup':
        Pugpig_Project_Utilities::get_template_parts( array('parts/content/roundup') ); break;
      case 'interactive':
        Pugpig_Project_Utilities::get_template_parts( array('parts/content/interactive') ); break;
      case 'shop':
        Pugpig_Project_Utilities::get_template_parts( array('parts/content/shop') ); break;

Create a single.php file and add some logic to choose a template.


Your custom template should output some html to make our data look elegant. In our Create a Custom Plugin we created the field pugpig_background_image. Here we will call the field and insert it in our template. 

<?php $post_id = get_the_ID(); ?>

<body background="<?php echo get_post_meta($post_id, 'pugpig_background_image; ?>"> require_once('common/header.php) ?>
<p><?php echo get_post_meta($post_id, 'body') ?></p>
<?php require_once('common/footer.php) ?> 

You now have a Custom Theme with a Custom Template. Don't forget to activate your theme!


Have a look at the other How To Guides (Wordpress) and How To Guides SDKs

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk