Bootstrapping WordPress Theme Development with Sage

If you are familiar with WordPress theme development, you know things can get a little messy when you are starting from the ground up. Building a theme from scratch is not easy, and setting it up can take a lot of the time you have, even before you start to write actual code. Because of this, developers have built starter themes, which are themes with code to display posts, pages or anything, but they lack on design and have a minimal layout. This allow us to not worry that much about how to bring content from the database so we can focus from the beginning on its presentation.

There are some key points you need to be aware of when choosing a starter theme: documentation, support, technical features and maintenance. You will need documentation and support when you are learning to use a theme, and when you have started developing and need troubleshooting the errors you might make. You need to know what tools are included in the starter theme, if it is compatible with browsers and your own tech stack, and if it suits your project purposes. Also, you want it to be updated constantly, so you can be sure you are up to date with the standard tools and your theme stays compatible with newer versions of WordPress all the time.

Here at Swapps we use Sage, a starter theme developed by Roots based on HTML5 boilerplate and it comes with features that help us to create new themes in a fast and clean way. It includes Bower, Gulp, Browsersync and Bootstrap, defining a workflow that you can use to build your theme. In case you don’t know what these tools are for, I’ll give you a short description:

• Gulp takes care of common frontend tasks and does them for us. That includes, but is not limited to, minifying CSS and JavaScript files, compiling CSS preprocessors, image optimization, concatenation of files and code linting.
• Bower is a front-end package manager.
• Bootstrap is a widely used CSS framework made by Twitter engineers, it allows us to create responsive, good-looking sites using predefined classes in short time.
• Browsersync synchronizes file changes in multiple browsers and devices (we don’t have to reload every time we save a change).

Note: new version (Sage 9) uses Webpack instead of Gulp and relies on npm instead of Bower for managing dependencies.

Sage has strong documentation and a forum where the community or even the Sage developers themselves can solve any problem you might have. They also include a README file into the project that you can use to get started. The Sage team is also aware of new technologies and trends in web development, i.e. using Webpack in their new release as I said above, so you can be sure that a theme based on Sage will always be updated with the best technology at the moment.

Installation

So, how do we install it? First make sure you have these installed:

• PHP 5
• Composer
• Node.js
• Git

You need to install Gulp and Bower in order to use them, but this is easily done with Node.js using npm. Just type npm install -g gulp bower in your console.

Go to your WordPress themes directory, at this point we have two ways to install Sage. First one is cloning the repository:
git clone https://github.com/roots/sage.git theme-name
Other way is through Composer, using this command:
composer create-project roots/sage theme-name 8.5.0
Either way, don’t forget to change theme-name with the name you want for your new theme. Also, you can download the Git repository as a .zip file and extract it in your theme but we prefer automated things, right?

File structure

You can see the common WordPress files (index.php, functions.php, single.php, page.php, etc) at the root of your theme folder. There we have the lib directory, where the specific Sage configuration is stored. There is also the assets directory, where we can put our images, styles, scripts and fonts. The templates directory contains files for all templates we commonly see in a WordPress theme, the key difference being they are based on HTML5 and they have improved accessibility using ARIA roles. dist folder contains the processed assets that are going to be used in our live site, they are the result of the automatized workflow and should never be edited. Sage is multilingual ready, so we have a lang folder containing a file named sage.pot, in case you need translations.

Customization

You can setup your Sage installation editing the files included into the lib folder. There are some files serving different purposes:

• assets.php, here is where styles and scripts are enqueued.
• extras.php contains functions for adding classes to and a link to continue reading at the end of posts excerpt.
• setup.php is where the main configuration is stored, you can enable/disable theme support for WordPress features, register sidebars and navigation menus, and choose in which pages do you want to display a sidebar (or not)
• titles.php controls the output of page titles.
• wrapper.php has the functionality for Theme Wrapper

The basic setup is done in setup.php, here are some snippets of the most essential features.

// lib/setup.php
add_theme_support('title-tag'); // Enable modifying the title tag on your web page.

add_theme_support('post-thumbnails'); // Enable WordPress featured images.

// Add navigations, a primary navigation is registered by default.
register_nav_menus([
'primary_navigation' => __('Primary Navigation', 'sage')
]);

// Types of posts enabled by default. Modify this as you need.
add_theme_support('post-formats', ['aside', 'gallery', 'link', 'image', 'quote', 'video', 'audio']);

// Enable support for HTML5 markup in the sections listed.
add_theme_support('html5', ['caption', 'comment-form', 'comment-list', 'gallery', 'search-form']);

// Specify path of the stylesheet for customizing the TinyMCE Editor used by WordPress.
add_editor_style(Assets\asset_path('styles/editor-style.css'));

// Here you can add sidebars to your theme. By default, Sage comes with Primary and Footer sidebars.
function widgets_init() {
register_sidebar([
 'name' => __('Primary', 'sage'),
 'id' => 'sidebar-primary',
 'before_widget' => '

We have seen enough into the lib folder, lets go to the assets folder. Here are two files you may want to pay special attention. First one is styles/main.scss; this file generates the main CSS files stored in dist/styles. Here is where you need to import all of your custom styles, and here will be injected all the Sass dependencies coming from Bower packages. The other file that deserves our attention is scripts/main.js; this file behaves the same as its styles colleague. It will load scripts from our installed Bower packages, and it will output the final JS file stored in dist/scripts folder. A singularity about this file is that it's structured in a way that you can put general code that will be loaded in all pages, and add specific page scripts that will be fired only in homepage, for example. So, You must take these two files into account when developing the front-end for your site.
 
Sage Theme Wrapper
 
The Theme Wrapper is a key feature of Sage, and it's a reason why it is different from other starter themes because it follows the DRY principle (Don't Repeat Yourself).

You may have noticed a file at the root of your theme folder called base.php. Well, this file is the skeleton for all pages in your site. It contains the main structure of an HTML document, and manages the load of commonly used sections as the header, the footer and the sidebar. The magic here is that Sage makes this file as the starting point for WordPress Template Hierarchy, so the code and markup in it will load in every page. Thus, you don't have to worry about putting the same pieces of code in whichever file you edit or create, and you can focus solely on the specific markup and display logic of that file. Besides, any general modifications to the main structure of pages are painless and you only need to change a single file to get this. Code is just written once, where it belongs, and you will save a lot of time and energy maintaining it.
 
Conclusion
 
Starter themes are a great way to start developing a new theme; they can speed up the process and bring you a workflow for an efficient coding. Sage, in our opinion, stands out from the rest because follows the DRY principle, comes with preconfigured tools that will help you to automatize processes and dependencies, it's easy to install and understand, and has a great support. With it, we can get done a solid WordPress theme in really short time.