Vanilla Wordpress Template DocumentationVanilla Wordpress Template Documentation, Release 1.0 During this step, we also recommend renaming the theme folder to the name of your theme

Vanilla Wordpress TemplateDocumentation

Release 1.0

Code My Views Inc.

October 29, 2016

Contents

1 Overview 31.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Pre-Requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.3.1 Step 1: Clone the repository from Github . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.2 Step 2: Composer Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.3 Step 3: Create .env file in project root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.4 Step 4: Create local MySQL database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.5 Step 5: Serve site in local dev environment and view site . . . . . . . . . . . . . . . . . . . 4

2 The Basics 72.1 WordPress Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 What’s Included . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.3.1 Latest WP Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3.2 Gravity Forms Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3.3 Advanced Custom Fields Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3.4 Laravel Blade Templating Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4 Theme Config File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5 Asset Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Theme Components 113.1 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.1.1 Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.1.2 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.1.3 Partials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2 Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.3 Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4 Custom Post Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.5 Taxonomies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.6 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.7 Options panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.8 Custom Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.9 Media Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.10 WYSIWYG Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.11 Sidebars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.12 Shortcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.13 Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

i

3.14 The Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.15 WP_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4 Helper Functions 194.1 Helper::image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.2 asset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 How To Build a WP Theme 215.1 Step 1: Views, Partials and Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.2 Step 2: Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.3 Step 3: Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.4 Step 4: View Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.5 Step 5: Dummy Content and Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.6 Step 6: Options Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.7 Step 7: Custom Field Definitions, Sidebars and Shortcodes . . . . . . . . . . . . . . . . . . . . . . . 235.8 Step 8: Make the views dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.9 Step 9: Endpoints and Advanced Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.10 Step 10: Testing, and production ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6 Appendix A: Windows Local Dev Environment Guide 256.1 Step 1: Download all of the packages here: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.2 Step 2: Restart Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.3 Step 3: Start Wamp Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.4 Step 4: Install Apache Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.5 Step 5: Install Apache Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.6 Step 6: Enabled PHP Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.7 Step 7: Edit Apache Config File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.8 Step 8: Restart WAMP Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.9 Step 9: Put WAMP Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.10 Step 10: Is it working? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.10.1 Step 11: Installing a new site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.11 Step 12: Edit your host file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.12 Step 13: Add the vhost configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.13 Step 14: Does it work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

ii

Vanilla Wordpress Template Documentation, Release 1.0

Contents:

Contents 1


2 Contents

CHAPTER 1

Overview

This documentation was created to accompany the Vanilla WordPress Boilerplate by Code My Views.

1.1 Motivation

The purpose of the Vanilla boilerplate is to simplify the process of taking static HTML/CSS and templating it out intoa custom WordPress theme.

The end goal in building a custom WordPress theme is to make it as easy as possible for the end user to update thecontent of their site.

The input into this process is static HTML/CSS. The expected output is a very easy to use WP theme using the variouscomponents you have available to you below.

When you are building out a WP theme, it is important to think of the end user experience. How can you setup thetheme so it is as easy and foolproof as possible for the end user.

1.2 Pre-Requisites

Before you can really benefit from this starter theme, you should have an already completed front end(HTML/CSS/JavaScript) of the site you are building. This starter theme will simplify the process of taking the staticHTML/CSS/JavaScript that you have created, and then integrating it into WordPress so that all of the content andpages are controlled via the WordPress CMS.

1.3 Installation

If you do not already have a local development environment setup, you will need to do that. Depending on whetheryou use Mac, Linux, or Windows for you local environment, we have a few guides.

• Mac / Linux Dev Environment Setup (tbd)

• Appendix A: Windows Local Dev Environment Guide

1.3.1 Step 1: Clone the repository from Github

git clone [email protected]:codemyviews/vanilla-wp-boilerplate.git ~/Code/sample-project.dev

3

https://github.com/codemyviews/vanilla-wp-boilerplate

https://codemyviews.com


During this step, we also recommend renaming the theme folder to the name of your theme. By default, the themefolder is called base-theme, but you can name this whatever you want.

1.3.2 Step 2: Composer Install

If you do not already have Composer installed on your computer, you will need to download and install it here:https://getcomposer.org .

Once you have Composer installed on your machine, you will need to open your Terminal (or Git Bash if you are onWindows) and then move to the root of the project directory and install the composer dependencies.

cd ~/Code/sample-project.devcomposer install

1.3.3 Step 3: Create .env file in project root

Within the project root that you cloned from Github, you will see a file called .env.example. Create a copy of this fileand call it: .env

Within the .env file, update the values to match the values of your local dev environment.

Here is a sample .env file:

WP_DEBUG=false

