ServiceComposer

End-User Service Compositions in the Internet of Things

Installation Guide

Note: Most of the actions will be performed via the console/command-line/terminal. You should be familiar with opening the console, traversing directories and running commands. If a command is failing try to run it as an administrator. To do this on Mac start the command with sudo.

Components

• Grunt is the tool that does the dirty work for you. Compiling LESS files, concatenating and minifying JavaScript files, error checking and much more.

• NPM, the Node Package Manager, is used to search, install and uninstall Grunt plugins.

• Bower is used to search for, install and uninstall JavaScript and LESS/CSS frameworks and libraries used in front-end development (like jQuery, modernizr, HTML5shiv etc.).

Initial setup

Windows users: Download and install git. Pick "Use Git from the Windows Command Prompt" during install! To check whether it's installed properly open a command line window and type git.

• Download and install Node.js

• Install Grunt (npm install -g grunt-cli)

• Install Bower (npm install -g bower)

• Install the required Grunt plugins with npm install. If this fails run the command as an administrator.

• Install the required Bower plugins with bower install

• Run grunt dev to start working on the project

Working with Grunt.js

To run a task use grunt [task name]. There are two default tasks available - dev and dist. They will be explained in the following.

grunt dev: Development

The task used during development is called 'dev'. Run it with grunt dev. It starts a static web-server with auto-reload enabled, compiles React files to JavaScript, compiles LESS files into CSS and checks JavaScript files for errors using JSHint.

Once the task is running the page can be accessed via 'http://localhost:8080'

grunt dist: Building a distribution ready version of the project

The task used to create a deployable version of the project is called 'dist'. Run it with grunt dist. It will export to the dist repository.

What it does:

• JavaScript-files get concatenated and minified using r.js, creating one file that contains all the code. The require.js library is being replaced with almond, a minimal module loader that only contains the code necessary in production.
• The <script>-tag in the index.html is updated to include the generated main.min.js file.
• CSS gets automatically processed to include all currently necessary vendor-prefixes (i.e. -webkit-).

Adding JavaScript and CSS libraries

Plugins, libraries and frameworks can either be installed using Bower or by hand. To check whether a package is available on Bower check the Bower website or use bower search [package name]. If it's not available you have to install it by hand.

• Install Bower packages via bower install [package name] --save. The optional parameter --save tells Bower to save the package as a dependency of the project.
• Bower packages are only downloaded and placed in the bower_components-folder. To learn how to include them in your project check the next chapter.

For further information consult the Bower website.

Note: Bower packages should never be committed to version control, which is why their directories are excluded by the .gitignore.

Including packages

JavaScript libraries have to be added to the require.js-config file, which can usually be found at js/main.js (link). To use it wrap your code in a require-block (link) or define a RequireJS/AMD-module (link). Reference either the source file in the bower_components directory or the js/vendor directory, depending on where you got it from.

For a more comprehensive introduction to RequireJS check out the API docs.

LESS/CSS libraries should be imported in the style.less file via @import (inline) "[path]/[to]/[package].css" (in case of LESS-files (inline) can be omitted). Reference either the source file in the bower_components directory or the less/vendor directory, depending on where you got it from.

Bootstrap components

Bootstrap is always installed. However, to use it the required components have to be referenced in the less/style.less-file, so they will be compiled into CSS. The location of the components is bower_components/bootstrap/less. You can find a list of all components on the Bootstrap website. Bootstrap variables, normalize and mixins are added as a standard feature.

To use Bootstrap's variables you have to add your own variables.less-file and override the desired variables.

Adding your own tasks to Grunt

To add your own tasks to Grunt you have to install the desired Grunt plugin with NPM and configure it with the Gruntfile.js.

• Find available Grunt plugins here. Plugins with the contrib- prefix are maintained by the Grunt team.
• Install Grunt-plugins via npm install [plugin name] --save-dev. The optional parameter --save-dev tells NPM to save the plugin as a dependency of the project. The plugins are being installed into the node_modules-folder
• Make the plugin available in your Gruntfile via grunt.loadNpmTasks('[plugin name]')
• Consult the plugin's website for usage instructions

For further information consult the Grunt website.

Note: Grunt plugins should never be committed to version control, which is why their directories are excluded by the .gitignore.