WDG Starter WordPress Theme

This is a very opinionated base theme for WordPress, build from several iterations of our projects' themes on production.

Features

• Straightforward directory structure
• PHP classes and helper functions for your WordPress theme
  • Constants for URIs and server paths
  • Custom post types & Taxonomies default options and auto generated labels
    • Breadcrumbs
  • Attachments
    • Get Average colors from images
    • Get paths and urls with attachment ids
    • SVG parsing and rendering with a rasterized image fallback
  • Menus: Additional CSS classes and sensitive defaults
  • Shortcodes:
    • Classes to ease the development of shortcodes with a UI integrated with Shortcake
  • String functions with Doctrine's inflector
    • Autoloading of classes & Composer packages
    • Vendor packages using Composer & Packagist
    • Enforced linting and WordPress coding standards with PHP_CodeSniffer
• Assets structure and build tools
  • CSS goodies like:
    • SASS (SCSS syntax): CSS pre-processor
    • Autoprefixer: Automatically prefixed vendor properties
    • Bourbon & Neat: SASS & Grid library
    • stylelint & CSScomb: Linting and coding standards
  • JavaScript goodies like:
    • ES2015 syntax with Bublé
    • ES2015 modules with Rollup
    • ESLint: Linting and coding standards
  • Vendor modules
    • Copied automatically from node_modules to assets/vendor
    • Custom Modernizr generated from your SCSS & JS files
  • Browsersync support
  • Gulp tasks to build/compile and watch for asset changes

Getting Started

1. Install Node.js & WordPress on your development server
2. Download the theme from our GitHub repo into your themes directory /wp-content/themes/
3. Install the theme's dependencies

$ npm install

4. Run the build task

$ npm run build

Or watch for changes

$ npm run watch

5. Enable the WordPress theme and start coding!

Directory structure

All static assets, like stylesheets, JavaScript files, images, icons and fonts should go in the /assets directory. All 3rd party frameworks and plugins should go in the /assets/vendor directory.

Feel free to use Npm for installing and updating them with the --save flag so our gulp build:vendor task can copy the files to the assets/vendor directory.

SASS is strictly required in development, use Gulp to compile the CSS files. Use components, mixins and variables folders to keep organized and build modular & reusable files.

All PHP scripts that aren't templates should go in /includes. Eg. /includes/class-theme.php. Refer to the WordPress Coding Standards for naming convention.

Translation files should live in the /languages directory.

node_modules is where all Node.js packaged modules will be stored to be used in the Build process with Gulp. This directory is excluded from the Git repo by default. Keep it this way.

partials is where all the template parts used by WordPress live.

templates is where all user-selectable page templates live. Eg. an "About us" page /* Template Name: About Us */ templates/about-us.php. Please do not clutter the root directory with WordPress templates.

tests include unit testing for our main PHP and JavaScript functionality. We encourage you to write all sort of tests for your theme here, feel free to use your favorite testing framework.

wdg-wordpress-theme
├─┬ assets
│ ├── dist
│ ├── fonts
│ ├── img
│ ├── js
│ ├── sass
│ └── vendor
├── includes
│ ├── api
│ ├── cli
│ ├── fields
│ ├── shortcodes
│ ├── vendor
│ └── widgets
├── languages
├── node_modules
├── partials
├── templates
└── tests

Vendor assets

3rd party vendor files live in /assets/vendor, they can be either stylesheets, JavaScript, images or any kind of helper, snippet, library or framework that isn't theme related.

Use WordPress register_style and register_script to add them to your theme.

ES2015 modules

To use the JavaScript vendor assets within ES6 modules you can whitelist them as globals in the gulpfile.js.

Inside the rollup task, add your 3rd party dependencies as follows:

globals: {
    bows: 'bows',
    jquery: 'jQuery',
    modernizr: 'Modernizr'
},

Then include them in your theme's JavaScript files, note that we use the previously provided key jquery and not the actual global variable jQuery. Then we alias such variable as $ to be used inside our module.

import $ from 'jquery';

$('html').addClass('js');

Learn more about ES2015 modules.

Default vendor assets

As you can see in the code above, we provide the following vendor assets by default:

• bows
• jquery
• modernizr

Modernizr is custom built from the references within the JavaScript & CSS asset files.

Searching for a package

NPM packages repository

Composer packages

There is Composer support built-in. Packages live under /includes/vendor and are autoloaded into the theme.

Build process with Npm & Gulp

Installing

Use the command line to get to the root of the repo and run the following command to install node modules, including Gulp.

$ npm install

Build

$ npm run build

This is a set of tasks to be run in the following order:

1. Compile vendor files
2. In parallel compile CSS & JS files

build:vendor

$ npm run build:vendor

1. Generate a custom built Modernizr file based on usage from the project's CSS & JS.
2. Copy all dependencies from package.json to the assets/vendor directory.

build:css

$ npm run build:css

1. Grab all Sass files without an underscore in front of the file.
2. Compile SASS files.
3. Autoprefixer.
4. Create compiled and minified versions of all CSS files.

build:js

$ npm run build:js

1. Rollup to merge all ES6 modules imported from assets/js/site.js.
2. Transpile all ES6 code into ES5 with Bublé.
3. Create compiled and minified versions of all CSS files.

Watch

$ npm run watch

The watch task will look for changes in the /assets/js and /assets/sass files and build them accordingly.

Please note that the watch task will not generate vendor files by default or on any file change. This has changed from previous versions of the theme. Please run build:vendor yourself.

Browsersync support

There is Browsersync support. This is not enabled, nor installed by default.

$ npm install browser-sync

Then run the Browsersync server:

$ npm run watch:sync

A note on using CSS pre-processors

We encourage all developers to use CSS pre-processors and we specially like SASS, but use whatever you feel more comfortable with. Just make sure you follow our simple rules.

1. Create a directory on /assets where all your files will live. Eg. /assets/sass.
2. Pipe the build:css task to compile all files without an underscore in front of the file name.
3. Hook up on the watch task for Gulp.
4. Avoid using mixins for vendor prefixes, we are already running Autoprefixer.

Code Linting

CSS

1. Install stylelint globally with NPM

# npm install --global stylelint

2. Install linter packages on Atom

$ apm install linter
$ apm install linter-stylelint

3. Select the following on linter-stylelint

Disable when no config file is found

JavaScript

1. Install ESLint globally with NPM

# npm install --global eslint

2. Install linter packages on Atom

$ apm install linter
$ apm install linter-eslint

3. Select the following on linter-eslint

Disable when no ESLint config is found (in package.json or .eslintrc)

PHP

1. Install Composer
2. Install WordPress coding standards & PHP_CodeSniffer

$ composer global require wp-coding-standards/wpcs
$ composer global require squizlabs/php_codesniffer

3. Find the path to your phpcs command

$ which phpcs

It should return a hidden directory on your home directory similar to the following:

MacOS & Linux: ~/.composer/vendor/bin/phpcs

Windows: %HOME%\AppData\Roaming\Composer\bin\phpcs

4. Replace "bin/phpcs" with "wp-coding-standards/wpcs" and add it to your phpcs installation

$ phpcs --config-set installed_paths ~/.composer/vendor/wp-coding-standards/wpcs

5. Install the linter packages on Atom

$ apm install linter
$ apm install linter-php
$ apm install linter-phpcs

WordPress Plugins

We encourage you to use the following plugins for development:

Development

• Advanced Custom Fields (Pro) for fields
• Black Studio TinyMCE Widget for a standard WordPress TinyMCE widget
• Carbon Fields as an alternative to Advanced Custom Fields
• Download Monitor for managing and versioning protected assets
• Easy WP SMTP for configuring SMTP email delivery
• Enhanced Media Library for Media Library taxonomies and mime types
• Gravity Forms for form management
• Redirection for managing redirects
• Redis Object Cache for providing an interface to redis
• Shortcake (Shortcode UI) for a shortcode user interface
• W3 Total Cache for cache management
• Yoast SEO or The SEO Framework for search engine optimization

Administration

• Admin Columns for customizing the columns in WP_List_Table
• Admin Column View for a hierarchical view of pages
• Bulk Creator for initial content creation
• Duplicate Post for duplicating content
• Google Analytics by Monster Insights for Google Analytics installation and admin user exclusion
• Jarvis for fast lookups of the admin menus
• Revisionize for creating drafts of already published content

Debugging

• Query Monitor for a debugging environment
• Rewrite Rules Inspector for testing rewrite rules
• Log Viewer for log management

WordPress CLI

We encourage you to use WordPress CLI as much as possible in your workflow, it's an incredible tool which provides an enormous amount of power. Also look at all the community packages.

Contribution

Although we are very opinionated, we are open to suggestions. Please send as a message to our email [email protected], through our contact page, send us a GitHub issue or even better, a pull request!

Credits

• Brought to you by The Web Development Group team. @dougaxe1, @kshaner, @MikeNGarrett, @neojp
• Original directory structure was inspired by Bones.
• Grunt configuration originally inspired by YeoPress.
• If we forgot someone, please send us a pull request or a message through the issues.