THEME_NAME=wordpress-starter-templateDB_NAME=sample-projectDB_USER=homesteadDB_PASSWORD=secretDB_HOST=192.168.35.40

WP_HOME=http://sample-project.devWP_SITEURL=http://sample-project.dev

AUTH_KEY='I[z(B/7@SfM+/0jc-69g&s,?&;ZGi-f{vvuJSh=7!>MkUF|6|LddV?i[W(#5-(L?'SECURE_AUTH_KEY='-qP,OJsa 9MIu(I1T4$f{c+y$GEZq<NF84X/~HL{{D5Gw#3GyO DW#84|.pO#^#.'LOGGED_IN_KEY=''}vl}r-A|72AI,#Z|0&#pNxC3Fu -)b|HA!zM1TLx4!]sCAW_BYp@#`E;hEm8uluV'NONCE_KEY='J[HDf&`lIE X]QQ;f<A(DMQx^>a+uCG-J4OTUOK!OH0==P9h@k?6FnS$P)2h~=f@'AUTH_SALT='T$wP9:j,X1.]IyWqI+R`>XqjL(KLSJS67cdgg7g`B{QsL~Vg{Gt*6ymI;Tb3:R|@'SECURE_AUTH_SALT=';c,xJR?f$Si_z$ Hm|dZvrS/_mC<wqoNjpm8 ARRU3sfDS1X!+6$>bAk0ZU7~e{,'LOGGED_IN_SALT='>*Bh2A&|v#ICPE-ARoVRrM-k+/;!b.8V?N%:u#fIozlBKM9B(^mn|ha?-+aZNlL['NONCE_SALT='LRWOV$5U90_Thc,SPc8&!_-F-:-caR2sV;R$~qbu#9J[Tl{nu4#$6Mi=gDw FQic'

TABLE_PREFIX=wp_

1.3.4 Step 4: Create local MySQL database

You need to create a new MySQL database in your local dev environment. The name of the database should match thevalue of DB_NAME from the .env file you created in the previous step.

1.3.5 Step 5: Serve site in local dev environment and view site

As a final step, you will need to ensure that you setup the site to be served within your local dev environment. Pleasefollow the instructions in your local dev environment setup guide if you have questions about this. The important

4 Chapter 1. Overview

https://getcomposer.org

https://git-scm.com/downloads


detail to note here is that the public path for the Vanilla boilerplate theme is this:

~/Code/sample-project.dev/public

Once you have the site setup to run locally, you will be able to visit the site in your browser at whatever domain yousetup for serving. For example, http://sample-project.dev .

As a last step, you should visit the URL http://sample-project.dev/wp-admin in your browser to finish the installation.

When you finish this step, you should be able to login to your wp-admin area, and then activate the boilerplate theme.

1.3. Installation 5

http://sample-project.dev

http://sample-project.dev/wp-admin


6 Chapter 1. Overview

CHAPTER 2

The Basics

2.1 WordPress Core

Please note that within this project, we are not only including the Vanilla theme, but also WordPress core in its entirety.The reason why we include the latest version of WordPress within the project repository itself is because it makes iteasier to automate deployments of sites that are built using the Vanilla boilerplate template. If you wanted to removeWordPress core, and simply install the theme manually into WordPress somewhere else, that would work as well.

With that being said, as a best practice, even though we include WordPress in the project repository, you should neveredit or delete any of the core WordPress files that exist in the wp-admin or wp-includes directory. This is where all ofthe default WordPress magic exists, and there is no need to edit anything here. In fact, editing files here may causeissues for you in the future in the event that you update the WordPress version because this will replace all files inwp-admin and wp-includes directories. Also, as a general best practice, you should never edit core files in any project.

2.2 Directory Structure

This is the directory structure of the Vanilla theme itself. The theme directory is in public/wp-content/themes, whichis where all of your theme coding and customization will happen.

• assets - All static assets

– compiled - This directory should largely be untouched by you. This is where compiled assets end up.More on this later.

– js - Javascript files

* plugins - All JavaScript plugins your front end uses go here

* custom - All custom JavaScript or jQuery should go here

* sass - Default SASS directory (this can also be a less/ directory if your front end uses less).You should place all of your SCSS or LESS files in this directory.

* images - Place all of the images from your front end into this directory.

* fonts - If your front end uses any custom fonts, you can place the font files in this directory.

• core - This is all of the core theme files. This is where the magic of the Vanilla theme happens.

• endpoints - This is where we place any endpoints that are needed in the theme. For example, if your theme hasa contact form, you will likely create a file in this directory called contact-form.php.

• field-groups - This directory contain the code that generates the various Advanced Custom Fields that areneeded in the theme

