Tag: Grunt

It is now 2015 and with it a new version of Visual Studio that includes tools for Bower front end package management, Node Package Manager (NPM) and the Grunt JavaScript Task Runner. Not surprisingly, Microsoft has its own way of implementing Grunt, Bower and Node Modules in their upcoming Visual Studio debut. You don’t have to wait for Visual Studio 2015. Grunt, Bower, Node Modules and Bourbon can easily be included in a Visual Studio 2012 MVC 4 web application.

Install Sass

4. Node Package Manager (NPM)

Install Node.js

NPM is included with Node.js. The best way to install NPM is to install node. The easiest way to install Node.js for Windows is with the Windows Installer (.msi) avaialble here.

5. Bower

Use NPM to install Bower globally on your system.

Install Bower

# global bower install
npm install -g bower

Change to the directory where you app is located. For me this is:cd ‘~\Documents\Visual Studio 2012\Projects\MvcAppBourbon\MvcAppBourbon’

Install Bourbon

# bourbon install
bower install bourbon

Installed packages are located in the bower_components directory. This is created in the folder which the bower program was executed.

Install Bourbon Neat

Neat is a lightweight semantic grid framework for Sass and Bourbon.

# bourbon neat install
bower install neat

6. Bitters

Install Bourbon Bitters

Bitters jump start projects with a predefined set of basic Sass variables, default element style and project structure. Bitters are not installed with bower since the styles and variables are intended to be customized as needed. Change to the root directory of the app if not already there from bourbon install above. For me this is:cd ‘~\Documents\Visual Studio 2012\Projects\MvcAppBourbon\MvcAppBourbon’

7. Grunt

Install Grunt

Use NPM to install Grunt’s command line interface (CLI) globally on your system. Then use NPM init to create a package.json that stores node package data for the app. The third command to run, npm install grunt –save-dev installs the latest version of Grunt into the project and adds it to the package.json devDependencies. More info is avaialable here.

main.scss

Prior to making anymore Sass edits, in the CLI, load grunt to watch and compile changes.

Windows PowerShell – Grunt

Since we are using Neat, uncomment the grid-settings import in sass/base/_base.scss:

_base.scss

// Neat Settings -- uncomment if using Neat -- must be imported before Neat
@import "grid-settings";

After saving sass/main.scss, the running grunt tasks should should indicate that css/main.css has been written in the CLI and css/main.css should be updated to contain all of the base styles from the bitters import. Refresh Solution Explorer to see the new css.

Windows PowerShell – Grunt Compass

On the next page, controller, views and some Bourbon Refills added for demonstration.

This post shows how to combine and minify multiple javascript files in a WordPress theme into one javascript file. The benefit is a single request to a javascript file that has been compressed by minification instead of multiple request to larger javascript files.

package.json

The package.json file contains meta data about your app or module and it includes the list of dependencies to install from Node Package Manager (NPM) when running npm install. NPM is bundled with Node.js; if you have not done so already, install Node.js so you have it. Then create and save this file in your themes root directory, for example /wp-content/my-theme/package.json. Then when you run npm install, the package.json file is read and the respective node modules are installed. More information is available here.

file structure

Here is what the themes javascript file structure looks like for this example. The /js/src folder contains all of the individual javascript files for your theme. When you run grunt, these are all combined and minified into /js/main.js

Partial view of themes files showing location of javascript

functions.php

The functions.php file controls the loading of the themes javascript resources. In the functions.php file, the wp_enqueue_script() function links the script to the page. The pre-existing wp_enqueue_script() function calls are no longer valid since the javascript files have been moved to the /js/src/ folder. Here is an example of the code from the pre-existing functions.php that was linking the scripts:

Here is an example of the code from functions.php after making the changes to link /js/main.js instead. Since /js/src/deflist.js depends on jQuery, so does /js/main.js and the $deps array parameter is set to ‘jquery’. For more information, refer to the wp_enqueue_script function reference

Resources

This post is not about a barrel-aged distilled spirit made primarily from corn. Instead, it is about a Sass mixin library. To add Bourbon to your web project, visit the Bourbon GitHub repo and take a look at the requirements.

The first requirement is obviously Sass, since this is a mixin library for it. As of this post, the latest Bourbon requires Sass 3.3+. To install or update Sass you will need to have Ruby installed. Ruby comes pre-installed on OS X. For Windows, you can use the RubyInstaller for Windows. When I set this up last year, I used the Ruby 1.9.3 installers. These next step are performed using a CLI. Git for Windows provides a BASH emulation that you can use instead of the Command Prompt.

Option 2

A good alternative is to use Bower to install Bourbon and manage packages for your project. You will need to have the Node Package Manger (NPM) which is bundled with Node.js. If you have not done so already, install Node.js. Then, use the NPM to install Bower

# global bower install
$ npm install -g bower

Next, using bower init, generate a bower.json file for your project. You will be prompted for answers to generate the file. Answering each is up to you, accept the defaults by selecting enter. After the bower.json file is created in your project, install Bourbon using bower install –save bourbon:

Using Bourbon

Now we can create a Sass file and test drive some Bourbon mixins. Create a folder named sass in your web project root. And in that folder create a main.scss file with the code/text editor of your choice. Add the following Sass code to your new main.scss file and save it. NOTE: if you used option 1 to install Bourbon, adjust your import path as needed since /bower_components unavailable.

Setup sass to compile main.scss automatically

From within your projects sass folder, execute the sass watch command. Whenever your main.scss file is saved, the respective main.css will be written with all of the applicable browser extensions, reusable properties, etc..

UPDATE – Bourbon 4.1 path changes **

main.scss

** Bourbon 4.1.0 released on December 30, 2014
For Bower users, the Bourbon’s directory structure has been changed. Instead of a dist directory, which was just a duplicate of the entire Bourbon library for Bower to use, now point Bower to app/assets/stylesheets.

Bitters is a scaffold of scss files to get you started, add to or edit them as needed. Since we are using Neat, uncomment the grid-settings import in base/_base.scss:

_base.scss

// Neat Settings -- uncomment if using Neat -- must be imported before Neat
@import "grid-settings";

After saving sass/main.scss, per the running grunt tasks the terminal output should indicate that css/main.css has been written. css/main.css should be updated to contain all of the base styles from the bitters import.

This tutorial covers using Git to clone, branch and merge the latest Bootstrap source code, modifying and compiling your modifications to the source LESS variables using Grunt and viewing your compiled changes with a local Node.js web server.

You could just use the Bootstrap customize and download form to customize the LESS variables and download a pre-compiled Bootstrap package. However, as of this writing, the user interface at the form doesn’t provide a preview option to monitor your changes before you download the package. And since the Bootstrap version 3 source now includes Grunt, we can use it to compile the LESS source and preview the changes via localhost.

Source Code

Using Git, clone the Bootstrap repository. To keep our changes to the source separate and to make upgrading the bootstrap source easier, create a develop branch.

Load a Bootstrap example

I like to use the Node.js web-server.js that is bundled with the AngularJS tutorial. For example, here is how I start the NodeJs web-server.js that is included in the angular-phonecat repository on GitHub. This example presumes your CLI is in the bootstrap directory and the angular-phonecat repository is cloned to its own directory one level up.

UPDATED 1/4/2014

Repository contents rearranged over the holidays and the examples have been moved to the docs folder. You can always take a look at the latest source on GitHaub.

Modify LESS variables

Open the bootstrap/less/variables.less file in a text editor and find the @navbar-inverse-color and @navbar-inverse-link-color variables and change their values from @gray-light to @gray-lighter. Also, find @navbar-inverse-bg and change its value to #FF8C00.

Install node modules and compile LESS

The Bootstrap source contains a package.json for node module installation and a fully configured gruntfile.js to run Grunt tasks.

Open another bash window CLI and navigate to the bootstrap directory to install the node modules. After the node modules are installed, run the Grunt dist-css task which compiles the less files to dist/css/ followed by task dist-docs which copies the css files created in the previous task to docs/dist/css/.

This tutorial describes how to setup and use the Grunt JavaScript task runner to automate repetitive tasks such as minification and compilation. Grunt is installed using npm, the Node.js package manager. You will also need Git to work with the tagged source code. This makes it easy to reset and compare your working copy of the code at each step. I discovered commit tags while using the AngularJS tutorial.

If you have not done so already, make sure that you have Node.js, Grunt CLI and Git installed. For Windows systems, after installing Git, you may decide to use the Git bash shell for your CLI (command line interface) instead of the Command Prompt.

Install Grunt’s command line interface (CLI) globally.

#install grunt CLI
$ npm install -g grunt-cli

Source Code

Using Git, clone the GruntTutorial repository. This contains all the source code for the tutorial. As you work through the tutorial, you will be instructed to use git to reset the source code so it matches the step at that point. This will revert the source code to it’s original state for the respective tag and thus overwrite any changes you have made to it.

GruntTutorial – bash

Step 2: Combine and Minify Javascript files

# reset to step 2
$ git checkout -f step-02

Gruntfile.js is added to root of the project to specify the modules configuration, define tasks and load plugins. This Gruntfile.js specifies an uglify plugin to perform JavaScript minification. The banner option creates a comment on the first line of the minified file that is output. The JavaScript source (src) and destination (dest) paths are set in the build properties. Since our build source path has a wildcard * before the js filename extension, all of the js files in that directory will be minified into a single JavaScript file named grunt-tutorial.min.js as specified in the build destination property.

For the Sass compile with the Compass & Watch Grunt plugins, you will need to have the RubyInstaller for Windows. As of this writing, use Ruby 1.9.3 installers. These provide a stable language and a extensive list of packages (gems) that are compatible and updated. During the setup, check the option to Add Ruby executables to your PATH. After installing Ruby, install Sass and Compass using the Start Command Prompt with Ruby.

Start Command Prompt with Ruby

Install compass and watch Grunt plugins

By running these npm install commands with –save-dev, the package.json file will automatically be updated to include these two new dependencies.

Edit and save one of the Sass (.scss) files. The watch task waits for changes to files and then fires a task. In our Gruntfile, the watch is configured to run the the compass task whenever a .scss file is updated. The compass task is configured to compile the Sass files specified in the sassDir property (src/sass/) and output to the cssDir specified (build/css/).