###Getting Started (new projects only)
- Create a new empty repository. The location of this repo will be provided to you by your project manager.
- Clone the repository to your local machine.
- Download the seed project.
- Extract the seed project into the repo on your computer
- Run through the setup process below.
- Commit files to repo.
###Quick Setup
If you don't want to use the guide for the setup, just run the following command lines from your terminal:
> npm install
> node setup
> bower install hammer-essentials
> grunt sandbox
Some projects may require additional components, refer to the documentation provided in each repo's README.md.
###Setup
This will guide you through the setup process and explain in detail. To get started with Hammer seed run the following command lines from your terminal:
> npm install
npm install - Installs node modules into the "node_modules" directory. Hammer will access these modules as additional JavaScript libraries and grunt tasks for compiling for distribution, sandbox and final builds.
> node setup
node setup - Runs a wizard that may or may not do the following based on your answers:
####Project name?
This is a unique name for the project. It may represent an exam, tutorial, simulation, etc. For example: "office2016", "ic3", "dreamweaver10", etc.
If you are building widgets for a package or for within the exam, you may want to use the project name as your "namespace" for your widgets to keep them from conflicting with other packages.
Example
Declaring a widget with name
widget('flashTimeline', function(){...});Consuming a widget with name
<flash:timeline></flash:timeline>####Project description?
An optional block of text that describes the project.
####Project repo url?
This should be a valid GIT repository. The path should end with ".git". Example: https://devops-tools.pearson.com/stash/scm/hammer-pkg/adobe-flash.git
####Ignore build directory? If you say "yes"...
The ".gitignore" file will be modified to include "build" to the ignore list. Project that are going to act as stand-alone packages should not include the "build" directory in their commits.
####Would you like to include "sandbox" example files? If you say "yes"...
Several files and directories used during the development stage of your exam or package will be injected into the "sandbox" directory. This is a fast way to get started as it creates the basic folder structure you need for organizing an exam or your testing environment for package creation.
####Would you like to include "package" example files? If you say "yes"...
The "src" directory will be injected with seed files to get you started with creating your own package. These are there to help you get an idea on how to setup your package. The grunt task for compiling a package is already set up. If you keep to this structure, all you have to do is create your widgets and compile. If you are a more experienced developer with Grunt, feel free to go into the Gruntfile.js and make additional modifications.
####Would you like to remove the setup files?
This is cleanup that will occur at the end of the setup. It will remove the "setup" directory from the project. The default is "Yes".
###Installing Hammer packages
> bower install hammer-essentials --save
This will install common Hammer packages (in the "bower_components" dir) used by most projects. The "hammer-essentials" component is nothing more than a reference to other hammer packages. It make it an easy way to setup all the dependencies with a single install.
The --save adds "hammer-essentials" to "bower.json" as a dependency.
Other packages are available, go to Hammer in stash to see other packages that are available. In addition to these packages, there are custom packages created by other development teams. Each should have a "README" so you can know what each contains.
###Compiling your code
Hammer uses Grunt (a node task module) to compile the code for testing and delivery. There are different ways to compile your code.
Before you launch your project in the browser, be sure to run
> grunt sandbox
Below is an explanation of each of the default tasks provided by Hammer.
Compile a package for distribution This task compile the code in the "src" directory into the "dist" directory. This is only needed if you are using this project to as a package (common library) to be used by other projects.
> grunt
Compile code for testing in the sandbox This task will compile the code in the "src" directory into the "sandbox" directory for testing.
> grunt sandbox
Compile code for a release This task will compile the code in the "src" directory and the "sandbox" directory into the "build" directory in a minified state. The build is what you use to distribute an exam.
> grunt build
Compiles all the above
> grunt all
Run Unit tests
> grunt test
###Running your project in the browser
While Chrome is the official browser used for testing and delivery, all hammer packages should work in any modern browser (IE 10+, Firefox, Safari, Chrome).
Instructions for WebStorm editor
You can run your project directly from WebStorm or PhpStorm. Right-click the HTML file in "sandbox/index.html" and select "Open in Browser" under the menu options.
Instructions for other editors
If you are using another editor such as Atom, Sublime or other, all you need to do is launch the local node server from your project directory
> node server
Open the Chrome browser and navigate to the url and port printed in the terminal.
If you find that you need to run on a different port you can add the argument...
node server --port PORT_NUMBER
###Registering package
These are instructions for distributing a package to be consumed by other projects. Hammer uses bower to distribute components. Bower is a package manager for Javascript libraries that allows you to define, version, and retrieve your dependencies.
To register from the terminal:
> bower register COMPONENT_NAME GIT_URL
Example
> bower register hammer-application https://devops-tools.pearson.com/stash/scm/hammer/hammer-application.git
###Bumping versions
Versioning your project bump the version number, commit modified files containing version numbers (package.json, bower.json, README.md) and tag your project in its current state.
For a fix version (most common):
> grunt bump
For a minor version:
> grunt bump:minor
For a major version:
> grunt bump:major
For more info on "grunt bump" go to: https://github.com/vojtajina/grunt-bump
###Install grunt and grunt tasks
> npm install
###Install bower dependencies
> bower install
###Create your first build
> grunt
###What did we just build?
You will see a new directory "dist" was created. It contains a build version of the contents found in the "src" directory. A package will contain the following files for distribution.
- A package.json file. These are instructions used by Hammer to load and configure this module and its dependencies.
- An unminified version of your compiled source code.
- A minified version of your compiled source code.
- A map file.
Alternatively you may also have
- A style.css file containing custom css for components in your package.
- A template.js file containing HTML templates compiled into a single JS file.
- A vendor directory containing 3rd-party libraries used by your package.
The Gruntfile.js is designed to work with little need for modifications. However if you are comfortable with Grunt and Gruntfile configurations, feel free to make changes.
###A look at the "src" directory
The boilerplate "src" directory provides and example on how you will most likely organize your package.
- scripts: contains an entry point for your package and other utility directives that may be required.
- vendor: contains 3rd-party libraries that may be required to use the package. These libraries will not be compiled during the build.
- widgets: a widget directory can consist of HTML templates, JavaScript code and CSS in the form of LESS files. It is meant to act as a unit and the build knows how to compile each of these parts so they are included.
###Preventing errors
There are three ways to prevent errors in your code:
- JSHint (testing syntax)
- Unit Tests (testing functionality)
- End-to-end (E2E) (testing user interaction)
The first two can be done during the build, and should be used during your development process. The third we will go over later.
###Unit and E2E Testing
Hammer uses Jasmine and Protractor for testing. The seed provides an initial setup of each. Tests should be placed in the "tests" directory. You will find two subdirectories: "unit" and "e2e".
To learn how to create unit tests with Jasmine read visit: http://jasmine.github.io/2.3/introduction.html
Looking at other Hammer packages will also provide you examples on how to setup tests. Some good examples can be found in "hammer-framework", "hammer-application", and "hammer-debug".
####Running Unit Tests
As stated above, Jasmine is the platform used for running unit tests. You can run the tests in the browser or in the console.
Running tests in browser through WebStorm
You can run your project directly from WebStorm or PhpStorm. Right-click the HTML file in "tests/unit/spec_runner.html" and select "Open in Browser" under the menu options.
Running tests in a browser with local server
If you are using another editor such as Atom, Sublime or other, all you need to do is launch the local node server from your project directory
> node server
Open a browser and navigate to the url and port printed in the terminal.
http://localhost:32002/tests/unit/spec_runner.html
If you find that you need to run on a different port you can add the argument...
node server --port PORT_NUMBER
Running tests in a console
To run in a console (or terminal), start the local node server (as explained above).
> grunt jasmine
####Running E2E Tests
As stated above, Protractor is the platform used for running e2e tests.
Setup Protractor
Protractor explains the setup on their site http://www.protractortest.org
Running e2e tests
Start the webdriver manager
> webdriver-manager start
Run protractor
> protractor tests/e2e/conf.js
There are some examples and additional functionality provided.
waitForAngular(val:Boolean):void - Indicates whether or not to have protractor wait for the Angular bootstrap to initialize before any operations are performed.
takeScreenshot([name:String]):void - Takes a screenshot of the current contents of the test window. The screenshot will be saved in the "tests/screenshots" directory.
####Coming in 2016
We are currently working on an environment that will allow you to record and playback your interactions. We are working on creating an export option to Protractor, making it easier and faster to create tests for the e2e environment.