How to Build a WordPress Starter Theme: Part 2 – Initialising the Theme

3

In this part of the series, we’ll be setting up our WordPress installation, configuring our local server, installing a comprehensive amount of dummy content designed for testing themes, and then we’ll create the necessary files to get our WordPress Starter Theme to show up in the backend. We have a lot to cover, so you’ll want to be up to speed with our previous parts in the series.

Setting up WordPress

As I mentioned in Part 1, I won’t go into the actual installation of WordPress itself here. I’m making the (reasonable) assumption that anyone looking to start building WordPress themes is a moderate to advanced WordPress user and has installed WordPress enough times to know the process themselves. Also, you may choose to install your starter theme on a live hosted server. Nothing wrong with that, as long as you have FTP access to the full WordPress installation including the wp-config.php file in the root of the WordPress installation, you’ll have no trouble following along. For brevity, when I mention the server environment/WordPress installation, I’m speaking of a local install.

That said, I’ll cover a few things I do once WordPress is installed so we’re all on the same page. First thing I always do is set up the Settings in WordPress so my permalinks are clean, depending on the type of site turn my comments on/off globally, and turn off search engine indexing if working on a test server.

So, in Settings > General, the first thing I do is set the correct timezone. For me that’s “Dublin” – for you, obviously set it to the appropriate timezone. This is more habit than necessarily important in this case. This is also a good time to check everything is correct after the install process, such as email, site title and tagline information.

Next, under Settings > Reading, we’ll leave “Front Page displays: Your latest posts”. It’s a good idea to set check “Discourage search engines from indexing site” if you are on a live server, but not ready for prime time. For example, I often begin building a sites for clients (or my own projects) on a subdomain such as demo.example.com, until I’m ready to migrate to the main domain. In this case, you don’t want engines poking around before you’re ready.

We’ll leave everything in Settings > Discussion and Settings > Media as they are, so comments are turned on site wide and WordPress handles media and images in the default manner. We need to test our theme with the defaults before testing for anything more customised.

Lastly, in Settings > Permalinks, I set permalinks to “Post Name” under “Common Settings”, which gives us clean URLs. Now, if you find your installation of WordPress breaks after doing this, there’s a few things you need to do to set up your local server. I’ll cover all of them next.

Configuring our Local Server for WordPress

httpd.conf

Depending on your server (WAMP/LAMP/MAMP/XAMPP) the directory to these files will be different (obviously). I’ll be using XAMPP seeing as it supports the widest range of OS. It’s one of the few AMP stacks that works on both Windows and OS X.

Please note: If you haven’t experienced any issues when changing permalinks in WordPress, you can skip this part and move onto editing the php.ini file.

To access your httpd.conf file on XAMPP, open your control panel and you’ll see on the Apache line (which is your server) a Config button. When clicked, you’ll see a list appear. The first option should be httpd.conf. Click that and the file should open in your operating system’s native text editor (like Notepad or Nano).

The easiest method to find things in this file is to use the “Find” feature of your text editor. We want to find the mod_rewrite module, so do a search for it. The line you’re looking for is #LoadModule rewrite_module modules/mod_rewrite.so.

The hash symbol, #, is used for comments in the configuration files of your server. Remove the hash before this line to turn the rewrite module on: LoadModule rewrite_module modules/mod_rewrite.so.

Next, do a search and replace for AllowOverride None and replace it with AllowOverride All. It should appear about 2-3 times in the httpd.conf file.

Save and close the file. At this point, you’ll need to restart your server. WAMP users have a handy restart option, but for XAMPP, you’ll have to stop and then start the Apache server again.

php.ini

Next, we need to increase our memory limits in the php.ini file. There are a few reasons for doing this:

  1. Having too low a memory limit will mean slow page load times on a local install, depending on, of course, your computer’s spec.
  2. Low memory will severely limit how many plugins you can install, although you should resist the urge to simply throw plugins at a problem. My general rule of thumb is (except for eCommerce & BuddyPress sites) keep your plugin usage at a maximum of seven. Even when you start getting near seven you should have a look if there’s a more efficient way of doing things.
  3. Most importantly for our purposes, low memory and low upload limits in the php.ini file will prevent us from fully utilising the Import/Export features of WordPress for installing our dummy content.

From the XAMPP control panel, select Apache > Config > php.ini. The file will open and again we’re going to perform a find and then increase our memory_limit and upload_max_filesize.