7


• views - All views for the theme

• forms - This is an optional directory where you can store any form partials

• layouts - Fundamental layouts of the templates

• partials - Various includes (Header, Footer, etc.)

• shortcodes - If your theme will have any custom shortcodes, you can place the template files for the shortcodesin this directory.

• sidebars - For any custom sidebars, you can place them in this directory.

• views - This is where all of the different views will go for your theme

• 404.php - the default 404 template for the Vanilla theme. This can be customized as you see fit.

• functions.php - This file behaves just as a functions.php file would behave in any WordPress theme. You canplace any WP customization code here as needed

• gulpfile.js - This file is what we use to compile all of the JavaScript and SASS/LESS from the assets directoryinto the assets/compiled directory

• package.json - This file defines the Node.js packages that are required for the gulpfile to work correctly (moreon this later)

• ** screenshot.png** - This is the screenshot that appears on the theme activation page in wp-admin. Feel freeto replace this with any image you want.

• theme-config.php - The config file for Vanilla. This is where the bulk of the configuration will happen for yourtheme.

• style.css - This is the default stylesheet. You can update the name of the theme, and the author, in this file.

2.3 What’s Included

2.3.1 Latest WP Core

When you clone from our Github repository, the code will always include the latest stable version of WordPress.

2.3.2 Gravity Forms Plugin

We always recommend Gravity Forms as the best plugin to use for form submission management and so we include itwithin the repository. There are no hard dependencies on Gravity Forms so if you wanted to remove this or replace itwith a different contact form plugin, that would be fine.

2.3.3 Advanced Custom Fields Pro

We bundle ACF5 directly into the theme itself because it relies on the ACF5 Options Panel functionality and we alsouse Advanced Custom Fields heavily during WP development. For the time being, the theme does not work wellwithout ACF5, but on a future release, we may have a version of the theme that does not use ACF5.

8 Chapter 2. The Basics


2.3.4 Laravel Blade Templating Engine

The Blade templating engine, developed for Laravel, has also been included in this theme.

Blade makes the front end templates much cleaner and organized, and you can read more documentation about bladehere: https://laravel.com/docs/5.2/blade.

2.4 Theme Config File

If you are already a WordPress developer, the power of the Vanilla theme comes with the theme-config.php file whereyou can quickly define and utilize all of the various WordPress components, all in one place.

I recommend opening up the theme-config.php and reading the comments of the file to see all of the various op-tions/settings there are available: theme-config.php

The following configuration options are currently available:

1. Global theme options

2. Custom post type options

3. Custom taxonomy options

4. Shortcode options

5. Custom sidebar options

6. Theme option panels

7. Theme menu options

8. Media library image options

2.5 Asset Pipeline

For all of your static assets (CSS files, images, custom @font-face fonts, JavaScript code, etc.), we like to use Gulp tomanage. All of these files will exist within the assets directory of the theme, and you can read more about Gulp here:Guide to Gulp.

The Vanilla theme is all driven by the gulpfile.js which is included in the theme. The output of the gulpfile is a theme.jsfile and a theme.css file - these are the two files that also outputted automatically into the <head> and footer of eachpage using the Vanilla boilerplate.

2.4. Theme Config File 9

https://laravel.com/docs/5.2/blade

https://github.com/codemyviews/vanilla-wp-boilerplate/blob/master/public/wp-content/themes/base-theme/theme-config.php


10 Chapter 2. The Basics

CHAPTER 3

Theme Components

In this section, you will learn about the key components that make up the Vanilla WordPress theme. It is critical thatyou understand each of these terms as it will help you correctly model your static front end site into a completelydynamic WordPress theme.

3.1 Templates

The Vanilla theme uses the Laravel Blade template engine to power the theme files. For more details on Blade, youcan read the documentation here: https://laravel.com/docs/5.1/blade

Blade makes it much easier and faster to template out your static front end into the Vanilla WordPress theme byproviding a much cleaner and fluid syntax.

Templates are broken out into three different sections:

1. Layouts

2. Views

3. Partials

3.1.1 Layouts

Take a look at your HTML files from your front end. Chances are that many of them share common elements. Forexample, it is likely that each of your pages uses the same header and same footer. We will use layouts to allow forthe various pages on your site that share a similar layout. The layout files will go in the layouts directory in the theme.In most cases, your theme will only require one layout, but there is no reason why your theme could not have multiplelayouts. For reference, here is the default layout that we use in the theme:

<!DOCTYPE html><html lang="en"><head>

<meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><title>{{ wp_title('') }}</title>

@yield('head')

{{ wp_head() }}

11

https://laravel.com/docs/5.1/blade




