Transforms text to colors
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
controllers
lib
public
test
views
.bowerrc
.gitignore
.jshintrc
Gruntfile.js
README.md
app.js
bower.json
package.json

README.md

colors

Transforms text to colors, like magic.

Overview

This application contains a single page which has a form that accepts text input. When submitted, each character within the text is transformed into a color, and the resulting set of colors is displayed below the form. A sample screen shot is shown below:

Though the concept of the project is simple, it's meant to illustrate a basic example of using Node.js and Express on the server side, and AngularJS on the client side. The original idea came from a MakerSquare project.

Getting Started

This is a Node.js project, so before cloning the repository make sure node is installed. Once cloned, install the node dependencies by issuing the following command (from the project root directory):

$ npm install

Bower is used to manage client side dependencies. If bower is not yet installed, execute the following command to install bower:

$ npm install -g bower

Once installed, you can use bower to install the bower dependencies (from the project root directory):

$ bower install

With the dependencies installed, you can start the application by executing the following command (from the project root directory):

$ npm start

This command is setup to use nodemon to watch for any file changes, and automatically restart the application.

By default the application will run on port 3000, so once it's started, browse to http://localhost:3000/ to view the application.

Project Structure

Server Side

On the server side, the app.js file is the starting point. This file sets up the Express server to properly render the initial page, along with loading all the controllers. It also hosts static assets on /public (these are the client side files).

In the controllers directory two controllers exist. The colors.js controller is responsible for rendering the initial view, and the letters-to-colors.js controller is our single API. This API accepts text input and responds with a set of colors to render on the page.

The views directory contains a single view. This view is initially rendered on the first request, and is responsible for loading up Angular along with the client side files (including CSS and JS files).

Finally, the node_modules directory is dynamically created when installing node packages (dependencies) for this project. This is not committed to source control since it's generated during setup. Dependencies, along with general project information is contained within the package.json file.

Client Side

The public directory contains all client side code. Similarly to the server side of things, the client side has dependencies which are installed to the public/bower_components directory. Again, here this directory is not committed to source control. Bower configuration, which details the dependencies and project setup, is contained within the bower.json and the .bowerrc configuration files.

The public/js directory contains the logic necessary to run the client side of the application. The public/js/app.js file defines the Angular modules for the app, along with the routes. The public/js/controllers directory has the only controller for the application: ColorsCtrl. This controller handles user interaction within the page. The LettersToColorsService which is contained within the public/js/services/letters-to-colors-server.js file, is responsible for sending and receiving data from the server side API.

Angular is initialized within the views/colors.html file, and it's within this file that the Angular application is defined, and the controller logic gets control over an element within the page. Comments within the code should help in understanding the specifics.

Finally, any HTML partials are defined in the public/partials directory (these partials are used by the controllers), and CSS is in the public/css directory.

Tests

Within this project exists both server side tests and client side tests. Both the server side and client side tests use Jasmine, but they use different frameworks to run the tests.

Setup

The devDependencies within the package.json file contain the test dependencies. These will be installed when running npm install which should be done as part of the project setup.

In addition to the dependencies listed in the package.json, two more setup steps must be executed to take advantage of all tests. Grunt is used to run both server side and client side tests at once. If the command line grunt executable is not already installed on the system, execute the following command:

npm install -g grunt-cli

Protractor uses the Selenium server to interact with the browser. To setup the webdriver, execute the following command:

npm run update-webdriver

Note that both of these commands only need to be executed once per setup.

In addition to the above steps, Protractor expects the web application to be running when it executes the tests. So prior to running the tests, start the web app by executing the following command:

npm start

Run Tests

Grunt is used to execute the tests. There are multiple tasks available to run the tests:

  • grunt - The default task executes jshint, Jasmine for server side tests, Karma and Protractor for client side tests. This task is meant to run all the tests just once.
  • grunt w - This task runs the same set of commands as the default task but does so in a "watch" mode. If any files change, the set of tasks will be (re)executed.
  • grunt ci - A continuous integration task which runs the same set of commands as the default task, but does so in a way suitable for a continuous integration environment (such as Travis-CI).

Tests Overview

Server Side

All tests for the server side components are contained within the test/server directory. These tests use Jasmine, but more specifically, jasmine-node which provides Jasmine tests within the Node environment. The tests are setup in directories which mirror the source code they are testing.

The tests utilize Jasmine's 1.3 release, for more information on the API for Jasmine 1.3, please consult the documentation.

Client Side

The client side tests are contained within the test/client directory. The tests are broken down into two categories:

  • Unit tests: These tests use Karma to run Jasmine tests. These tests run within the browser, and currently are configured to run under Chrome and Firefox. These tests exist in directories which mirror the source code they are testing.
  • End to end tests: These tests use Protractor to run Jasmine tests. Protractor uses the Selenium WebDriver to interact with the browser directly, navigating the pages of this application. The tests verify certain behavior as if the user was manually clicking around on the page. There is only one test which is meant to test this "Colors App".