So first, do a find for memory_limit. It will most likely be set to 128M. I generally double this to 256M, however, if you have a lot of RAM and processing power, feel free to go up to 512M.

Now, we need to increase how much data we can upload through our server (and thus, through WordPress). Do a find for upload_max_filesize. This will be either 16M or 32M depending on your chosen server. WordPress requires 64M for numerous things including bulk uploading images and media, uploading/installing themes and plugins when when installing from zipped files and when importing dummy data, which is what we’ll be doing next. So, set this to 64M. You can save and close the file now, however, I want to draw your attention to some other noteworthy settings in this file which you may wish to increase if you still have problems.

  1. max_execution_time – This may need to be increased if you find WordPress gives you errors that scripts failed to execute or if you’re getting along the lines of “Max execution time exceeded”. Around 300 should be fine for general WordPress sites.
  2. max_input_time – Again, increase this if you keep getting errors when uploading files in WordPress. 120 should work fine in most cases.
  3. post_max_size – If you still have issues when uploading files in WordPress, make sure this equals whatever you have upload_max_filesize set at. If post_max_size=16M and upload_max_ilesize=64M, your max is still 16M if the field is using $_POST to sent the data. However, if you reverse these (so post_max_size=64M and ) then you can send four files of 16M in one request before hitting the limit.

That should do it for configuring our server. Let’s install some dummy data!

Installing the Test Data

When I started building this theme, I wanted to do my best to meet WordPress standards from the beginning. I initially assumed that this would all be about tracking down and fixing PHP errors and notices, and constantly making sure I followed best practices laid out by the Codex, but while on one of my many searches for debugging and unit testing for WordPress, I came across WP Test.

WP Test is “A fantastically exhaustive set of test data to measure the integrity of your plugins and themes”. The test data ranges from posts, pages, embedded Tweets, and oddly sized images, to test posts designed to test your theme’s design and compatibility with popular plugins such as Jetpack. Aside from that, it’s a great way to quickly get all the images and text you could possibly need to see exactly what is going on while we build a theme – and the content is a lot more interesting and amusing than boring old lorem ipsum!

To install WP Test:

  1. Go to http://wptest.io and click the download button.
  2. Extract the ZIP file. I like to keep all of my WordPress related downloads (themes, plugins etc.) in a folder in my htdocs directory for simplicity’s sake.
  3. Now, in WordPress, go to Tools > Import. From here, choose WordPress and Install. Then Activate Plugin & Run Importer.
  4. Browse to the wptest-master directory and select the wptest.xml file. Then select Upload File and Import.
  5. The next screen allows you to change the assigned authors to the posts and content being uploaded. For a local install you can leave these, but if you plan to use this on a live server, be aware that this also creates the users, and thus the passwords and login details need to be reset – or simply assign all the authors material to your own account. For now it’s useful to have various authors created. At the bottom you’ll need to make sure Download and import file attachments is checked. This will import the images from the upload directory in wptest-master. Select Submit and wait for everything to import – it can take a while so go make some coffee! If this fails or you get any errors, refer to the php.ini section above.

References and Themes

When I first built this starter theme, and anytime I’ve built any theme since, I’ve always used a few references which have made things much easier. There’s no way you could be expected to remember every function or code snippet needed to build even the simplest of themes. Therefore, all throughout this series you should have The WordPress Codex open in a tab, and bookmark certain pages as we go.

The first of those pages to bookmark is the Function Reference, and second is the Theme Development section. In fact, at this point you should read through the Theme Development page. Don’t worry if a lot of it doesn’t quite make sense right now – as we get deeper into the different parts of the theme, more and more of it will become clearer. I’d recommend reading through it each time you’re about to start working on your theme. It’s almost like a roadmap/checklist which will keep you on track.

The other references I used were the Twenty Fourteen theme, and a theme called Naked WordPress by Joshua Beckman. As I worked on each file, I would also open the same file in the twentyfourteen directory and the naked-wordpress directory. Both have useful comments, and along with The Codex, they will ensure that you best understand what each function and template tag is doing, and why they’re required.

Once you have all those themes installed, we’re ready to open our text editor and start editing our files.

WP_DEBUG

Regardless of whether you’re on a local server or a live production server, WordPress is set up to hide PHP errors from you by default. When you’re building a theme or a plugin, it’s extremely useful (I’d almost argue necessary) to turn on PHP errors and notices so you can immediately see when and where something has gone wrong. We all “fat-finger” a function name or variable every once in a while, and without seeing what line the errors are on, then you’ll go to check your theme in the browser and at some point you’ll see “the white screen of death”. Not much good to you.