</head><body>

@yield('content')

{{ wp_footer() }}</body></html>

3.1.2 Views

If you are unfamiliar with the MVC (Model View Controller) pattern, then you likely have not heard the word Viewbefore. Views are an easy concept to grasp. Views represent what the user of your site actually see. For example, yourtheme will likely have a home page, an about page, a contact page, etc. Each of these pages will use a unique template,and each of these unique templates is what we call a “View”. For each of your static HTML files that you have in yourfront end, we will turn them into a reusable “view” that will be placed into the views directory in the Vanilla theme.Our goal is to convert each of the static HTML files you have into a completely dynamic view, that can then be re-usedthroughout the theme.

It is important to think of every single unique page on your site. For example, if you also have a custom 404 page,this is another view that will exist in your theme, and thus, we will create another View file for it in the theme. Otherexamples of common Views in your theme:

1. Blog index page (a feed of blog posts)

2. Blog single page (a single blog post)

3. Blog category page (a feed of blog posts from a specific category)

4. Search results page

5. Product page

The most important concept to remember is that we are creating these views so that they are reusable and completelydynamic. For example, if you have a Product view, it may be re-used to show several different products on the site.

3.1.3 Partials

In the name of DRY (Don’t Repeat Yourself), we place any front end code that is used across more than 1 view into aspecific partial. For example, if both your “Home Page” view and your “Product” view has a newsletter HTML on it,we can copy the code for the newsletter, place it into a partial, and then load the partial in both of the views using:

@include('partials/name-of-partial')

Any time you find two views using the same block of HTML, you should partial it out into a file in the partialsdirectory. Never have the same code in two different places.

12 Chapter 3. Theme Components


3.2 Posts

Posts are enabled by default in every WordPress theme. Posts are meant to store a feed of blog posts within the CMS.In order to use posts within this theme, you will need a front end HTML view to display the posts.

Posts, by default, also have categories enabled which allow you to group certain posts together.

Posts, by default, also have tags enabled. Tags are similar to categories. The only difference are that tags are nothierarchical so a tag cannot be a child of another tag, whereas categories can have parent and children categories.

3.3 Pages

Pages are also enabled by default in every WordPress theme. From an architecture standpoint, Pages and Posts arealmost identical to each other within the WordPress framework. The only differences between pages and posts isthat (1) pages are hierarchical, so a page can have a parent page and many children pages and (2) pages do not havecategory or tags associated with them (although you certainly can enable this behavior if you wanted to).

A unique feature to pages is that you can also create Custom Page Templates, and then assign the custom pagetemplates to specific pages on your site. For example, you may have an About Us page, and you have a custom aboutpage you want to use. You can simply create a new file in the “views” directory called “about.blade.php”, and use thebelow as a template:

@layout('layouts/master')<?php /* Template Name: About Page Template */ ?>

@section('content')<?php while ( have_posts() ) : the_post(); ?>

<?php endwhile ?>@endsection

3.4 Custom Post Types

Post Types refer to the data of your WP theme. Both “Posts” and “Pages” that we just covered, are “post types” withinWordPress that are enabled by default.

WordPress gives you the ability to create more post types if your theme requires it.

In many cases, your theme will not require you to create any additional post types, and the post and page post typeswill fulfill all the needs of your theme.

However, let’s assume that the site you are building has other data types. For example, maybe your site has clienttestimonials that are displayed in various parts of the site. Or, if you are building a portfolio on your site, you will havemany different portfolio items. Finally, if you are selling something on your site, you may have a list of products. Ineach of those cases, you will need to create a Custom Post Type (CPT) so that you will be able to easily store this datain your theme.

Within the theme-config.php, it is easy to add an additional post type within the load_custom_post_types() method.

3.5 Taxonomies

Taxonomies can be used to sort and filter your post types. By default, WordPress includes the following taxonomies:

3.2. Posts 13


1. Categories - categories, by default, only exist on the “Posts” post type. Categories allow you to group manyposts together.

2. Tags - tags, by default, also only exists on the “Posts” post type. Tags also allow you to group many poststogether.

The main difference between categories and tags is that categories are hierarchical and tags are not. This means thatcategories can have parent and children categories, whereas tags cannot.

In the Post Types section, we explained how you can create “Custom Post Types”. We can also create “CustomTaxonomies” and assign them to the Post Types in the theme which us allows us to filter the posts. For example, if wehave a Products CPT, we may want to be able to filter these Products by their color. We can create a Custom Taxonomycalled “Color” and then assign it to the Products CPT. This would allow us to then add Colors, and assign them to theproducts.

Within the theme-config.php, you can create custom taxonomies and assign them to post types within theload_custom_taxonomies() method.

