Below is some of the features:

• React
• React Router 4
• React Hot Loader 3
• Redux
• Redux Saga
• Redux Form
• Webpack 3
• Hapi.js
• Universal / Isomorphic / Server-sider Rendering

Please star my JavaScript version of React Server-side rendering boilerplate/example and my TypeScript version of React Server-side rendering boilerplate/example

Today I want to show you how I think JavaScript Classes should be structured. I’ve written classes many different ways over the years (Prototypal Inheritance, Object Literal Notation, Mootools, Base2js, Sencha Touch, Backbone and TypeScript). The following is a condensed example of the current format I use to structure my classes in JavaScript.

var BaseView = (function () {

    function BaseView() {
    }

    BaseView.prototype.createChildren = function () {
    };

    BaseView.prototype.layoutChildren = function () {
    };

    return BaseView;
})();

You may have seen prototypal inheritance before but in the example above you can see it is wrapped with an extra closure. Sometimes this is referred to as an immediately invoked function expression (iife). The extra iife allows us to have access to the class when we start extending other classes. It is in this example to keep our class structure consistent.

Inheritance

Prototypal or class inheritance is where one class can inherit characteristics from another class. The benefit is you don’t have the same exact code or functionality in several different classes. If there is a bug in your code you don’t have to fix it in 10 different places. You just have to fix it in one class and all classes extending that class will be fixed.

Below is an example of how to extend the class above.

var AnotherView = (function () {

    var _super = Extend(AnotherView, BaseView);

    function AnotherView() {
        _super.call(this);
    }

    AnotherView.prototype.createChildren = function () {
        _super.prototype.createChildren.call(this);
    };

    AnotherView.prototype.layoutChildren = function () {
    };

    return AnotherView;
})();

The format is constant with the the BaseView above but now we have this `_super` thing in our class. What `_super` allows you to do is call the functions/methods on the class you extended.

If you look at Extend in `var _super = Extend(AnotherView, BaseView);` it is a helper function that allows you to extend other classes easily. It will take the first class (AnotherView) and extend it with the second class (BaseView).

Below is the 12 line Extend function/class. Go ahead, put it in your projects to easily extend your classes.

var Extend = function (inheritorClass, baseClass) {
    for (var p in baseClass) {
        if (baseClass.hasOwnProperty(p)) {
            inheritorClass[p] = baseClass[p];
        }
    }
    function __() {
        this.constructor = inheritorClass;
    }
    __.prototype = baseClass.prototype;
    inheritorClass.prototype = new __();
    return baseClass;
};

Real World Example

You may have a view class like below that you always use and repeat the same methods and logic throughout most of your classes. Lets use this class as our base for all of our other view classes. After, scroll down to the next sample class to see how we can extend this class.

var BaseView = (function () {

    function BaseView($element) {
        if (($element instanceof jQuery) === true && $element.length === 0) {
            // If a jQuery object was passed in and it doesn't have any items then exit.
            return;
        }

        this.$element = $element;
        this.isEnabled = false;

        this.init();
    }

    BaseView.prototype.init = function() {
        // Kick off the view lifecycle
        this.createChildren()
            .setupHandlers()
            .enable()
            .layoutChildren();

        return this;
    };

    BaseView.prototype.createChildren = function() {
        // Used to create any objects for thr view and/or find references to child elements.
        return this;
    };

    BaseView.prototype.setupHandlers = function() {
        // Creates a class reference to an event handler method that is bound to the scope of the object.
        return this;
    };

    BaseView.prototype.layoutChildren = function() {
        // Optional use to set any child objects for the view. Also can be called later to update objects.
        return this;
    };

    BaseView.prototype.enable = function() {
        if (this.isEnabled === true) {
            return this;
        }
        this.isEnabled = true;

        // Add event listeners for this class.

        return this;
    };

    BaseView.prototype.disable = function() {
        if (!this.isEnabled === false) {
            return this;
        }
        this.isEnabled = false;

        // Remove event listeners for this class.

        return this;
    };

    BaseView.prototype.destroy = function() {
        this.disable();

        // Nulls out all properties of the class to prevent memory leak.
        for (var key in this) {
            if (this.hasOwnProperty(key)) {
                this[key] = null;
            }
        }
    };

    return BaseView;
})();

In the new class below you will notice we don’t need to set any properties or have any logic that we usually have in all of our view classes. Since we extended BaseView and called super throughout the different methods it will be handle behind the scenes and we can concentrate on what this new class needs to do.

var AnotherView = (function () {

    var _super = Extend(AnotherView, BaseView);

    function AnotherView($element) {
           // Put any properties above super.
            _super.call(this, $element);
            // Put any method calls below super.
    }

    AnotherView.prototype.createChildren = function() {
        _super.prototype.createChildren.call(this);

        return this;
    };

    AnotherView.prototype.setupHandlers = function() {
        _super.prototype.setupHandlers.call(this);

        return this;
    };

    AnotherView.prototype.layoutChildren = function() {
        return this;
    };

    AnotherView.prototype.enable = function() {
        if (this.isEnabled) {
            return this;
        }

        return _super.prototype.enable.call(this);
    };

    AnotherView.prototype.disable = function() {
        if (!this.isEnabled) {
            return this;
        }

       return _super.prototype.disable.call(this);
    };

    AnotherView.prototype.destroy = function() {

       _super.prototype.destroy.call(this);
    };

    return AnotherView;
})();

I did not come up with this structure. This is what the TypeScript compiler spits out. I’ve just clean it up for easier use in native JavaScript projects.

Check out the example files for this article.

Less Typing with Templates and Snippets

Want to speed up your development? Check out my other article Templates/Snippets in your IDE to learn more.

Below is an example of a template I created that will create new classes that extends the BaseView above.

Below you can see the snippets in action. Just hit the Tab key to fill in the next predefined input area.

Creating a Property

Creating a Method

