June 27th, 2019

Setup and develop a custom Wordpress Theme from scratch with Bootstrap 3

Love it or hate it, Wordpress can be a very powerful framework for web development. It easily allows for site content to be updated without having to touch any code, which can make it a great solution for client projects.

Below I’ll show you the most painless way to setup a custom theme with custom pages in Wordpress in no time at all.

Covered in this guide:

  • Setup a local development environment
  • Install and setup Wordpress from scratch
  • Setup a custom Wordpress template
  • Integrate template to use Wordpress’ content editor

What we’ll be using:

  • Wordpress 5.2.2
    • Older and newer versions (4.x.x to 5.x.x) should work as well.
  • PHP 7.0.0
    • Newer versions should work fine.
  • MySQL
  • Bootstrap 3.3.5
  • MAMP (for local development)
    • I use version 3.5 even though they’re up to 5.3 now. Any version should work fine.

Let’s begin.

Setup Local Development Environment

1. Setup MAMP

The first step is to setup your local development environment. We do this to make it easy to develop and debug, and after we’ve launched, easily develop new features without touching the live production site.

I use a great program called MAMP, which is a local server environment for Windows and macOS. It’s nice because it handles all the initial setup of PHP, MySQL, and an Apache web server. Plus it’s free. Just download and install.

2. “Install” Wordpress

I put “install” in quotes because all the installation is is simply downloading the Wordpress files from the official Wordpress website and dragging them to a folder in MAMP.

The default folder for the MAMP web server is /PATH/TO/MAMP/htdocs. All files here will be served via MAMP’s web server. This can be changed under the Web Server settings tab.

MAMP's Web Server settings

A screenshot of the MAMP Web Server settings.

Simply create a new project folder with any name you’d like and drop the unarchived Wordpress files into it. It’ll look something like:

    • htdocs/
      • new-wordpress-site/
        • wp-admin/
        • wp-content/
        • wp-includes/
        • index.php
        • ...

3. Configure Database