To turn on errors and notices in WordPress:

  1. Navigate to the root of your WordPress install.
  2. Open the wp-config.php file in your text editor and do a find for WP_DEBUG.
  3. Change this from false to true and then save and close the file.

Simple! Now you’ll see any errors and notices if and when there are any whilst working on your theme.

Creating the Required Theme Files

Solid preparation is key to any project. That said, it can be tedious. You’ll be happy to hear that all the boring prep work is done now and we’re ready to start working on our theme.

To get a theme to actually show up in WordPress, you technically only need two files. Seeing as we’ll be working in an interactive workflow (simple first and gradually getting more complex) we’ll start with the bare minimum amount of files necessary.

So, to get started:

  1. Create a directory in the wp-content/themes directory. Call it whatever you want your theme to be called. For me that’s noesis. Remember to keep it all lowercase, and use only letters and hyphens, instead of underscores or spaces.
  2. If you plan on submitting your theme to the WordPress repository or as a premium theme, then now is a good time to do a search and make sure your chosen name isn’t already taken. Noesis wasn’t my first choice…
  3. Inside your theme directory, create the following files: index.php and style.css.

style.css

In the style.css file, you’ll need to add a commented header which WordPress uses to display information about your theme in the Appearance > Themes area and on the WordPress repository.

Go to the Theme Development page you bookmarked before (you did bookmark it, didn’t you…?).

Scroll down to the Theme Stylesheet section, and copy the comment block.

Paste it into your style.css file and change the information to your own. Here’s what I’ve added in mine:

/*
Theme Name: Noesis
Theme URI: http://demo.luke-watts.com/noesis
Author: Luke Watts
Author URI: http://luke-watts.com/
Description: Semantic, minimally styled starter theme.
Version: 1.0
Tags: semantic, minimal styles
Text Domain: noesis

This is a minimally styled starter theme which will be the foundation of all future themes....EVER!
*/

This is a good time to mention that if you go to the Theme URI above, you can see the finished Noesis theme, if you’d like. It’s certainly not going to win any design awards but that’s not it’s purpose.

Once that’s done, save the file and open index.php. For now, we’ll simply add our opening PHP tag and a docBlock with some information about what this files does. The following is taken from the twentyfourteen index.php page with the relevant amendments:

<?php
/**
 * The main template file
 *
 * This is the most generic template file in a WordPress theme and one
 * of the two required files for a theme (the other being style.css).
 * It is used to display a page when nothing more specific matches a query,
 * e.g., it puts together the home page when no home.php file exists.
 *
 * @link http://codex.wordpress.org/Template_Hierarchy
 *
 * @package WordPress
 * @subpackage Noesis
 * @since Noesis 1.0
 */
?>

Now if you go to Appearance > Themes, you should see your theme among the available themes to activate. Click Theme Details, and the information you placed in the style.css comment block should be displayed. It is… excellent! If not, just make sure the comment block is correct and that you have no spelling mistakes in the Theme Name tag – or any other tags for that matter.

If you activate the theme now, you should see no errors also. However, clicking on Visit Site will show you a white screen. This is expected since we have nothing in our index.php file.

In Summary

Congratulations! You’ve got your new WordPress Starter Theme to show up in the backend! You’d be surprised how large a part of the battle that is.

From here, any HTML and PHP you insert into the index.php file will appear. You could even give it a go right now! Simply copy over the HTML from your index.html file, paste it in after the closing PHP tag, save it and check it in your web browser. You should see your page as it was at the end of Part 1.

In the next part, we’ll be moving over our HTML and replacing certain parts with PHP tags, allowing us to utilise the power of WordPress.

Any comments and feedback will be much appreciated. See you in Part 3!

Share.

About Author

Founder and Lead Developer at Affinity4.ie, a web development agency in Galway, Ireland. Develops mosty with WordPress, Laravel, PHP, MySQL, Git, Github, Sass and Compass.

Leave A Reply

  • http://www.samberson.com Sam Berson

    Hey David, I’m glad you’re enjoying the series! Part 3 will be published within the next couple of days.

  • Gareth Milligan

    Nice job Luke, very informative

    • http://luke-watts.com/ Luke Watts

      Thanks Gareth. Part 5 should be up during this weekend (19th – 20th).