Build process streamlining

* Removing “min” suffix and associated structure; with sourcemaps there
is no need for this anymore

* `images-dist` now `images-optimize` to better explain what this
function does
* More and better comments, particularly in the assets-loading file

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));
 });
 

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' ),