One final setup we’ll have to take before running the Wordpress setup wizard is creating the local database table. Simply start MAMP’s server, navigate to the local MAMP WebStart page (probably something like http://localhost:8888/MAMP). From there, click on the phpMyAdmin link to navigate to phpMyAdmin (it might be under the “Tools” dropdown). Here you can view and edit your local MAMP databases.

A small aside

The default port for MAMP is 8888. But if that port isn't available, MAMP may default to a different port. Just check via the MAMP WebStart page to confirm. In this guide, I'll be using the default port.

On the left sidebar, click on the “New” option and name your database table, choosing (if applicable) a database encoding of utf8 and collation of utf8_unicode_ci.

Just creating the table is enough. Wordpress will take care of the rest in the next step.

4. Setup Wordpress

With everything setup and our database table created, let’s run the Wordpress setup wizard.

Simply go to http://localhost:8888/new-wordpress-site/ to begin the setup process. Then fill out all the relevant information. Refer to the MAMP WebStart page for database info, but most likely you can just use the following default values:

  • Host: localhost
  • User: root
  • Pass: root

Then you’re done!

The Wordpress database setup screen

The Wordpress database setup screen

Visit your Wordpress Admin dashboard by navigating to http://localhost:8888/new-wordpress-site/wp-admin and logging in with the credentials you just set.

Setup Custom Wordpress Theme

Wordpress File Structure: Themes Folder

There are a lot of different files and folders within Wordpress. For this guide, we'll only be interested in the theme folder, located at /wp-content/themes.

1. Setup Custom Theme

Wordpress by default comes with a few themes, with the default (at the time of writing) being “Twenty Nineteen”. Navigate to the themes folder and create a new folder for your new Wordpress theme. I’m calling mine custom-theme/.

Next, we’re going to use a starting template to save us the trouble of creating all the files required for a new theme. We’ll be using Simon Padbury’s BST theme. This theme is built using Bootstrap 3 already integrated, which is great. Download it and extract it into your new theme folder you created.

Now your theme folder should look like:

  • wp-content/
    • themes/
      • custom-theme/
        • css/
        • fonts/
        • functions/
        • ...

GitHub Repo Missing/Moved?

If the GitHub link above for BST has moved or isn't working, you can download the files here as well.

However, I always recommend downloading from GitHub instead to make sure you have the most recent version of the code.

Navigate into your new theme folder so we can update two quick things. First things first, let’s update the name of the theme. This is done via the style.css file. Simply update the info as needed, removing what you don’t.

Optionally, update the screenshot.png image as well.

2. Activate Custom Theme

Back in the Wordpress Admin dashboard, go to Apperance > Themes and you should see your new theme. Go ahead and activate it.

3. Set a Static Homepage

If you view your site again, you’ll see it’s now changed to use the new theme. But the default for Wordpress is to show you the blog for the home page. Let’s change that to use a static custom page instead.

Under Pages, create a new page called Home. Add a few quick lines into the content area, then publish.

Next, go to Settings > Reading, and change the radio option to a static page, choosing the newly created Home page as the option for the Homepage dropdown. Save your changes.

Setting the homepage

Setting the homepage

Now when you visit your website, you’ll see the new Home page displayed.

Create a Custom Page Template for Wordpress

We have our Home page setup, but let’s say we want a fully customizable page, HTML and all. In Wordpress, that’s not difficult.

Wordpress handles custom pages via templates. You can have multiple pages all use the same template. And each template is just a PHP file.

To start:

  1. Create a new folder called custom/ located in your custom theme folder (custom-theme/).
    • This will be used to hold all the templates and keep our file structure from getting messy.
  2. Create a new PHP template file in your custom/ folder.
    • I’m calling mine custom-template.php
  3. Open up custom-template.php (or whatever you called it) and add the following:

     <?php /* Template Name: Our New Custom Template */ ?>
     <h1>Hello from our new custom template</h1>

    It’s vital that the Template Name PHP tag is always at the top of your template files. Everything else goes below. The name “Our New Custom Template” will be the name of the template, and can be anything you’d like it to be.

  4. Go back to the Wordpress Admin dashboard and click on Pages. Then edit the Home page. On the right sidebar, look for a “Template” dropdown. Choose your newly named template and click save.
  5. Go back to your homepage and you should see your new page appear!

Add Wordpress Fields into Custom Template

You now have a fully customizable Wordpress template for your pages. But we aren’t using Wordpress just for static sites. Let’s hook in Wordpress to display the content from the page’s content editor.

Back in your custom-template.php file, replace the code with the following:

<?php /* Template Name: Custom Page */ ?>

<div class="container">
    <div class="row">
        <div class="col-md-12">
            <h1>Hello from the custom template!</h1>

            <?php if ( have_posts() ) : while ( have_posts() ) : the_post();
            endwhile; else: 
                // No content to display
            endif; ?>

Now when you refresh your homepage, you should see your content (if you don’t make sure you added something on the Home page editor in the Wordpress Admin section).

The Loop

Why do we have code called have_posts() if we're not dealing with posts? Well because Wordpress started (and still is) a blogging platform, this is just one of the paradigms it uses.

You can learn more about The Loop here.

Advanced Custom Fields

In a future guide, I'll explain how to use Advanced Custom Fields as well. It's a great tool for creating smaller editable elements of the site.

However, you’ll see the site isn’t themed yet. That’s because we haven’t included our Wordpress header or footer. Let’s drop those in. Update your code to the following:

<?php /* Template Name: Custom Page */ ?>

// Add this
<?php get_template_part('includes/header'); ?>

<div class="container">
    <div class="row">
        <div class="col-md-12">
            <h1>Hello from the custom template!</h1>

            <?php if ( have_posts() ) : while ( have_posts() ) : the_post();
            endwhile; else: 
                // No content to display
            endif; ?>

// And this
<?php get_template_part('includes/footer'); ?>

Now when you refresh, you can see all the CSS has been included as well.

If you’d like to edit the header and footer, they can be found in the includes/ folder.

You’re all set! You’ll now be able to create custom Wordpress pages from scratch with the ability to update them easily without having to touch code. There’s no limit to the number of templates you can have.

Happy coding! 🎉