Creating a Class

Sublime Text Snippets

Here are three Sublime Text snippets for you to use:
* Method Helper

* Property Helper

* View Class

1) To create a snippet, go to Tools > New Snippet.

2) A new sample snippet file will be created. Go ahead and replace all of the code with one of the snippets I provided above. Below I have replaced it with the BaseView snippet.

3) Now save the file and name it “view.sublime-snippet”. For Sublime Text snippets the file must end with “.sublime-snippet”.

The snippets files will be saved in: Sublime Text > Preferences > Browse Package > Users

4) Once you have created all three snippets above you can start using them. First, create a new file and save it with the class name you are creating, be sure to give it a “.js” extension. You must have the extension defined so Sublime Text knows what type of snippet to use.

Now start typing “view” and hit the Tab key on your keyboard.

5) You can see it has created a “AnotherView” class that extends “BaseView” with all of the default methods.

JetBrains Templates & Live Templates

With JetBrains you have File Templates & Live Templates. Here are three JetBrains templates for you to use:
* Method Helper

* Property Helper

* View Class

File Templates

1) Lets create a File Template for the View Class template. In PhpStorm/WebStorm you can right click on any folder in your project then select New > Edit File Templates.

2) Now click the green plus button top left and name it JS View. Copy the snippet provided above and paste it in. Click the OK button and you are ready to go.

3) Now you can click New > JS View to create a new view class.

Live Templates

For the Method Helper and Property Helper snippets above we need to do the following.

1) Go to Preferences > Live Templates > JavaScript and click on the plus symbol and select 1. Live Template.

2) Fill in the Abbreviation: with the name you want to type to trigger the snippet. Add the snippet I’ve provided in the Template text: area and then click the Define link.

3) After clicking the Define select JavaScript and click the Apply button.

4) One thing you will want to do is click the Edit variables and order the names like I have below. Also on the Method Helper you will need to set the Expression and check the Skip if defined checkbox.

5) When you want to use the Live Template use Ctrl+J or Cmd+J and start typing the Abbreviation name to insert the snippet.

This template article relates to another article I wrote How To Write JavaScript Classes. Please let me know if you use and like these templates.

Grunt JS Setup

If you have never used GruntJS before you probably need to checkout my Install Grunt JS on a Mac Tutorial or Install Grunt JS on Windows Tutorial.

Example Code

To follow along with this tutorial you may want to download the files from https://github.com/codeBelt/Example-JSON-to-Javascript and click the “Download Zip” button.

Grunt File

If you take a look at the json config area you will see some options. Those options are:

namespace

The namespace in which the json data will be assigned. (Default: ‘myjson’)

includePath

Includes the full path of the file and the extension. By default only the file name is used as the key value. (Default: false)

processName

This option accepts a function which takes one argument (filename) and returns a string which will be used as the key for the object. The example below stores all json data on the default JSON_DATA namespace in lowercase letters. (Default: null)

module.exports = function(grunt) {

    // Project configuration.
    grunt.initConfig({

        //Read the package.json (optional)
        pkg: grunt.file.readJSON('package.json'),

        // Constants for the Gruntfile so we can easily change the path for
        // our environments.
        BASE_PATH: '../',
        DEVELOPMENT_PATH: '../dev/',
        PRODUCTION_PATH: '../prod/',

        // The JSON to JavaScript plugin.
        json: {
            prod: {
                options: {
                    namespace: 'JSON_DATA',
                    includePath: false,
                    processName: function(filename) {
                        return filename.toLowerCase();
                    }
                },
                src: ['<%= DEVELOPMENT_PATH %>' + '**/*.json'],
                dest: '<%= PRODUCTION_PATH %>' + 'assets/scripts/json.js'
            }
        }

    });

    // Loads the necessary tasks for this Grunt file.
    grunt.loadNpmTasks('grunt-json');

    // Grunt tasks.
    grunt.registerTask('default', ['json']);

};

Checkout the grunt-json plugin to learn more about the plugin.

JSON File

The grunt-json plugin will take the following JSON data convert it into a JavaScript Object like in the next example.

