<<<<<<< HEAD

OrderCloud Seed - AngularJS

A seed project for custom Four51 Solutions built on AngularJS

---

Get started

Node.js is required for the following node package manager (npm) tasks. If you don't have node.js installed, you can download it here.

Begin by downloading the necessary global node packages in your command line,

OrderCloud lets you decide between using Gulp or Grunt as its build system, so Node.js is required. While Gulp comes standard with a command-line utility, Grunt does not; and Karma and Bower must end up in your global path for the build system to find it, so Grunt, Karma, and Bower must be installed independently.

If you

$ npm -g install grunt-cli karma bower

Once this is complete, you will need to download your local node packages. This will begin by downloading the packages listed under 'devDependencies' in ~/package.json. Once the initial install is complete, you will see a prompt on your command line, asking to specify your task runner (gulp or grunt). Enter your preferred task runner, and the remaining dependencies will be downloaded.

$ npm install

Finally, run the following commands to install the necessary bower packages, and create the build folder. Make sure you run build with your selected task runner (you will receive an error if you try running it with the wrong one)

$ bower install
$
$ grunt build 
$ ....or....
$ gulp build

You should now have a few more directories in your project.

OrderCloud/
  |- build/
  |- node_modules/
  |- vendor/

REMAINING README NEEDS TO INCLUDE TASK RUNNER UPDATES

Configure WebStorm

WebStorm is our chosen development IDE. It provides an interface for the capabilities of the seed projects configuration.

Karma Unit Testing

Once you've installed the prerequisites and run your grunt build you can setup and run your Karma tests.

Create a Run configuration using the Karma plugin with the following settings:

Node interpreter: C:\Program Files (x86)\nodejs\node.exe

Karma package: C:\Four51\WebFiles\SPASites\defaults\OrderCloud\node_modules\karma

Configuration file: C:\Four51\WebFiles\SPASites\defaults\OrderCloud\build\karma-unit.js

Overall Directory Structure

At a high level, the structure looks roughly like this:

OrderCloud/
  |- karma/
  |- node_modules/
  |- src/
  |  |- app/
  |  |  |- <application code>
  |  |- assets/
  |  |  |- <static files>
  |  |- index.html
  |- vendor/
  |  |- <bower components>
  |- .bowerrc
  |- bower.json
  |- build.config.js
  |- Gruntfile.js || Gulpfile.js
  |- module.prefix
  |- module.suffix
  |- package.json

REMAINING README NEEDS TO INCLUDE TASK RUNNER UPDATES

Detailed Installation

This section provides a little more detailed understanding of what goes into getting OrderCloud up and running. Though OrderCloud is really simple to use, it might help to have an understanding of the tools involved here, like Node.js, Grunt or Gulp, and Bower. If you're completely new to highly organized, modern JavaScript development, take a few short minutes to read this overview of the tools before continuing with this section.

Here it is:

OrderCloud lets you decide between using Gulp or Grunt as its build system, so Node.js is required. While Gulp comes standard with a command-line utility, Grunt does not; and Karma and Bower must end up in your global path for the build system to find it, so Grunt, Karma, and Bower must be installed independently. Once you have Node.js installed, you can simply use npm to make it all happen:

If you chose Grunt, run this,

$ npm -g install grunt-cli karma bower

And if you chose Gulp, run this,

$ npm -g install karma bower

And then install the remaining build dependencies locally:

$ npm install

This will read the dependencies (empty by default) and the devDependencies (which contains our build requirements) from package.json and install everything needed into a folder called node_modules/.

There are many Bower packages used by OrderCloud, like AngularJS and the OrderCloud-SDK, which are listed in bower.js. To install them into the vendor/ directory, simply run:

$ bower install

In the future, should you want to add a new Bower package to your app, run the install command:

$ bower install packagename --save-dev

The --save-dev flag tells Bower to add the package at its current version to our project's bower.js file so should another developer download our application (or we download it from a different computer), we can simply run the bower install command as above and all our dependencies will be installed for us. Neat!

Technically, OrderCloud is now ready to go.

To ensure your setup works, launch grunt:

$ grunt watch

The built files are placed in the build/ directory by default. Open the build/index.html file in your browser and check it out! Because everything is compiled, no XHR requests are needed to retrieve templates, so until this needs to communicate with your backend there is no need to run it from a web server.

watch is actually an alias of the grunt-contrib-watch that will first run a partial build before watching for file changes. With this setup, any file that changes will trigger only those build tasks necessary to bring the app up to date. For example, when a template file changes, the templates are recompiled and concatenated, but when a test/spec file changes, only the tests are run. This allows the watch command to complete in a fraction of the time it would ordinarily take.

When you're ready to push your app into production, just run the compile command:

$ grunt compile

This will concatenate and minify your sources and place them by default into the compile/ directory. There will only be three files (excluding assets): index.html, OrderCloud.js, and OrderCloud.css. All of the vendor dependencies like AngularJS styles and the OrderCloud-SDK itself have been added to them for super-easy deploying. If you use any assets (src/assets/) then they will be copied to compile/ as is.

Lastly, a complete build is always available by simply running the default task, which runs build and then compile:

$ grunt

The Build System

The best way to learn about the build system is by familiarizing yourself with Grunt and then reading through the heavily documented build script, Gruntfile.js. But you don't need to do that to be very productive with OrderCloud. What follows in this section is a quick introduction to the tasks provided and should be plenty to get you started.

The driver of the process is the delta multi-task, which watches for file changes using grunt-contrib-watch and executes one of nine tasks when a file changes:

• delta:gruntfile - When Gruntfile.js changes, this task runs the linter (jshint) on that one file and reloads the configuration.
• delta:assets - When any file within src/assets/ changes, all asset files are copied to build/assets/.
• delta:html - When src/index.html changes, it is compiled as a Grunt template, so script names, etc., are dynamically replaced with the correct values configured dynamically by Grunt.
• delta:less - When any *.less file within src/ changes, the temp/imports.less file is regenerated by the less_imports:build task, autoprefixed, and compiled into build/assets/OrderCloud.css.
• delta:jssrc - When any JavaScript file within src/ that does not end in .spec.js changes, all JavaScript sources are linted, all unit tests are run, and the all source files are re-copied to build/src. build/src in a structure mirroring where they were in src/ so it's easy to locate problems.
• delta:tpls - When any *.tpl.html file within src/ changes, all templates are put into strings in a JavaScript file that will add the template to AngularJS's $templateCache so template file is part of the initial JavaScript payload and do not require any future XHR. The template cache file is build/template-app.js.
• delta:jsunit - When any *.spec.js file in src/ changes, the test files are linted and the unit tests are executed.

As covered in the previous section, grunt watch will execute a full build up-front and then run any of the aforementioned delta:* tasks as needed to ensure the fastest possible build. So whenever you're working on your project, start with:

$ grunt watch

And everything will be done automatically!

Build vs. Compile

To make the build even faster, tasks are placed into two categories: build and compile. The build tasks (like those we've been discussing) are the minimal tasks required to run your app during development.

Compile tasks, however, get your app ready for production. The compile tasks include concatenation, minification, compression, etc. These tasks take a little bit longer to run and are not at all necessary for development so are not called automatically during build or watch.

To initiate a full compile, you simply run the default task:

$ grunt

This will perform a build and then a compile. The compiled site is located in compile/. To test that your full site works as expected, open the compile/index.html file in your browser. Voila!

ng-sdk-test

8ea59fccaea3a943846a24c14f21a3800a34cf2b