Merge pull request #31 from synapticism/develop

Develop

Author: xsynaptic

gulpconfig.js

@@ -53,14 +53,14 @@ module.exports = {
   , chunks: { // Chunks are arrays of paths or globs matching a set of source files; this way you can organize a bunch of scripts that go together into pieces that can then be bundled (above)
       // The core chunk is loaded no matter what; put essential scripts that you want loaded by your theme in here
       core: [
-        modules+'timeago/jquery.timeago.js'
+        modules+'timeago/jquery.timeago.js' // The modules directory contains packages downloaded via npm
       , src+'js/responsive-menu.js'
       , src+'js/core.js'
       ]
       // The pageloader chunk provides an example of how you would add a user-configurable feature to your theme; you can delete this if you wish
       // Have a look at the `src/inc/assets.php` to see how script bundles could be conditionally loaded by a theme
     , pageloader: [
-        modules+'html5-history-api/history.js' // The modules directory contains packages downloaded via npm
+        modules+'html5-history-api/history.js'
       , modules+'spin.js/spin.js'
       , modules+'spin.js/jquery.spin.js'
       , modules+'wp-ajax-page-loader/wp-ajax-page-loader.js'
@@ -72,8 +72,7 @@ module.exports = {
       src: [src+'js/**/*.js'] // Linting checks the quality of the code; we only lint custom scripts, not those under the various modules, so we're relying on the original authors to ship quality code
     }
   , minify: {
-      src: [build+'js/**/*.js', '!'+build+'js/**/*.min.js'] // Avoid recursive min.min.min.js
-    , rename: { suffix: '.min' }
+      src: build+'js/**/*.js'
     , uglify: {} // Default options
     , dest: build+'js/'
     }

gulpfile.js/tasks/images.js

@@ -13,7 +13,7 @@ gulp.task('images', function() {
 });
 
 // Optimize images in the `dist` folder (slow)
-gulp.task('images-dist', ['utils-dist'], function() {
+gulp.task('images-optimize', ['utils-dist'], function() {
   return gulp.src(config.dist.src)
   .pipe(plugins.imagemin(config.dist.imagemin))
   .pipe(gulp.dest(config.dist.dest));

gulpfile.js/tasks/main.js

@@ -13,4 +13,4 @@ gulp.task('build', ['images', 'scripts', 'styles', 'theme']);
 
 // Dist task chain: wipe -> build -> clean -> copy -> compress images
 // NOTE: this is a resource-intensive task!
-gulp.task('dist', ['images-dist']);
+gulp.task('dist', ['images-optimize']);

gulpfile.js/tasks/scripts.js

@@ -9,7 +9,7 @@ var gulp        = require('gulp')
 // Check core scripts for errors
 gulp.task('scripts-lint', function() {
   return gulp.src(config.lint.src)
-  .pipe(plugins.jshint('.jshintrc'))
+  .pipe(plugins.jshint())
   .pipe(plugins.jshint.reporter('default')); // No need to pipe this anywhere
 });
 
@@ -47,8 +47,9 @@ gulp.task('scripts-bundle', ['scripts-lint'], function(){
 // Minify scripts in place
 gulp.task('scripts-minify', ['scripts-bundle'], function(){
   return gulp.src(config.minify.src)
-  .pipe(plugins.rename(config.minify.rename))
+  .pipe(plugins.sourcemaps.init())
   .pipe(plugins.uglify(config.minify.uglify))
+  .pipe(plugins.sourcemaps.write('./'))
   .pipe(gulp.dest(config.minify.dest));
 });
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress-gulp-starter-kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A starter kit for developing WordPress themes with Gulp",
   "homepage": "https://github.com/synapticism/wordpress-gulp-starter-kit",
   "repository": {
@@ -50,7 +50,7 @@
     "scut": "^1.4.0",
     "spin.js": "^2.3.2",
     "timeago": "^1.5.2",
-    "wp-ajax-page-loader": "^0.2.0"
+    "wp-ajax-page-loader": "^0.2.1"
   },
   "scripts": {
     "postinstall": "gulp setup"

readme.md

@@ -38,6 +38,7 @@ If you're already up and running with most of the usual Node ecosystem tools thi
 * Install all dependencies by running `npm install`. This will fetch all dependencies listed in `package.json` (which includes front-end JavaScript packages and back-end tools like Gulp plugins and [BrowserSync](http://www.browsersync.io/)).
 * [BrowserSync](http://www.browsersync.io/) setup: assuming you have a local development environment setup all you should need to do is enter the URL into the `proxy` setting in `gulpconfig.js`. Why use BrowserSync? It's fast, awesome, and allows for simultaneous responsive development across multiple devices.
 * [LiveReload](http://livereload.com/) setup: install a browser extension for [Chrome](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) or Firefox. Why use LiveReload? It does the job without complications or additional setup after the extension is installed.
+* This build process assumes you're up and running with [source maps for both JavaScript and Sass](http://blog.teamtreehouse.com/introduction-source-maps). You may need to configure your browser or debugging environment to make sense of the minified files generated by Gulp!
 * Run `gulp` and start hacking!
 
 
@@ -53,7 +54,7 @@ There are two components worth a closer look:
 * The script variable and enqueuing functions in `src/inc/assets.php`; these are tightly coupled with the output of the build process.
 * The theme configuration pattern described in `functions.php` and `functions-config-defaults.php`.
 
-Whether you use anything from this built-in theme is entirely up to you. If you prefer to start working with your own theme just drop it in. You may need to go into `gulpconfig.js` and modify paths and glob matching patterns but this is designed to be fairly easy and straight-forward with lots of comments to point you in the right direction.
+Whether you use anything from this built-in theme is entirely up to you. If you prefer to start working with your own theme just drop it in. You will probably need to modify paths and glob matching patterns in `gulpconfig.js` but it is designed to be fairly easy and straight-forward with lots of comments to point you in the right direction.
 
 
 
@@ -82,7 +83,7 @@ Configuration is handled by a single file: `gulpconfig.js`. If you leave the dir
 * [BrowserSync](http://www.browsersync.io/) settings: if you are developing on a local web server you will want to enter the URL into `browsersync.proxy` and then change `watch.watcher` to `browsersync` to take it for a test drive. You'll know it's working when you run `gulp` and a new browser opens with a live copy of your web site. Make changes to any of the Sass files and they should be shown on the page almost immediately. Of course, BrowserSync really shines when you connect a mobile device to your development server, but for that you're on your own ;)
 * Script settings: draw your attention to `scripts.bundles` and `scripts.chunks`. This feature is essentially a poor man's [Browserify](http://browserify.org/) or [Webpack](https://webpack.github.io/). By defining different "chunks" (script files that combine to provide a particular feature) and "bundles" (chunks that combine to provide feature sets) you can generate an assortment of files that can be efficiently and intelligently loaded through your WordPress theme. This approach has its limitations, of course, particularly when dependencies are shared between scripts, but it should be of use to many WordPress theme developers.
 
-Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site (install, require, and add to the `processor` variable in `./gulpfile.js/tasks/styles.js`).
+Interested in adding new Gulp plugins to your build system? A full tutorial is out of scope for this project but it really shouldn't be all that hard to figure out. In brief, install a plugin with `npm install [package] --save-dev`, require it in a suitable task file, add something to the configuration file if needed, and drop it into the pipeline somewhere. Some types of plugin are particularly easy to add, for instance anything listed on the [postcss.parts](http://postcss.parts/) web site (install, require, and add to the `processor` variable in `/gulpfile.js/tasks/styles.js`).
 
 
 
@@ -131,7 +132,9 @@ Like images, PHP (and language) files can go anywhere under `src` and will be co
 
 
 
-## EXAMPLE INTEGRATION
+## EXAMPLE INTEGRATIONS
+
+The bare bones theme included in this starter kit integrates two external JavaScript projects: [timeago](http://timeago.yarp.com/) (which facilitates human-readable timestamps) and [WP AJAX Page Loader](https://github.com/synapticism/wp-ajax-page-loader) (a lightweight and intelligent infinite scroll script). Have a look at the `/src/inc/assets.php` file and `gulpconfig.js` to see how this was accomplished. Timeago required only `npm install -d timeago`, an extra line in `gulpconfig.js`, and initialization in `/src/js/core.js`. Integrating the other script was much more involved; you'll have to browse the source and see for yourself.
 
 Let's say you run across a cool project like [Headroom.js](http://wicky.nillia.ms/headroom.js/) and decide you'd like to try it out. Here's how you would do that with the tools and workflow outlined in this repo:
 

src/header.php

@@ -17,8 +17,8 @@
           <h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></h1>
           <h2 class="site-description"><?php bloginfo( 'description' ); ?></h2>
         </div>
+        <button id="responsive-menu-toggle"><?php _e( 'Menu', 'voidx' ); ?></button>
         <nav id="site-navigation" class="site-navigation">
-          <button id="responsive-menu-toggle"><?php _e( 'Menu', 'voidx' ); ?></button>
           <div id="responsive-menu"><?php wp_nav_menu( array( 'theme_location' => 'header', 'menu_id' => 'menu-header', 'menu_class' => 'menu-inline' ) ); ?></div>
         </nav>
       </header>

src/inc/assets.php

@@ -1,60 +1,64 @@
 <?php // ==== ASSETS ==== //
 
 // Now that you have efficiently generated scripts and stylesheets for your theme, how should they be integrated?
-// This file walks you through the approach I use but you are free to approach this any way you like
+// This file walks you through the approach I use but you are free to do this any way you like
 
 // Enqueue front-end scripts and styles
 function voidx_enqueue_scripts() {
 
-  $script_name = '';                // Empty by default, may be populated by conditionals below
+  $script_name = '';                // Empty by default, may be populated by conditionals below; this is used to generate the script filename
   $script_vars = array();           // An empty array that can be filled with variables to send to front-end scripts
-  $script_handle = 'voidx';         // A generic script handle
-  $suffix = '.min';                 // The suffix for minified scripts
-  $ns = 'wp';                       // Namespace for scripts
-
-  // Load original scripts when debug mode is on; this allows for easier local development
-  if ( WP_DEBUG === true )
-    $suffix = '';
+  $script_handle = 'voidx';         // A generic script handle used internally by WordPress
+  $ns = 'wp';                       // Namespace for scripts; this should match what is specified in your `gulpconfig.js` (and it's safe to leave alone)
 
   // Figure out which script bundle to load based on various options set in `src/functions-config-defaults.php`
-  // Note: bundles require less HTTP requests at the expense of addition caching hits when different scripts are requested
-  // You could also load one main bundle on every page with supplementary scripts as needed (e.g. for commenting or a contact page)
+  // Note: bundles require fewer HTTP requests at the expense of addition caching hits when different scripts are requested on different pages of your site
+  // You could also load one main bundle on every page with supplementary scripts as needed (e.g. for commenting or a contact page); it's up to you!
+
+
+
+  // == EXAMPLE INTEGRATION == //
 
   // An example integration using WP AJAX Page Loader; this script requires a bit more setup as outlined in the documentation: https://github.com/synapticism/wp-ajax-page-loader
   $script_vars_page_loader = '';
 
   // This conditional establishes whether the page loader bundle is loaded or not; you can turn this off completely from the theme configuration file if you wish (or just remove the code)
   if ( VOIDX_SCRIPTS_PAGELOAD && ( is_archive() || is_home() || is_search() ) ) {
-    $script_name .= '-pageloader'; // This is used to generate the filename that the theme will serve to the user; it is additive to allow for multiple features that can be toggled in the theme configuration
 
-    global $wp_query;
+    // The script name is used to specify the file that the theme will serve to users
+    // Script names are designed to be additive (meaning you can append more script names to the end in other conditional blocks using `.= '-anotherscript'` etc.) to allow for multiple feature toggles in the theme configuration
+    $script_name .= '-pageloader';
 
-    // This chunk of code provisions the script with some important information it needs: What page are we on? And what is the page limit?
+    // This chunk of code provisions the WP AJAX Page Loader script with some important information it needs: What page are we on? And what is the page limit?
+    global $wp_query;
     $max = $wp_query->max_num_pages;
     $paged = ( get_query_var( 'paged' ) > 1 ) ? get_query_var( 'paged' ) : 1;
 
-    // Prepare script variables; note that these are separate from the rest of the script variables as this script requires everything in an object named `PG8Data`
+    // Prepare script variables; note that these are separate from the rest of the script variables as the WP AJAX Page Loader script requires everything in a specific object named `PG8Data`
     $script_vars_page_loader = array(
       'startPage'   => $paged,
       'maxPages'    => $max,
       'nextLink'    => next_posts( $max, false )
     );
   } // WP AJAX Page Loader configuration ends
 
-  // Default script name
+
+
+  // Default script name; used when conditional blocks (above) aren't triggered
   if ( empty( $script_name ) )
     $script_name = '-core';
 
   // Load theme-specific JavaScript bundles with versioning based on last modified time; http://www.ericmmartin.com/5-tips-for-using-jquery-with-wordpress/
   // The handle is the same for each bundle since we're only loading one script; if you load others be sure to provide a new handle
-  wp_enqueue_script( $script_handle, get_stylesheet_directory_uri() . '/js/' . $ns . $script_name . $suffix . '.js', array( 'jquery' ), filemtime( get_template_directory() . '/js/' . $ns . $script_name . $suffix . '.js' ), true );
+  wp_enqueue_script( $script_handle, get_stylesheet_directory_uri() . '/js/' . $ns . $script_name . '.js', array( 'jquery' ), filemtime( get_template_directory() . '/js/' . $ns . $script_name . '.js' ), true );
 
   // Pass variables to JavaScript at runtime; see: http://codex.wordpress.org/Function_Reference/wp_localize_script
   $script_vars = apply_filters( 'voidx_script_vars', $script_vars );
   if ( !empty( $script_vars ) )
     wp_localize_script( $script_handle, 'voidxVars', $script_vars );
 
-  // Script variables for WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object must be `PG8Data`)
+  // Script variables specific to WP AJAX Page Loader (these are separate from the main theme script variables due to the naming requirement; the object must be `PG8Data`)
+  // This appears and NOT in the conditional block (above) because these variables will be attached to the main script handle (which may be modified after the page loader block)
   if ( !empty( $script_vars_page_loader ) )
     wp_localize_script( $script_handle, 'PG8Data', $script_vars_page_loader );
 
@@ -70,7 +74,7 @@ function voidx_enqueue_scripts() {
 // Provision the front-end with the appropriate script variables
 function voidx_update_script_vars( $script_vars = array() ) {
 
-  // Non-destructively merge script variables if a particular condition is met (e.g. `is_archive()` or whatever)
+  // Non-destructively merge script variables if a particular condition is met (e.g. `is_archive()` or whatever); useful for managing many different kinds of script variables
   if ( 1 == 1 ) {
     $script_vars = array_merge( $script_vars, array(
       'ajaxUrl'       => admin_url( 'admin-ajax.php' ),

src/js/responsive-menu.js

@@ -1,4 +1,4 @@
-// ==== RESPONSIVE NAVIGATION MENU ==== //
+// ==== RESPONSIVE MENU ==== //
 
 // Menu toggle script adapted from _s: https://github.com/Automattic/_s
 ;(function() {
@@ -19,16 +19,12 @@
 
   // Toggle navigation; add or remove a class to both the button and the nav element itself
   button.onclick = function() {
-    if (button.className.indexOf( 'toggled' ) !== -1) {
-      button.className = button.className.replace(' toggled', '');
+    if (button.className.indexOf( 'active' ) !== -1) {
+      nav.style.display = 'none';
+      button.className = button.className.replace(' active', '');
     } else {
-      button.className += ' toggled';
-    }
-
-    if (menu.className.indexOf( 'toggled' ) !== -1) {
-      menu.className = menu.className.replace(' toggled', '');
-    } else {
-      menu.className += ' toggled';
+      nav.style.display = 'block';
+      button.className += ' active';
     }
   };
 } )();

src/scss/_config.scss

@@ -30,7 +30,7 @@ $_metadata: (
 , theme-author:             "Alexander Synaptic"
 , theme-author-uri:         "http://synapticism.com"
 , theme-description:        "A minimally viable theme made with the WordPress/Gulp starter kit"
-, theme-version:            "0.2.1"
+, theme-version:            "0.2.2"
 , theme-license:            "GPLv3"
 , theme-license-uri:        "http://www.gnu.org/licenses/gpl.txt"
 , theme-tags:               (light, responsive-layout, right-sidebar, starter-theme, two-columns, translation-ready, white)