3.6 Menus

Your theme likely has a navigation menu (or two menus, or many). For example, you may have a menu in the header,and also a menu in the footer. Menus in WordPress allow you to dynamically control which pages are outputted intothe menus.

Within the theme-config.php, you can create and define menus within the set_menus() method.

3.7 Options panels

Within the Vanilla theme, you can create custom Options Panels that will then appear in wp-admin. You can assignACF field groups to these option panels. The purpose of the Options Panels is to give the theme some Global con-figuration options. For example, perhaps you want the user to be able to update the logo on the site. You can createan Options panel called “Header Options”, and then create a field group on this Options panel called “Header Logo”.The user will then be able to update the logo dynamically in wp-admin.

Within the theme-config.php, you can create custom options panels within the load_options_panel() method.

3.8 Custom Fields

Every custom page template, post type, options panel, custom taxonomy may have additional data associated with it.For example, on your product posts, you will want to be able to store the color of your product, pricing information,and customer reviews. Or, on your about us custom page template, you may want to store a group of client testimonials.

For each area on the site where we have custom data to be stored, we will create an Advanced Custom Fields fieldgroup, and then create fields that will allow the user to easily update the content on that specific page, post, optionspanel, or taxonomy.

3.9 Media Library

The Media Library is a powerful tool included by default within the WordPress core. Whenever you upload an imageto WordPress through wp-admin, it is using the WordPress media library, and a copy of the image is stored in theMedia Library in the theme.



One of the great features of the Media Library is that it can also automatically crop each image that is uploaded to aspecific group of sizes.

Your theme likely has many images that exist in various parts of the site. For example, if you have products on yoursite, each product might have an image. You will create a ACF field group that allows the user to upload and changethe image that is associated with the product. In an ideal world, the user would upload the perfect sized image of theproduct so that it displays properly on the site. But often times, a user will upload an image that is too big, or not theright size. By defining Image Sizes in your theme, WordPress will automatically crop the image so that it is the perfectsize.

Within the Vanilla theme, you can define these image sizes in the theme-config.php - just look in the set_image_sizes()method.

3.10 WYSIWYG Editor

The “What You See Is What You Get” (WYSIWYG) editor is built into WordPress by default. This allows the user toupdate the content section on the page or post.

An important rule of thumb here is to never place blocks of HTML directly into the WYSIWYG editor. For example,on the home page, your HTML for the testimonial section may look like this:

<div class="testimonial-item"><h3>Testimonial</h3><blockquote>

<p>Here is my testimonial</p><cite>- James Jiggins, CEO CMV</cite>

</blockquote></div>

Often times, you will be tempted to simply copy and paste this HTML block directly into the WYSIWYG on yourhome page in wp-admin. This is something we never recommend, and instead, you should create a ACF field groupthat allows the user to fill out the content for the Testimonial, and then you should dynamically generate the HTML inthe View.

So what is the WYSIWYG editor used for? On many views, we entirely disable the WYSIWYG editor, and insteadonly have ACF field groups on the page. However, on pages where there are long blocks of long-form content (forexample, a blog post) the user will be able to edit the content there, and add h1 –> h6 tags and other basic contentstyles to the post.

3.11 Sidebars

To define a new custom sidebar widget area, please see the load_sidebars() method in the theme-config.php file.

3.12 Shortcodes

In the case where you want users to be able to add more dynamic content to a WYSIWYG, we use Shortcodes.Shortcodes allow the user to automatically generate HTML into a WYSIWYG box. For example, we have a testimonialshortcode that looks like this:

[testimonial text="Here is my testimonial" by="James Jiggins, CEO CMV"]

3.10. WYSIWYG Editor 15


We would then have a file in the shortcodes directory in the theme, and when the user places the shortcode into theWYSWIYG box, when the user views the page on the front end, the template for the shortcode would be outputted.

To define a new shortcode, please see the load_shortcodes() method in the theme-config.php file.

3.13 Endpoints

If your theme needs any advanced functionality on the front end, other than simply outputting content from the CMS,than you can create an endpoint. For example, if you have a contact form on your contact us page template, you willneed to setup a contact form endpoint that your form on the front end can POST to.

Please see the contact-form.php file in the endpoints directory for a sample endpoint.

In addition, please see the contact-form.blade.php in the forms directory for a sample form that submits to the createdendpoint.

The main idea behind endpoints is that for all forms within the theme, we make POST requests to the admin-ajax.phpfile within WordPress core. Within our POST request, we can include any custom POST data that we want, aslong as we also pass in an additional parameter called “action”. The “action” POST value should be equal to the“action” param that is setup in your endpoint file in the endpoints directory (the $action_param value at the top ofendpoints/contact-form.php).

