Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
180 lines (118 sloc) 7.26 KB

Wordpress View-Controller Theme

This is an adaptation of the TwentySixteen Wordpress theme that uses the Timber Plugin to help aid the creation of Wordpress themes using a View-Controller pattern.

The aim of this project is to improve the editing, reuse and migration of Wordpress themes by:

  • Increasing the readability of template files
  • Rationalising the structure of the theme
  • Separating PHP functionality from the template HTML
  • Providing the possibility of activating useful, non-standard functionality "out of the box"
  • Turning the theme directory into a "package" that can be easily moved while still communicating important information about its intended usage

The theme also includes additional functionality that supports the stated aims.

Lazy Coder Note: This project is explicitly for the purpose of improving the way I create and maintain Wordpress themes for clients. In situations where it seemed more efficient or straightforward to NOT use Timber or the View-Controller pattern, I simply didn't bother.

Getting Started

Clone this repository into your Wordpress themes directory.

Update package.json with your own details.

Run npm install to install the Node modules.

Go through gruntfile.js to make sure the various settings correspond to your project (e.g. the development URL and src paths).

Update the theme information in style.scss.

Run grunt sass to apply your changes to style.css.

Log in to your Wordpress site and activate the theme.

Get creating your own theme!

Project Information


This theme uses Timber to power the Twig template engine.

The entry point for all templates is index.php. index.php uses Wordpress conditionals to load the relevant view-controller files as "template parts". For example:


if ( is_single() ) {

  get_template_part('controllers/controller', 'single');

} else if ( is_page() ) {

  get_template_part('controllers/controller', 'page');

} else {

  get_template_part('controllers/controller', 'index');


View-controllers follow the naming convention controllers/controller-index.php.

The view-controller generates variables, runs logic and renders the view, passing the data ($context) into the template. For example:


$context = Timber::get_context();

if ( is_home() && !is_front_page() ) {
	$context['single_post_title'] = single_post_title('', false);

if ( is_archive() ) {
	$context['archive_title'] = get_the_archive_title( '<h1 class="page-title">', '</h1>' );
	$context['archive_description'] = get_the_archive_description( '<div class="taxonomy-description">', '</div>' );

if ( have_posts() ) {
	$context['posts'] = Timber::get_posts();
	$context['pagination'] = Timber::get_pagination();
	$context['has_posts'] = true;

Timber::render('index.twig', $context);

The view-controller renders the template stored in views/. Data is displayed using the Twig template syntax.


Depending on your background, you may find that Timber/Twig results in more concise and readable template code. For example:

Before (PHP template)

Before: index.php

After (Twig template)

After: index.twig

Advanced logic and functionality can be stored in the view-controller, further reducing the complexity of the template.


For the sake of order, common functionality has been removed from functions.php and split into separate files within a functions directory. This is purely to make specific code easier to find and edit in the future.

Included functions files:

  • ajax.php – contains ajax localization script and ajax actions
  • assets.php – for enqueuing scripts, styles and fonts
  • custom-fields.php – export [Advanced Custom Fields](advanced custom fields wordpress github) php here (Note: activated only in production)
  • dependencies.php – the code that manages the dependency notices
  • editor.php – add TinyMCE editor additions here
  • post-types.php – add custom post types here
  • shortcodes.php – define custom shortcodes
  • supports.php – this is for common Wordpress functionality such as thumbnails, custom image sizes, menu support and widgets

Miscellaneous or global template functions are included in the main functions.php file.

Plugin Dependencies

This theme uses a variation of the code created by Paulund to display required/recommended plugins to administrators, along with a direct link to install them.

Dependencies are listed in plugins.json, which may look something like this:

  "require": {
    "advanced-custom-fields": ["advanced-custom-fields/acf.php", "*"],
    "contact-form-7": ["contact-form-7/wp-contact-form-7.php", "*"],
    "timber-library": ["timber-library/timber.php", "*"]
  "suggest": {
    "wp-db-backup": ["wp-db-backup/wp-db-backup.php", "*"],
    "google-analyticator": ["google-analyticator/google-analyticator.php", "*"],
    "lazy-load": ["lazy-load/lazy-load.php", "*"],
    "amazon-web-services": ["amazon-web-services/amazon-web-services.php", "*"],
    "amazon-s3-and-cloudfront": ["amazon-s3-and-cloudfront/wordpress-s3.php", "*"]
  "vendor": {

This appears in the admin area like this:



The theme includes a gruntfile.js setup with common tasks that may prove useful to Wordpress theme developers. A few quick notes:

SASS: The theme uses .scss files stored in assets/css. These are merged, minified and output to the main style.css file.

Uglify: Uglify minifies all files contained in the assets/js/myscripts directory and outputs it into assets/js/build.min.js. This is the main theme script enqueued at load.

Compress: Zips the theme directory for distribution. Be sure to update the src files list to include (and exclude) all the files you need.

Version: Change semantic versioning through the command line. This has been set up to also update the version number in the main stylesheet.

FTP Push: Requires a .ftpauth file with server credentials. Intended to 'release' the compressed theme file, along with release notes and theme update information json file. Visit the documentation for more information on usage

Further Resources