The Mozaik WordPress Theme Boilerplate

This is a WordPress theme starter-kit meant to offer a first-class developer experience.

Full Feature List
Important Prerequisites
Development Guidelines
Standard Theme Development Process
Reading Recommendations
License
FAQ
- 1. How do I use jQuery with wp-theme-starter ?

Full Feature List

Important Prerequisites

Dev Environment

Have node and npm installed on your system (node@5.0.0)
Have gulp globally installed (gulp@^3.9.0)

You can use nvm to manage the node versions installed on your computer
You can use npm-check-updates to update the node modules in your theme (Note that updating may break things, so be careful)

Windows

On Windows you may need to do some of the following if you run into trouble when running npm install in this project:

Install Python - Install version 2.7 of Python and add it to your path or/and create a PYTHONPATH environment variable.
Install Visual Studio (Express Edition is fine) - We will need this for some of modules that are compiled when installing Theme Starter. Download VS Express, get one of the versions that has C++ - Express 2013 for Windows Desktop for example.
Set Visual Studio Version Flags - We need to tell node-gyp (something that is used for compiling addons) what version of Visual Studio we want to compile with. You can do this either through an environment variable GYP_MSVS_VERSION. If you are using Express, you have to say GYP_MSVS_VERSION=2013e.

Thanks to Ryanlanciaux

WordPress

Read the WordPress theme development guidelines
Understand the WordPress template hierarchy
Understand the WordPress Loop
Understand how WordPress helps with Data Validation/Sanitization
Read up on the following WordPress core APIs:
- the Plugin API
- the Shortcode API
Understand when you should use a Custom Functionality Plugin instead of implementing functionality within a theme
- Creating a custom functions plugin for end users
- How to Create a Custom Functionality Plugin (And Why You Need One)

JavaScript

This project uses webpack to provide support for modular JS, read up on the functionality & tools it provides

CSS

The boilerplate assumes you are using SCSS to write your styles and compiles to CSS using Libsass
Autoprefixer is used for adding the correct vendor prefixes to the final generated CSS

Development Guidelines

Avoid committing the built theme to the project repository
Avoid committing the wp-uploads directory to the project repository
Avoid making changes directly to the built theme -- Always use the build process
In production avoid uploading the theme development directory to a public server
It is good practice to enable WP_DEBUG in your wp-config.php file, but only during development

Standard Theme Development Process

Setup

Install WordPress and clear it of unnecessary default themes & plugins
Clone/Download the contents of this repository into a directory in your WordPress wp-content/themes directory (eg: "my-theme_dev") this will be your "dev theme"
Open the terminal and navigate to the dev theme, eg: cd wp-content/themes/<my-theme>_dev
(Note: The next steps require nodejs @5.0.0 and gulpjs @^3.9.0)
Run npm install to install all dev dependencies
Change the project.config.js file with your new theme's configuration
Run gulp build to generate the "built theme" for the first time
Log in to the admin and enable the built theme (Note: The dev theme is not a valid theme, that's fine! Don't delete it or try to enable it!)
Start Developing!

Development

Run gulp to begin the dev build process that uses libsass, browser-sync and webpack
Develop your theme in the /assets and /theme directories, the "built theme" will be generated by gulp
Optional stuff:
- use npm install --save <module(s)> or bower install --save <module(s)> to easily manage js dependencies, then use var <module> = require('<module>'); or import <module> from '<module>'; anywhere in your js files you want to use them
- explore the /library directory in the dev theme for anything useful to your project.

Production

Delete files you are not using from inside the /theme directory
Add a screenshot.png
Before deploying run gulp build to generate a production ready version of the built theme
Deploy the built theme directory, not the dev directory

Reading Recommendations

WordPress Developer Documentation
We generally follow the WordPress PHP Coding Standards in our WP code
The build process supports ES6+ JavaScript syntax by using babel.js to transpile ES6+ to ES5.

License

This Theme Boilerplate is licensed under the MIT license see license.txt.

FAQ

1. How do I use jQuery with wp-theme-starter ?

As mentioned above, wp-theme-starter uses webpack to handle concatenating, minifying and optimizing the javascript in the theme. Webpack, like Browserify and RequireJS, is a module loader for javascript and as such requires each module (file) to declare the dependencies it has within it. To use jQuery, or any other global library, in your webpack-ed js you have a couple of choices:

Use jQuery as an internal dependency of your bundle
(this means jQuery will be included in the final JS bundle created)
1. With the terminal open within the dev theme, type npm install jquery --save or bower install jquery --save to install jquery for the project
2. In the ./gulp/config/scripts.js file add this line to the top of the file to expose webpack within this file:
```
 var webpack = require('webpack');
```
3. Then within the file declare that any instance of $,jQuery or window.jQuery within the project refers to the jQuery package we downloaded earlier. We can achieve this by adding the following to the config object: (it is worth checking out the ./gulp/core/config/scripts.js file for the general structure of the config object)
```
 ...
 options: {
 	webpack: {
 		defaults: {
 			plugins: [
 				new webpack.ProvidePlugin({
 					'$': 'jquery',
 					'jQuery': 'jquery',
 					'window.jQuery': 'jquery'
 				})
 			]
 		}
 	}
 }
 ...
```
Use jQuery as an external package
(this means jQuery will be requested as a separate resource from the rest of your bundle. Use this when you are working with WordPress plugins that include jquery dependant scripts on the front-end)
1. Declare jQuery as an external dependency of your main.js in the theme_scripts function in your functions.php file. Something like this:
```
 wp_enqueue_script( 'main', "$theme_dir/assets/js/main.js", array( 'jquery' ), null, true );
```
2. In the ./gulp/config/scripts.js file add this line to the top of the file to expose webpack within this file:
```
 var webpack = require('webpack');
```
3. Declare jQuery as an external dependency in webpack. Add the following to ./gulp/config/scripts.js in the webpack section of the config:
```
 ...
 options: {
 	webpack: {
 		defaults: {
 			plugins: [
 				new webpack.ProvidePlugin({
 					'$': 'jquery'
 				})
 			],
 			externals: {
 				jquery: 'window.jQuery'
 			}
 		}
 	}
 }
 ...
```

krisalcordo/wp-theme-starter