3.14 The Loop

The loop is an important concept to grasp that exists within all WordPress installations.

Default WordPress loop code looks like this:

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

<! -- post data here --><?php endwhile; ?>

<?php else: ?>



<?php endif; ?>

The WordPress loop will try to determine which post data it should output based off of what page you are currentlyviewing on the site.

For example, if you are currently on a “http://sitename.dev/about”, and you have a page created on the site called“About”, the WordPress loop will simply contain all of the data it knows about the single “page” called About.

However, if you are viewing “http://sitename.dev/blog”, and you have a page created called “Blog”, and that page isdefined as your “blog feed” page in wp-admin options, then the WordPress loop will instead loop through all of yourblog posts .

The WordPress loop is a bit confusing, and is better to just play around with it in your local dev environment to getfamiliar with it.

This document also will be quite helpful once you get more into advanced WordPress development:https://developer.wordpress.org/files/2014/10/template-hierarchy.png


http://sitename.dev/about

http://sitename.dev/blog

https://developer.wordpress.org/files/2014/10/template-hierarchy.png


3.15 WP_Query

If you wanted to completely ignore the WordPress loop, and not include it anywhere in your theme, you could easilydo that, and instead simply use WP_Query.

WP_Query is a powerful class that will give you access to all of the data that is stored in your theme. Any dataassociated with any posts, pages, or custom post types you created can easily be queried, paginated, and returnedusing the WP_Query class.

As a code sample, let’s assume we wanted to return the past 15 testimonial posts from our site.

Let’s also assume that on our site, we sort our testimonials by “Year Received”, and thus, we have a custom taxonomyfor the testimonials called “testimonial year”.

In my query, I only want to return the testimonial posts that are from 2015. Here is the code:

<?php$options = array(

'post_type' => 'testimonial','orderby' => 'date','posts_per_page' => 15,'tax_query' => array(

array('taxonomy' => 'testimonial-year','field' => 'name','terms' => array('2015')

))

);

$testimonials = new WP_Query( $options );while( $testimonials->have_posts() ) : $testimonials->the_post();

?>

<!-- include the partial that have the HTML/CSS for the testimonial.

@include('partials/testimonial')

<?phpendwhile;wp_reset_postdata();

?>

3.15. WP_Query 17

https://codex.wordpress.org/Class_Reference/WP_Query



CHAPTER 4

Helper Functions

4.1 Helper::image

The Helper::image() function helps you output an image that is stored as a custom field. When we store an imageinto a custom field, we will always store the attachment_id associated with the image. By passing that ID to theHelper::image, in addition to your expected image size, you can automatically generate the <img> tag.

For example, this:

{{ Helper::image(get_field('profile_image'), 'attorney', array('class' => 'pull-left')) }}

Would generate this:

<img src="http://path-to-image/size/profile-image.jpg" alt="Image Alt Text" title="Image Title Text" class="pull-left" />

4.2 asset()

The asset helper function allows you to easily return an absolute URL to a file in the assets directory of the theme. Forexample, if you want to get the URL to a image in the assets/images directory, you can use the function like so:

<img src="{{ asset('images/image-name.png') }}" />

19


20 Chapter 4. Helper Functions

CHAPTER 5

How To Build a WP Theme

This guide will walk you through the steps of converting your static HTML/CSS files into a custom WordPress themeusing the Vanilla WordPress Boilerplate by Code My Views.

This guide assumes you have already followed the setup guide from the documentation link above.

5.1 Step 1: Views, Partials and Layouts

The first step in any WP theme build is identifying each of the unique HTML views that your theme will have. Foreach unique HTML page that you have, you should create a view.

Views

To create a view, create a new file in the views directory in your theme. For example, if your theme has a unique homepage template, you can create a file called home.blade.php and place it in the views directory.

Here is what a sample view looks like:

https://github.com/codemyviews/vanilla-wp-boilerplate/blob/master/public/wp-content/themes/base-theme/views/page-sample-custom-page-template.blade.php

Layouts

Once you have turned each of the HTML files into a view, you should next look at which HTML pages use the samelayout. If all of your views have the same exact header and footer, you likely can extract all of this into one layout.

Please see the same master.blade.php layout here: https://github.com/codemyviews/vanilla-wp-boilerplate/blob/master/public/wp-content/themes/base-theme/layouts/master.blade.php

Partials

In cases where your views use similar elements, you can extract these into partials.

Create partials by adding a new file to the partials directory. Partials can be loaded into any view by using:

@include('partials/name-of-partial')

5.2 Step 2: Assets

At this point, you should have successfully moved over all of your static HTML/CSS into the theme, and then partialedit out into views, partials and layouts.

21



https://github.com/codemyviews/vanilla-wp-boilerplate/blob/master/public/wp-content/themes/base-theme/layouts/master.blade.php

https://github.com/codemyviews/vanilla-wp-boilerplate/blob/master/public/wp-content/themes/base-theme/layouts/master.blade.php


The next step is to copy over all static assets (JavaScript, CSS, images, font files, etc.). All of the static assets canbe copied over to the assets directory in your theme. All of the CSS should be compiled down into one file calledtheme.css. All of the JavaScript should be compiled down into one files called theme.js. For more info on how to useGulp to make this happen, read this: Guide to Gulp.

5.3 Step 3: Data Model

At this point, you should have completely moved over all of the static views and static assets for your site.

The next step is to map out how you will make the content on each view dynamic, and controlled through the Word-Press admin panel.

In many cases, the default WordPress data model which contains posts and pages, will work just fine. If your themeonly needs posts and pages, then you can simply turn each of the views you created into a “Custom Page Template” inWordPress, and then assign them to any page you create in WordPress.

In the case where your theme has more data than just posts and pages, for example, if you want a feed of products,you need to create custom post types.

In the theme-config.php file, you can register post types in the load_custom_post_types() method.

In the theme-config.php file, you can also register custom taxonomies.

5.4 Step 4: View Mapping

At this point, we should have all views created, and also the entire structure of the data created.

WordPress, by default, depending on which page a user is viewing will load a different file in the theme automat-ically. You can see the WordPress template hiearchy here: https://developer.wordpress.org/files/2014/10/template-hierarchy.png

View mapping involves making sure that the views we created get served on the correct page. For example, when auser is visiting a product detail page, or a single blog post, we want to make sure they see the product detail view, orthe single blog post view.

Product Detail View Example

View file: views/product.blade.php WordPress template hierarchy loads: single-product.php

Create single-product.php and contents of this file should be:

@include('views/product')

Single Blog Post Example

View file: views/blog-post.blade.php

WordPress template hierarchy loads: single.php

Create single.php and contents of this file should be:

@include('views/blog-post’)

Custom Page Template - Contact

View file: views/contact.blade.php WordPress template hierarchy loads: $custom.php

Just be sure to place this at the top of the views/contact.blade.php and WordPress will automatically register your viewas a custom page template.

22 Chapter 5. How To Build a WP Theme




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

5.5 Step 5: Dummy Content and Menus

At this point, you should have all of your views registered and being mapped to the correct WordPress template file.

The next best step is to login to the wp-admin on your local dev environment and create all of the pages, posts, andcustom post types (i.e. sample products) that you will need. This will also allow you to test to make sure that all ofthe views are loading correctly.

Things to check:

1. Do all of your custom page templates show up as options when creating a new page?

2. When you view your blog post, does it load your blog post view?

3. If you have any custom post types, do their single post pages load the correct view?

Since you are already in wp-admin, it is a good time to also create any of the site menus that are needed on the theme.You can define the menus in set_menus() in the theme-config.php, and then you should also update the HTML codein the views so that it uses wp_nav_menu() to load the menu.

5.6 Step 6: Options Panels

If this theme has any global options, we can now create the options panels that are needed.

By default, all of the themes have a “Header and Footer” Options panel enabled. If you needed to add additionaloptions panels, you can do so in the load_options_panel() method in theme-config.php

5.7 Step 7: Custom Field Definitions, Sidebars and Shortcodes

At this point, you should actually be able to click around your entire site and see all of the views loading, and navigationmenus working. However, all of the views still are serving static content.

The next step is to determine how to make each of the views dynamic so that all of the content is being loaded fromthe database, via Custom Fields that are created in the theme.

For each of the views, you need to determine the most efficient and user friendly way to output the content from theCMS to the page.

5.8 Step 8: Make the views dynamic

Now that you have all of the custom fields created, you need to update the views so they are being served from thecustom fields.

5.9 Step 9: Endpoints and Advanced Functionality

Create endpoints in the endpoints directory for any advanced functionality.

Examples of advanced functionality:

5.5. Step 5: Dummy Content and Menus 23


1. Contact form

2. Advanced search queries

3. Mailing list subscription

4. Payment forms

5.10 Step 10: Testing, and production ready

Checklist:

1. Make sure to export all ACF fields into the field-groups directory (wp acf export)

2. Export a copy of your local database and place in project root (wp db export)

3. Commit code to project repo

24 Chapter 5. How To Build a WP Theme

CHAPTER 6

Appendix A: Windows Local Dev Environment Guide

6.1 Step 1: Download all of the packages here:

https://github.com/codemyviews/windows-dev-environment-packages

You should install the applications in the following order:

1. Wamp Server - a standard installation is ok;

2. Libraries required by WAMP #. Vcredist_arm.exe #. Vcredist_x86.exe

3. Git - should be straight forward. This will also install git bash, which is a better terminal client to use;

4. Composer - see instructions here

5. Sublime Text - is not required if you use a different IDE

6.2 Step 2: Restart Machine

Once you have WAMP completely installed, you should restart your computer.

6.3 Step 3: Start Wamp Server

You will need to start the WAMP Server. If you do not create a desktop shortcut for WAMP Server during installation,then you can go into your start menu and search for “START WAMP SERVER”

6.4 Step 4: Install Apache Service

Once you start WAMP, you should see the WAMP icon in the bottom right tray. Right click on this icon, and then goto Apache, and click “Install Apache Service”

6.5 Step 5: Install Apache Modules

Within the Apache menu, click on “Apache Modules” and make sure the following modules are enabled:

• ssl_module

25

https://github.com/codemyviews/windows-dev-environment-packages

http://codezag.com/how-to-install-composer-wamp/


• Rewrite_module

6.6 Step 6: Enabled PHP Extensions

Within the PHP menu in WAMP< click on “PHP Extensions” and make sure the following php extensions are enabled:

• php_openssl

• Php_curl

• Php_sockets

6.7 Step 7: Edit Apache Config File

Open this file in a text editor: C:wampbinApache#.#.#confhttpd.conf

Find this line: LoadModule vhost_alias_module modules/mod_vhost_alias.so and make sure it is uncommented.

Find this line: Include conf/extra/httpd-vhosts.conf And make sure it is uncommented

6.8 Step 8: Restart WAMP Services

Click the restart wamp services button in WAMP

6.9 Step 9: Put WAMP Online

Click the “Put WAMP Online” button in WAMP

6.10 Step 10: Is it working?

For good measure, you should restart

You should be able to visit: http://localhost in your browser now.

If you see the WAMP page when you visit http://localhost, then WAMP has been installed.

Note: Database management is straightforward with phpmyadmin. Visit http://localhost/phpmyadmin

The default password for mysql is:

username: rootpassword:

The password is empty.

If you are taking over an existing project, there should be a backup of the latest database included in the project root.You should import this via phpmyadmin to get all of the content and data loaded into your local dev environment.

26 Chapter 6. Appendix A: Windows Local Dev Environment Guide

http://localhost

http://localhost

http://localhost/phpmyadmin


6.10.1 Step 11: Installing a new site

This is a quick guide on how to install a new site on your local WAMP development environment.

This guide assumes that you install all of your code projects into a Code directory into the c:/wamp/www/ directory.

For example, if you have a project called “sample-project”, you would have the code installed into:c:/wamp/www/sample-project

The goal is to setup your local dev environment so that you can visit a url in your browser, for example: http://sample-project.dev, and have the local code display.

6.11 Step 12: Edit your host file

Open up this file in your text editor (eg Sublime Text): c:WINDOWSsystem32driversetchosts

At the bottom of the hosts file, add the following line:

127.0.0.1 sample-project.dev

Note: You will need to right click on Sublime Text and click “Run as Administrator”. If you do not do this, you willnot be able to save the hosts file. This file requires admin privileges to save.

6.12 Step 13: Add the vhost configuration

Open up this file in your text editor: C:wampbinApache#.#.#confextrahttpd-vhosts.conf

At the bottom of this file, add the following:

<VirtualHost *:80>ServerAdmin [email protected] "c:/wamp/www/sample-project/public"ServerName sample-project.devErrorLog "logs/sample-project.dev-error.log"CustomLog "logs/sample-project.dev-access.log" common<Directory "/">

Deny from all Allow from 127.0.0.1</Directory>

</VirtualHost>

Note: You should update the DocumentRoot to whatever the root is of the project you are installing. Most of theprojects at Code My Views will have a public directory in them which is one level up from the project root.

The ServerName must match the domain you added to your hosts file in the previous step.

Restart WAMP after you save this file.

6.13 Step 14: Does it work?

You should be able to visit http://sample-project.dev in your browser and see the project.

6.11. Step 12: Edit your host file 27





If you do not see the site loading, make sure you restarted WAMP.

Next steps can be found here - Installation

28 Chapter 6. Appendix A: Windows Local Dev Environment Guide

Documents

Vanilla Wordpress Template DocumentationVanilla Wordpress Template Documentation, Release 1.0 During this step, we also recommend renaming the theme folder to the name of your theme