{
    "name": "Product",
    "properties": {
        "id": {
            "type": "number",
            "description": "Product identifier",
            "required": true
        },
        "name": {
            "description": "Name of the product",
            "type": "string",
            "required": true
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "required": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}

JSON Converted to JavaScript

Below is what the JavaScript file will look like.

var JSON_DATA = JSON_DATA || {};
JSON_DATA["products"] = {
    "name": "Product",
    "properties": {
        "id": {
            "type": "number",
            "description": "Product identifier",
            "required": true
        },
        "name": {
            "description": "Name of the product",
            "type": "string",
            "required": true
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "required": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
};

Now we can used the data like any other JavaScript Object.

console.log( JSON_DATA.products );

Leave me a comment, I love comments.

grunt-contrib-requirejs
grunt-contrib-cssmin
grunt-contrib-htmlmin
grunt-contrib-copy
grunt-contrib-concat
grunt-env
grunt-preprocess
grunt-contrib-yuidoc
grunt-contrib-watch
grunt-contrib-clean
grunt-banner
grunt-usemin
grunt-manifest
grunt-express
grunt-open

Grunt JS Setup

If you have never used GruntJS before you probably need to checkout my Install Grunt JS on a Mac Tutorial or Install Grunt JS on Windows Tutorial.

Example Code

To follow along with this tutorial you may want to download the files from https://github.com/codeBelt/Single-Page-Application-Workflow-Boilerplate and click the “Download Zip” button.

Environments

We will setup GruntJS to build our development (src/ folder) environment and our production (web/ folder) environments. Our two GruntJS commands will be grunt and grunt web.

We will start with the following:

/
├──  src/
├──  web/
├──  Gruntfile.js
└──  package.json

src folder

The src folder will have all of the source files we need to create a single page JavaScript application.

web folder

The web folder will only contain the minified files and assets needed for the production server.

Gruntfile.js & package.json Files

The GruntJS tasks and plugins need to build our environments.

Development Folder

Lets take a look at our src folder. Notice the src/config.html file. This file will be used to create the index.html file for both our development (src) and production (web) environment.

/
├──+ src/
│  ├── assets/
│  ├── favicon.ico
│  └── config.html
├──  Gruntfile.js
└──  package.json

If where too run both the development (grunt) and production (grunt web) commands it would generate the following:

/
├──+ src/
│  ├── assets/
│  ├── favicon.ico
│  ├── config.html
│  └── index.html
├──+ web/
│  ├── assets/
│  ├── favicon.ico
│  ├── offline.appcache
│  └── index.html
├──  Gruntfile.js
└──  package.json

Here is our config.html in the src folder. Notice the NODE_ENV conditions, they will be used to determine how the production and development html file will be generated.

<!DOCTYPE html>

<!-- @if NODE_ENV == 'DEVELOPMENT' -->
<html lang="en">
<!-- @endif -->

<!-- @if NODE_ENV == 'PRODUCTION' -->
<html lang="en" manifest="offline.appcache">
<!-- @endif -->

<head>
    <!-- The current version of the application -->
    <meta name="version" content="<!-- @echo buildVersion -->"/>

    <!-- Add the fav icon -->
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">

    <!-- build:css assets/styles/app.min.css -->
        <link rel="stylesheet" media="screen, projection" href="assets/styles/setup.css" />
        <link rel="stylesheet" media="screen, projection" href="assets/styles/bootstrap.css" />
        <link rel="stylesheet" media="screen, projection" href="assets/styles/screen.css" />
    <!-- endbuild -->

</head>
<body>
    <!-- @if NODE_ENV == 'DEVELOPMENT' -->
        <script src="assets/vendor/require/require.js" data-main="assets/scripts/AppBootstrap.js"></script>
        <script src="assets/scripts/config.js"></script>
    <!-- @endif -->

    <!-- @if NODE_ENV == 'PRODUCTION' -->
        <script src="assets/scripts/require.js" data-main="assets/scripts/app.min.js"></script>
    <!-- @endif -->
    </body>
</html>

Install GruntJS & the necessary plugins

Lets look how I setup the package.json file. This file will install Grunt and Grunt plugins locally for our project. All we have to do to install all of the plugins is type npm install when in root of this project and it will install everything we need.

{
    "name": "Single-Page-Application-GruntJS",
    "version": "0.2.0",

    "appVersion": "0.1.0",
    "description": "A sample single page JavaScript application workflow boilerplate with Grunt.js",
    "url": "https://codebelt.github.io/blog/javascript/single-page-javascript-application-workflow/",
    "developedBy": "codeBelt",

    "devDependencies": {
        "grunt": "0.4.2",
        "matchdep": "0.3.0",

        "grunt-contrib-requirejs": "0.4.1",
        "grunt-contrib-yuidoc": "0.5.0",
        "grunt-contrib-watch": "0.5.3",
        "grunt-contrib-cssmin": "0.7.0",
        "grunt-contrib-htmlmin": "0.1.3",
        "grunt-contrib-concat": "0.3.0",
        "grunt-contrib-uglify": "0.2.7",
        "grunt-contrib-copy": "0.4.1",
        "grunt-contrib-clean": "0.5.0",
        "grunt-banner": "0.2.0",
        "grunt-usemin": "2.0.2",
        "grunt-manifest": "0.4.0",
        "grunt-preprocess": "4.0.0",
        "grunt-env": "0.4.1",
        "grunt-express": "1.2.1",
        "grunt-open": "0.2.2"
    }
}

Take notice of the “version” property. It will be used in the creation of the index.html, minified css, minified JavaScript and the cache manifest files.

Here is the Gruntfile.js file. You can read the comments to see what each plugin is doing.

module.exports = function(grunt) {

    // Load Grunt tasks declared in the package.json file.
    require('matchdep').filterDev('grunt-*').forEach(grunt.loadNpmTasks);

    // Project configuration.
    grunt.initConfig({

        /**
        * This will load in our package.json file so we can have access
        * to the project name and appVersion number.
        */
        pkg: grunt.file.readJSON('package.json'),

        /**
        * Constants for the Gruntfile so we can easily change the path for our environments.
        */
        BASE_PATH: '',
        DEVELOPMENT_PATH: 'src/',
        PRODUCTION_PATH: 'web/',

        /**
        * A code block that will be added to our minified code files.
        * Gets the name and appVersion and other info from the above loaded 'package.json' file.
        * @example <%= banner.join("\\n") %>
        */
        banner: [
            '/*',
            '* Project: <%= pkg.name %>',
            '* Version: <%= pkg.appVersion %> (<%= grunt.template.today("yyyy-mm-dd") %>)',
            '* Development By: <%= pkg.developedBy %>',
            '* Copyright(c): <%= grunt.template.today("yyyy") %>',
            '*/'
        ],

        /**
        * The different constant names that will be use to build our html files.
        * @example <!-- @if NODE_ENV == 'DEVELOPMENT' -->
        */
        env: {
            src: {
                NODE_ENV : 'DEVELOPMENT'
            },
            web : {
                NODE_ENV : 'PRODUCTION'
            }
        },

        /**
        * Allows us to pass in variables to files that have place holders so we can similar files with different data.
        * This plugin works with the 'env' plugin above.
        * @example <!-- @echo appVersion --> or <!-- @echo filePath -->
        */
        preprocess : {
            // Task to create the index.html file that will be used during development.
            // Passes the app version and creates the /index.html
            src : {
                src : '<%= DEVELOPMENT_PATH %>' + 'config.html',
                dest : '<%= DEVELOPMENT_PATH %>' + 'index.html',
                options : {
                    context : {
                        appVersion : '<%= pkg.appVersion %>',
                        filePath: ''
                    }
                }
            },
            // Task to create the index.html file that will be used in production.
            // Passes the app version and creates the /index.html
            web : {
                src : '<%= DEVELOPMENT_PATH %>' + 'config.html',
                dest : '<%= PRODUCTION_PATH %>' + 'index.html',
                options : {
                    context : {
                        appVersion : '<%= pkg.appVersion %>',
                        filePath: ''
                    }
                }
            }
        },

        /**
        * Cleans or deletes our production folder before we create a new production build.
        */
        clean: {
            dist: ['<%= PRODUCTION_PATH %>']
        },

        /**
        * Copies certain files over from the development folder to the production folder so we don't have to do it manually.
        */
        copy: {
            web:  {
                files: [
                    // Copy favicon.ico file from development to production
                    { expand: true, cwd: '<%= DEVELOPMENT_PATH %>', src: 'favicon.ico', dest: '<%= PRODUCTION_PATH %>' },
                    // Copy the media folder from development to production
                    { expand: true, cwd: '<%= DEVELOPMENT_PATH %>', src: ['assets/media/**'], dest: '<%= PRODUCTION_PATH %>' },
                    // Copy the index.html file from development to production
                    { expand: true, cwd: '<%= DEVELOPMENT_PATH %>', dest: '<%= PRODUCTION_PATH %>', src: ['index.html'], filter: 'isFile', dot: true },
                    // Copy require.js file from development to production
                    { expand: true, cwd: '<%= DEVELOPMENT_PATH %>' + 'assets/vendor/require/', src: 'require.js', dest: '<%= PRODUCTION_PATH %>' + 'assets/scripts/' }
                ]
            }
        },

        /**
        * Prepends the banner above to the minified files.
        */
        usebanner: {
            dist: {
                options: {
                    position: 'top',
                    banner: '<%= banner.join("\\n") %>',
                    linebreak: true
                },
                files: {
                    src: [
                        '<%= PRODUCTION_PATH %>' + 'assets/scripts/app.min.js',
                        '<%= PRODUCTION_PATH %>' + 'assets/styles/app.min.css'
                    ]
                }
            }
        },

        /**
        * The useminPrepare part of the usemin plugin looks at the html file and checks for a build:js or build:css code block.
        * It will take those files found in the code block(s) and concat them together and then runs uglify for js and/or cssmin for css files.
        * useminPrepare requires grunt-contrib-uglify, grunt-contrib-concat, and grunt-contrib-cssmin plugins to be installed. Which is listed in the package.json file.
        *
        * The usemin part will remove the code block(s) and replace that area with the single file path in the html file.
        */
        useminPrepare: {
            html: ['<%= DEVELOPMENT_PATH %>' + 'index.html'],
            options: {
                dest: '<%= PRODUCTION_PATH %>'// Moves the single concatenated files to production.
            }
        },
        usemin: {
            html: ['<%= PRODUCTION_PATH %>' + 'index.html'],
            options: {
                dirs: ['<%= PRODUCTION_PATH %>']
            }
        },

        /**
        * The RequireJS plugin that will use uglify2 to build and minify our JavaScript,
        * templates and any other data we include in the require files.
        */
        requirejs: {
            compile: {
                options: {
                    baseUrl: '<%= DEVELOPMENT_PATH %>' + 'assets/scripts/',                         // Path of source scripts, relative to this build file
                    mainConfigFile: '<%= DEVELOPMENT_PATH %>' + 'assets/scripts/config.js',         // Path of shared configuration file, relative to this build file
                    name: 'AppBootstrap',                                                           // Name of input script (.js extension inferred)
                    out: '<%= PRODUCTION_PATH %>' + 'assets/scripts/app.min.js',                    // Path of built script output

                    fileExclusionRegExp: /.svn/,                                                    // Ignore all files matching this pattern
                    useStrict: true,
                    preserveLicenseComments: false,
                    pragmas: {
                        debugExclude: true
                    },

                    optimize: 'uglify2',                                                            // Use 'none' If you do not want to uglify.
                    uglify2: {
                        output: {
                            beautify: false,
                            comments: false
                        },
                        compress: {
                            sequences: false,
                            global_defs: {
                                DEBUG: false
                            }
                        },
                        warnings: false,
                        mangle: true
                    }
                }
            }
        },

        /**
        * Removes all comments from the production index.html file. I can also remove all whitespace if desired.
        */
        htmlmin: {
            dist: {
                options: {
                    removeComments: true,
                    collapseWhitespace: false
                },
                files: {
                    '<%= PRODUCTION_PATH %>index.html': '<%= PRODUCTION_PATH %>' + 'index.html'
                }
            }
        },

        /**
        * Creates a Cache Manifest file.
        */
        manifest: {
            generate: {
                options: {
                    basePath: '<%= PRODUCTION_PATH %>',
                    exclude: [
                        'assets/media/images/moblie-icons/icon-144x144.png',
                        'assets/media/images/moblie-icons/icon-100x100.png',
                        'assets/media/images/moblie-icons/icon-29x29.png',
                        'assets/media/images/moblie-icons/icon-50x50.png',
                        'assets/media/images/moblie-icons/icon-58x58.png',
                        'assets/media/images/moblie-icons/icon-72x72.png'
                    ],
                    preferOnline: false,
                    verbose: true,
                    timestamp: true,
                    master: []
                },
                src: [
                    'assets/data/**/*.json',
                    'assets/media/images/**/*.jpg',
                    'assets/media/images/**/*.png',
                    'assets/scripts/**/*.js',
                    'assets/styles/**/*.css'
                ],
                dest: '<%= PRODUCTION_PATH %>' + 'offline.appcache'
            }
        },

        /**
        * YUIDoc plugin that will generate documentation from our YUI comments.
        */
        yuidoc: {
            compile: {
                name: '<%= pkg.name %>',
                description: '<%= pkg.description %>',
                version: '<%= pkg.appVersion %>',
                url: '<%= pkg.homepage %>',
                options: {
                    paths: '<%= DEVELOPMENT_PATH %>' + 'assets/scripts/',
                    outdir: '<%= BASE_PATH %>docs',
                    themedir: '',
                    extension: '.js',                                   // Default '.js' <comma-separated list of file extensions>
                    exclude: ''
                }
            }
        },

        /**
        * Creates a node.js Express Server to test our code in a server like environment.
        * Note: We are using the watch task to keep the server running.
        */
        express: {
            src: {
                options: {
                    port: 8000,
                    hostname: "0.0.0.0",
                    bases: ['<%= DEVELOPMENT_PATH %>'],
                    livereload: true
                }
            },
            web: {
                options: {
                    port: 8001,
                    hostname: "0.0.0.1",
                    bases: ['<%= PRODUCTION_PATH %>'],
                    livereload: true
                }
            }
        },

        /**
        * Opens the index.html file in the default browser after the node.js Express Server is running.
        */
        open: {
            src: {
                // Gets the port from the connect configuration
                path: ' express.src.options.port%>'
            },
            web: {
                // Gets the port from the connect configuration
                path: ' express.web.options.port%>'
            }
        },

        /**
        * Watches files and will run task(s) when files are changed. It will also reload/refresh the browser.
        */
        watch: {
            css: {
                options: {
                    livereload: true
                },
                files: [
                    '<%= DEVELOPMENT_PATH %>' + 'assets/styles/**/*.css',
                ]
            },
            src: {
                options: {
                    livereload: true
                },
                files: [
                    '<%= DEVELOPMENT_PATH %>' + 'assets/scripts/**/*.ts',
                    '<%= DEVELOPMENT_PATH %>' + 'config.html',
                    '<%= DEVELOPMENT_PATH %>' + 'assets/templates/**/*.hbs'
                ],
                tasks: ['src']
            }
        }

    });

    /**
    * Grunt tasks:
    *
    * grunt        (Will build and run your development code/server)
    * grunt web    (Will build and run your production code/server)
    * grunt doc    (Will generate the YUI documentation from the code comments)
    */
    grunt.registerTask('default', [
        'server'
    ]);

    grunt.registerTask('server', [
        'src',
        'express:src',
        'open:src',
        'watch'
    ]);

    grunt.registerTask('src', [
        'env:src',
        'preprocess:src'
    ]);

    grunt.registerTask('web', [
        'env:web',
        'preprocess',
        'clean',
        'copy',
        'useminPrepare', 'concat', 'cssmin',
        'usemin',
        'requirejs',
        'usebanner',
        'htmlmin',
        'manifest',
        'open:web',
        'express:web',
        'express-keepalive'
    ]);

    grunt.registerTask('doc', [
        'yuidoc'
    ]);

};

Please let me know if you liked this tutorial.

In this YUIDoc JavaScript Documentation Tutorial I will be using the GruntJS YUIDoc Plugin to generate the JavaScript Docs.

Grunt JS Setup

If you have never used GruntJS before you will need to checkout my Install Grunt JS on a Mac Tutorial or Install Grunt JS on Windows Tutorial.

Now download the example files below and navigate with Terminal or the Command Prompt to the “_build” folder and type in:

npm install

On a Mac you may need to type:

sudo npm install

Basically what “npm install” is doing is looking for a “package.json” file and checks the “devDependencies”. NodeJS will download and install the necessary files for your GruntJS setup. Here is our package file:

{
    "name": "YUI-Docs",
    "version": "0.1.0",
    "description": "This is the description.",
    "url": "http://www.test.com",/
    "devDependencies": {
        "grunt": "~0.4.1",
        "grunt-contrib-yuidoc": "*"
    }
}

Luckily EaselJS uses YUIDoc and I could run a test with JavaScript classes already committed. Below is how the Gruntfile is setup.

// Metadata.
meta: {
    basePath: '../',
    srcPath: '../easeljs/',
    docsPath: '../docs/',
    deployPath: '../deploy/'
},

// Task configuration.
yuidoc: {
    compile: {
        name: '<%= pkg.name %>',
        description: '<%= pkg.description %>',
        version: '<%= pkg.version %>',
        url: '<%= pkg.homepage %>',
        options: {
            paths: '<%= meta.srcPath %>',
            outdir: '<%= meta.docsPath %>',
            themedir: '',
            exclude: ''
        }
    }
}

Now all we have to do is type the command below and it will generate the JavaScript documents for us.

grunt yuidoc

If you want to get a good overview of YUIDoc check out Documenting JavaScript with YUIDoc. Also it seems YUIDoc is not just for JavaScript Documenting before all languages.

Download the examples files to see the outputted docs.

It might be a secret you want to keep like my grandmothers chocolate chip cookie recipe but I want know, I want to learn, please teach me. I can keep a secret and you can email me at code{AT}codebelt.com. I used to work with Andy your Server-Side Savant. Maybe he can vouch for me.

While I am at it can you also create GreenSock LoaderMax JS.

Grunt JS Setup

If you have never used GruntJS before you will need to checkout my Install Grunt JS on a Mac Tutorial or Install Grunt JS on Windows Tutorial.

Now download the example files below and navigate with Terminal or the Command Prompt to the “_build” folder and type in:

npm install

On a Mac you may need to type:

sudo npm install

Basically what “npm install” is doing is looking for a “package.json” file and checks the “devDependencies”. NodeJS will download and install the necessary files for your GruntJS setup. Here is our package file:

{
    "name": "UnderScoreTemplate",
    "version": "0.1.0",
    "devDependencies": {
        "grunt": "~0.4.1",
        "grunt-contrib-jst": "~0.5.0"
    }
}

Compiling Underscore Templates into JavaScript

Now that we have the GruntJS packages added to our “_build/node_modules/” folder we can start converting Underscore templates into precompiled JavaScript template Functions.

What the JST GruntJS plugin will do is take the Underscore template (templates/home/UserDetailTemplate.tpl) below and will create a JavaScript function that will return the template as a string.

<%
    var length = userList.length;
    for (var index = 0; index < length; index++) {
        var user = userList[index];
%>
        <tr>
            <td><%= index %></td>
            <td><%= user.firstName %></td>
            <td><%= user.lastName %></td>
            <td><%= user.email %></td>
        </tr>
<% } %>

Here is the function it creates. It uses the path and name of the template as the function name.

this["JST"]["templates/home/UserDetailTemplate.tpl"] = function (obj) {
    obj || (obj = {});
    var __t, __p = '', __e = _.escape, __j = Array.prototype.join;

    function print() {
        __p += __j.call(arguments, '')
    }

    with (obj) {
        var length = userList.length;
        for (var index = 0; index < length; index++) {
            var user = userList[index];
            ;
            __p += '\r\n        <tr>\r\n            <td>' +
                ((__t = ( index )) == null ? '' : __t) +
                '</td>\r\n            <td>' +
                ((__t = ( user.firstName )) == null ? '' : __t) +
                '</td>\r\n            <td>' +
                ((__t = ( user.lastName )) == null ? '' : __t) +
                '</td>\r\n            <td>' +
                ((__t = ( user.email )) == null ? '' : __t) +
                '</td>\r\n        </tr>\r\n';
        };
    }
    return __p
};

To use the precompiled JavaScript template Function in your JavaScript code you would do the following:

var userDetailTemplate = window['JST']['templates/home/UserDetailTemplate.tpl']();
jQuery('body').append(userDetailTemplate);

Since the Underscore template example above expects an Array we will need to pass the data(Array) into the function-call operator as we do below:

var data = [
...
]
var userDetailTemplate = window['JST']['templates/home/UserDetailTemplate.tpl'](data );
jQuery('body').append(userDetailTemplate);

Precompiled JavaScript Template Example

On to my example code which you can download below and see how this all works. I hope code is straight forward.

<script>
    /**
     * Helper Function to get the template function and returns the compiled
     * template string.
     * @param {string} templatePath The path and name of the template you want to use.
     * @param {Object=} data Optional data to be used within the template.
     * @returns {string} Returned compiled template.
     */
    function createTemplate(templatePath, data) {
        var templateString = window['JST'][templatePath](data);
        return templateString;
    }

    /**
     * Initialize Function that gets called when the page is loaded (window.onload).
     * All of our JavaScript code to generate the templates and add it to the DOM.
     */
    function init() {
        // Data for the UserDetailTemplate template.
        var userListData = [
            {
                firstName: 'Mark',
                lastName: 'Otto',
                email: 'mark@example.com'
            },
            {
                firstName: 'Jacob',
                lastName: 'Thornton',
                email: 'jacob@example.com'
            },
            {
                firstName: 'Larry',
                lastName: 'Bird',
                email: 'lary@example.com'
            }
        ];

        // Get templates by path and template name.
        var titleBar = createTemplate('templates/titlebar/TitleBarTemplate.tpl');
        var header = createTemplate('templates/home/HelloTemplate.tpl', { title: 'Robert Is Cool!' });
        var users = createTemplate('templates/home/UserDetailTemplate.tpl', {userList: userListData});

        // Add the template string to the DOM with jQuery.
        var $body = $('body');
        $body.append(titleBar);
        $body.append(header);
        $body.find('tbody').html(users);
    }

    // Calls the init Function on window load.
    window.onload = init;
</script>

Gruntfile

If you dive into the “Gruntfile.js” file you will see:

jst: {
    compile: {
        options: {
            //namespace: "anotherNameThanJST",      //Default: 'JST'
            prettify: false,                        //Default: false|true
            amdWrapper: false,                      //Default: false|true
            templateSettings: {
            },
            processName: function(filename) {
                //Shortens the file path for the template.
                return filename.slice(filename.indexOf("template"), filename.length);
            }
        },
        files: {
            "<%= meta.deployPath %>scripts/templates.js": ["<%= meta.srcPath %>templates/**/*.tpl"]
        }
    }
}

I will point out a couple of things. Look at the files: {…} property. The first part <%= meta.deployPath %>scripts/templates.js is the export path and file name(templates.js) we want the template(s) to be outputted to. The second part [“<%= meta.srcPath %>templates/**/*.tpl”] is where the Underscore templates are located. The templates/**/ means look in the templates directory and all the sub directories. The *.tpl means look for all files that have an extension of .tpl. This will take all those .tpl files and precompile the Underscore templates into JavaScript Functions to a file called templates.js.

Another one I want to point out is the “processName” function. This allows you to modify the file name before the precompiling finishes. By default in my case, all my template Function names would be like below because where my Gruntfile is located:

this["JST"]["../assets/src/templates/home/UserDetailTemplate.tpl"]

I don’t like the look of that and I just wanted to remove everything before the “template” word to get this:

this["JST"]["templates/home/UserDetailTemplate.tpl"]

Now all we have to do is type the command below and it will precompile our Underscore templates.

grunt jst

It maybe best to download the example and start playing around with it.

In this JavaScript tutorial I will show a very simple example how you can integration Greensock (Tweenmax / Tweenlite) with EaselJS.

var canvas = document.getElementById('mainCanvas');
var stage = new createjs.Stage(canvas);

var shape = new createjs.Shape();
shape.graphics.beginFill("#000");
shape.graphics.drawCircle(0, 0, 100);
shape.graphics.endFill();
stage.addChild(shape);

stage.update();

TweenLite.ticker.addEventListener("tick", stage.update, stage);

TweenLite.to(shape, 1, {delay: 1, x:100, y:100, ease:Cubic.easeInOut});

Here is all the HTML markup and JavaScript for the EaselJS and Tweenlite example.

<!DOCTYPE html>
<html>
<head>
    <title>EaselJS with GreenSock Tweenlite TweenMax</title>
    <script type="text/javascript" src="libs/easeljs/easeljs-0.6.0.min.js"></script>
    <script type="text/javascript" src="libs/greensock/easing/EasePack.min.js"></script>
    <script type="text/javascript" src="libs/greensock/TweenLite.min.js"></script>
    <script type="text/javascript">
        function init()
        {
            var canvas = document.getElementById('mainCanvas');
            var stage = new createjs.Stage(canvas);

            var shape = new createjs.Shape();
            shape.graphics.beginFill("#000");
            shape.graphics.drawCircle(0, 0, 100);
            shape.graphics.endFill();
            stage.addChild(shape);
            stage.update();

            TweenLite.ticker.addEventListener("tick", stage.update, stage);

            TweenLite.to(shape, 1, {delay: 1, x:100, y:100, ease:Cubic.easeInOut});
        }
    </script>
</head>
<body onload="javascript:init();">

    <canvas id="mainCanvas" width="400" height="400"></canvas>

</body>

You can download example files below:

Install Ruby and Sass

First thing we need to is get Ruby and Sass installed on our computer. If you are using a Mac you do not need to install Ruby. For my Windows computer I used http://rubyinstaller.org/ to install Ruby. Be sure to check the “Add Ruby executables to your Path” checkbox.

To install Sass on Windows open the Command Prompt and type:

gem install sass

To install Sass on your Mac open Terminal and type:

sudo gem install sass

You should see the following after Sass is successfully installed.

Fetching: sass-3.2.7.gem (100%)
Successfully installed sass-3.2.7
Parsing documentation for sass-3.2.7
Installing ri documentation for sass-3.2.7
Done installing documentation for sass (18 sec).
1 gem installed

Grunt JS Setup

If you have never used GruntJS before you will need to checkout my Install Grunt JS on a Mac Tutorial or Install Grunt JS on Windows Tutorial.

Now download the example files below and navigate with Terminal or the Command Prompt to the “_build” folder and type in:

npm install

On a Mac you may need to type:

sudo npm install

Compiling Sass into CSS

Now that we have the Grunt JS packages added to our “_build/node_modules/” folder we can start converting sass into css. Check out the “Gruntfile.js” and you will see:

sass: {
    dist: {
        files: {
            '<%= meta.deployPath %>main.css': '<%= meta.srcPath %>main.scss'
        }
    }
}

That’s the magic where it will take your main.scss and all the @import’s and compile it into one css file. Now all we have to do is type the command below:

grunt

This works because in our “Gruntfile.js” file we have default Grunt JS task setup to use “sass”:

grunt.registerTask('default', ['sass']);

SASS Watch Command

Lets make this better by any time a sass file is edited or added Grunt JS will compile the files into css. Take a look at the “package.json” file in our “_build” folder. It should look like this:

{
  "name": "Test-SASS-To-CSS",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-contrib-sass": "*"
  }
}

Now add [“grunt-contrib-watch”: “*”] to devDependencies. Yours should look like this now:

{
    "name": "Test-SASS-To-CSS",
    "version": "0.1.0",
    "devDependencies": {
        "grunt": "~0.4.1",
        "grunt-contrib-sass": "*",
        "grunt-contrib-watch": "*"
    }
}

Type the below command to install the watch task packager to your local “_build” folder.

npm install

Ok, trust me we are almost done. Once you do this for one project. Setting up another project will be faster. Now we need to add the below code to the “Gruntfile.js” file.

watch: {
    scripts: {
        files: [
            '<%= meta.srcPath %>/**/*.scss'
        ],
        tasks: ['sass']
    }
}

grunt.loadNpmTasks('grunt-contrib-watch');

Your “Gruntfile.js” file should look like this now:

module.exports = function(grunt) {

    // Project configuration.
    grunt.initConfig({

        //Read the package.json (optional)
        pkg: grunt.file.readJSON('package.json'),

        // Metadata.
        meta: {
            basePath: '../',
            srcPath: '../assets/sass/',
            deployPath: '../assets/css/'
        },

        banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
                '<%= grunt.template.today("yyyy-mm-dd") %>\n' +
                '* Copyright (c) <%= grunt.template.today("yyyy") %> ',

        // Task configuration.
        sass: {
            dist: {
                files: {
                    '<%= meta.deployPath %>main.css': '<%= meta.srcPath %>main.scss'
                }
            }
        },

        watch: {
            scripts: {
                files: [
                    '<%= meta.srcPath %>/**/*.scss'
                ],
                tasks: ['sass']
            }
        }

    });

    // These plugins provide necessary tasks.
    grunt.loadNpmTasks('grunt-contrib-sass');
    grunt.loadNpmTasks('grunt-contrib-watch');

    // Default task.
    grunt.registerTask('default', ['sass']);

};

To start the watch command we need to type:

grunt watch

Not sure if that was painful for you but for me creating this tutorial was. It seems like a lot of steps but after you use Grunt JS a couple of times you will see the benefit.

Chrome Developer Tools Video Tutorials

http://discover-devtools.codeschool.com/

Google Blog Post

http://blog.chromium.org/2013/03/discover-chrome-devtools-our-new.html

Discover DevTools Companion Extention

https://chrome.google.com/webstore/detail/discover-devtools-compani/angkfkebojeancgemegoedelbnjgcgme

I will be installing Grunt.js v0.4.1. WARNING if you have Grunt.j 0.3.x or less you will need to uninstall it first.

Grunt’s command line interface (CLI)

To get grunt.js installed we need to first install Grunt’s command line interface (CLI) globally. Current version is 1.0.6. Open up Windows Command Prompt and put in the command below:

npm install grunt-cli -g

This will put the grunt command in your system path, allowing it to be run from any directory.

Windows Tip – Open Command Prompt from Folder (Two Ways)

1. Type cmd into the address bar and hit enter
2. Hold Shift while Right-Clicking a blank space in the folder and select Open Command Window Here.

Folder and Package JSON Setup

Now we need to install Grunt.js. With Windows Command Prompt navigate to our project folder. I like to put all my build files into a folder called “_build”. So for this example the path is “C:\Users\codebelt\Desktop\first-grunt-project\_build”.

There are a few different ways to get Grunt.js and other plugins installed but I will be showing you the easiest way (I think). We need to create a “package.json” and put it in our “_build” folder. Copy and past code below and put in the “package.json”

{
  "name": "Test-Project",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-contrib-concat": "~0.1.3"
  }
}

When the next command below is ran it will install grunt v0.4.1 and the grunt plugin concat v0.1.3 into the “_build” folder.

Here is the command:

npm install

Grunt File Setup

Now Grunt.js and the Concat plugin should be installed. Now we need to add a Grunt file to configure and build our project. Create a “Gruntfile.js” file inside the “_build” folder and paste in the code below.

module.exports = function(grunt) {

    // Project configuration.
    grunt.initConfig({

        //Read the package.json (optional)
        pkg: grunt.file.readJSON('package.json'),

        // Metadata.
        meta: {
            basePath: '../',
            srcPath: '../src/',
            deployPath: '../deploy/'
        },

        banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
                '<%= grunt.template.today("yyyy-mm-dd") %>\n' +
                '* Copyright (c) <%= grunt.template.today("yyyy") %> ',

        // Task configuration.
        concat: {
            options: {
                stripBanners: true
            },
            dist: {
                src: ['<%= meta.srcPath %>scripts/fileone.js', '<%= meta.srcPath %>scripts/filetwo.js'],
                dest: '<%= meta.deployPath %>scripts/app.js'
            }
        }
    });

    // These plugins provide necessary tasks.
    grunt.loadNpmTasks('grunt-contrib-concat');

    // Default task
    grunt.registerTask('default', ['concat']);

};

If you look you can see I have created a fileone.js and filetwo.js file and placed them into the ../src/scripts directory. This GruntJS script will take those files and export into the ../deploy/scripts folder as app.js. I am using <%= meta.srcPath %> as a constant or base path to my src folder. This allows me to change the base path in one location than having it hard coded all over the Gruntfile.

Now type “grunt” into Windows Command Prompt and watch the magic happen.

grunt

That will run the Default task and concatenate the two js files into one. Try it out, I hope this works for you. You should see the output in Windows Command Prompt say:

Running "concat:dist" (concat) task
File "../deploy/scripts/app.js" created.

Done, without errors.

You can download the example files for this tutorial here:

I will be installing Grunt.js v0.4.1. WARNING if you have Grunt.j 0.3.x or less you will need to uninstall it first.

Grunt’s command line interface (CLI)

To get grunt.js installed we need to first install Grunt’s command line interface (CLI) globally. Current version is 1.0.6. Open Terminal and put in the command below:

npm install grunt-cli -g

You may get an error that says “Please try running this command again as root/Administrator.” You will need to put sudo before you command.

sudo npm install grunt-cli -g

This will put the grunt command in your system path, allowing it to be run from any directory.

Mac Tip – Open Terminal from Folder

1. If you have the Terminal icon on your Dock you can drag the folder to the Terminal icon and it will open to that folder path.

Folder and Package JSON Setup

Now we need to install Grunt.js. With Terminal navigate to our project folder. I like to put all my build files into a folder called “_build”. So for this example the path is “/Users/codebelt/Desktop/project/_build”.

There are a few different ways to get Grunt.js and other plugins installed but I will be showing you the easiest way (I think). We need to create a “package.json” and put it in our “_build” folder. Copy and past code below and put in the “package.json”

{
  "name": "Test-Project",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-contrib-concat": "~0.1.3"
  }
}

When the next command below is ran it will install grunt v0.4.1 and the grunt plugin concat v0.1.3 into the “_build” folder.

Here is the command:

sudo npm install

Grunt File Setup

Now Grunt.js and the Concat plugin should be installed. Now we need to add a Grunt file to configure and build our project. Create a “Gruntfile.js” file inside the “_build” folder and paste in the code below.

module.exports = function(grunt) {

    // Project configuration.
    grunt.initConfig({

        //Read the package.json (optional)
        pkg: grunt.file.readJSON('package.json'),

        // Metadata.
        meta: {
            basePath: '../',
            srcPath: '../src/',
            deployPath: '../deploy/'
        },

        banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
                '<%= grunt.template.today("yyyy-mm-dd") %>\n' +
                '* Copyright (c) <%= grunt.template.today("yyyy") %> ',

        // Task configuration.
        concat: {
            options: {
                stripBanners: true
            },
            dist: {
                src: ['<%= meta.srcPath %>scripts/fileone.js', '<%= meta.srcPath %>scripts/filetwo.js'],
                dest: '<%= meta.deployPath %>scripts/app.js'
            }
        }
    });

    // These plugins provide necessary tasks.
    grunt.loadNpmTasks('grunt-contrib-concat');

    // Default task
    grunt.registerTask('default', ['concat']);

};

If you look you can see I have created a fileone.js and filetwo.js file and placed them into the ../src/scripts directory. This GruntJS script will take those files and export into the ../deploy/scripts folder as app.js. I am using <%= meta.srcPath %> as a constant or base path to my src folder. This allows me to change the base path in one location than having it hard coded all over the Gruntfile.

Now type “grunt” into Terminal and watch the magic happen.

grunt

That will run the Default task and concatenate the two js files into one. Try it out, I hope this works for you. You should see the output in Terminal say:

Running "concat:dist" (concat) task
File "../deploy/scripts/app.js" created.

Done, without errors.

You can download the example files for this tutorial here: