See other posts on ‘Branding SharePoint sites with yeoman’
- Yeoman the web development workflow
- An Introduction to Jade
- An Introduction to CoffeeScript
- An Introduction to SASS
- Our yeoman generators
- Hands On – Let’s create a custom MasterPage
- Hands On – Let’s create a custom PageLayout
- A forecast – What are we currently working on
Through all articles you’ll see screenshots and commands which I use to get things up and running or to achieve several requirements. I’m doing all my development stuff on a Mac, so don’t be confused everything will also work on Windows. (Of course I’ve a virtualized Windows to do my regular SharePoint development…)
Yeoman is built on top of Node.JS and uses Git for managing dependencies and loading packages from the web. If you’d like to use Compass within your projects you’ve also to install Ruby and Compass on your development machine. We’re using Compass within out SharePoint related generators, so the final list of dependencies looks like this
- Node.JS (http://nodejs.org)
- Git (http://git-scm.com)
- Ruby (http://ruby-lang.org)
- Compass (http://compass-style.org)
See detailed installation documentations linked behind the dependencies.
Installing yeoman itself is straight forward. Yeoman is available as Node-Package and can easily be installed by using npm. By executing the following command, yeoman will be installed on your system
$ npm install –g yo
When the installation process is finished you’ve successfully installed yeoman with all it’s required tools. So let’s move on and install some yeoman generators.
Yeoman Generators – The heart of yeoman
As described within the introduction post, yo is a simple scaffolding tool that is responsible for creating the app structure and providing pre-configured files in order to get started with development in no time.
Because almost every project is different from another, yeoman uses generators to describe how a new project will look like.
Most generators are also available as NPM package and can be installed by using the
npm command. Before I’ll install a new generator it’s a good point to get an overview of which generators are currently available.
npm search generator-* you can get a list of all yeoman generators available through NPM, alternatively you can browse the list on yeoman’s homepage at http://yeoman.io/community-generators.html
Let’s install the most simple generator right now by executing
$ npm install –g generator-webapp
Create your first project with yeoman
Creating projects using yeoman is straight forward. You just have to create a new folder and execute
followed by the generator you would like to use.
Alternatively you can just execute yo and yeoman will ask you for a generator based on all installed generators. Depending on the generator you’ve chosen yeoman will ask you some questions about your project. In this example yeoman is asking which dependencies you want to add directly to the new project. After selecting for example Bootstrap you’ll see the yeoman magic. Yeoman will dump the project structure and install various dependencies from the web using npm and bower. After downloading the dependencies has finished, it’ll execute the generated Gruntfile in order to ‘build’ your web-app. (Don’t care about all details now, we’ll go through them later)
That’s it now your first project has been created by using yeoman. But what do we get? Let’s have a closer look to the project directory.
As you can see there are several files and folders created by yeoman. Most important artefacts are
package.json– This file describes your project and lists all Node.JS dependencies such as grunt, various grunt tasks
bower.json– This file is used to manage client-side dependencies and tells bower which libraries it has to install (jQuery, bootstrap, …)
gruntfile.js– The Gruntfile describes what grunt should do during ‘compilation’ of the project. Depending on the generator you’ve chosen the file may be existing as CoffeeScript file with the name Gruntfile.coffee
testfolder – Put your unit-tests right here
bower_componentsfolder – Bower installs your dependencies right here (will not be stored in git)
node_modulesfolder – NPM installs your dependencies right here (will not be stored in git)
Building the project
In order to build your project you’ve just to execute
$ grunt build
within the project folder and grunt is going to execute the tasks described in your Gruntfile. As a result you’ll recognize a new subfolder called dist. Within the dist folder everything is placed that your app requires to run.
Executing the project
There is also a grunt task for running a small webserver serving your project. You just have to execute the command
$ grunt server
As you may realize the process stays active and in the background it’s watching to your source directory!! This is a pretty cool and perhaps the most boosting feature. You can now change the HTML of your website and the files will be compile in the background and you’ll get really fast feedback and you can directly see the results in the browser.
Executing the unit tests
Unit-Testing is built in, so execution is also straight forward. You just have to
$ grunt test
and grunt will explicitly run all tests in your project.
What’s going on behind the scenes
Right now you should have a rough understanding of what yeoman is offering. You’ve seen how to create a new project and how to build it, how to execute your tests and how to start your project by using grunt. Playing around within your sources and see the changes directly in the browser has also been described in ‘Executing the project’ section. But now it’s time to see what’s actually going on. The simple web-app generator generates a both
gruntfile.js. In order to understand the insights these are the most important files.
First see the list of
devDependencies in the
package.json file. By examining this list you can understand which tasks are executed when you fire-up grunt build for example. Several tasks such as minifying your images, CSS and HTML are described here. You may also notice the
grunt-contrib-compass reference which will be used to control the powerful compass command directly from your Gruntfile.
Understanding each task may take a while. Therefor you should learn more about GruntJS and the Gruntfile. The GruntJS website offers a good documentation and it’s also important to browse the git repositories from all community tasks in order to see how these tasks can be configured.
When you open up
The copy task configuration
copy: in your Gruntfile and you should find the following part
As you can see is each task configured by using a simple JSON object. The complexity of the various tasks differ depending on their level of configuration, but hey JSON is super readable. Don’t be afraid :)
The copy-task actually has two sub-tasks (
styles). The generator requires two sub-tasks here because other tasks such as
cssmin require to do some further actions with the style sheets. The most complex properties are file-system related. GruntJS offers a great set of wildcard filters in order to select the files you’re interested in from the file system.
dist sub-task is going to copy all files that match the source pattern (
src) from the current working directory (
cwd) and will copy them into the given destination (
dest). The expand property is a special property! By setting it to true, you tell the engine that it should build the array of files dynamically instead of defining the files manually. The engine is going to use the combination of all other properties (src, dest, cwd,…).
As you can see, grunt-tasks are very flexible and provide solutions for almost every scenario. For Further details see the grunt documentation on http://gruntjs.com or the specific documentation on the grunt-task you’re currently working on. (Almost every grunt task is hosted on github hooray)
Depending on the chosen generator you may have different command line options when executing grunt. These options are also configured within the Gruntfile. The following screenshot shows the “test” and “build” option for the grunt executable. As you can see the option is defined followed by all dependent grunt-tasks that will be invoked in the given order. By using grunt.registerTask you can easily create your own CLI or tweak the current configuration. For example you can easily enable the CoffeeScript compiler by adding the grunt-contrib-coffee package to the project, configure the task as shown with the ‘copy’-task and put it right here in the dependency list.
Installing a package such as
grunt-contrib-coffee is straight forward. Just open a terminal and navigate to the project directory. By executing
$ npm install grunt-contrib-coffee --save-dev
the package will be installed and added as development dependency (see
package.json). Because yeoman is using a package called
load-grunt-tasks it’s automatically loaded and available for configuration and execution within the Gruntfile.
Yeoman brings really powerful operations for each developer and it’s great to see how fast you can develop frontend-apps with the yeoman stack. I think you get a rough introduction into the topic with this post. Don’t worry if you don’t understand all insights of yeoman yet. The easiest way of learning the yeoman insights is to start at this point and tweak the Gruntfile in order to fit your needs. Of course it’s difficult if you come from standard SharePoint development. But with the rise of the AppModel we’re finally back to good old web development. Therefor it’s time to catch up the latest tools and workflows in order to increase the productivity and make SharePoint Apps and customizations popping up quickly.
Within the upcoming posts we move on with some programming languages and frameworks we’ve backed into our development stack. So keep on reading and hopefully you’ll leave your thoughts right here as comment.