Quote & Switch Front End

A single page application, built on AngularJS

Installation

Make sure you have Node and Yarn installed, and then run

npm login
yarn login
yarn install

Note: if you have previously had a js-qs installation on your machine before, you will need to clear your NPM and Yarn cache before running the commands above. You can do so by running:

npm cache clear
yarn cache clear

If you are getting permission errors when trying to pull private packages (i.e. ovo-bootstrap), run the following command:

npm config set always-auth true

If you are loggen in, set the always-auth to true and still getting permission errors try removing the registry setting from your .npmrc file

Project Dependencies

The project uses Yarn to manage dependencies. Yarn sits on top of NPM and offers advantages such as smart caching and better dependency resolution, as well as maintaining a lockfile in the root of the repository to track these dependencies. Do not make any modifications to the lockfile in any circumstance as this is automatically generated and maintained by Yarn.

To add a dependency to the project, run yarn add <dependencyName>. As an example, to add dependency foo to the project, run:

yarn add foo

To add a dev dependency, run yarn add with the --dev flag. As an example, to add dependency foo to the project as a dev dependency, run:

yarn add foo --dev

It is important to add dependencies to the project using Yarn and not NPM, otherwise the Yarn lockfile will not be updated.

Quick Start

To run the server in development mode:

yarn start

Structure

Currently this application is undergoing a refactor to use Typescript. Until that is complete the application has quite a complicated structure:

• src contains the old Javascript source
• test contains unit tests for this old Javascript
• assets contains assets used by old Javascript
• ts contains new Typescript source, with unit tests and assets

The application currently uses NPM, Grunt, Webpack, Karma and Mocha. The aim is to remove Grunt completely, and all new code in ts should have no dependency on Grunt.

This is all achieved using two separate angular modules. The old module is ovo.qs and its entry point is in src/main.js. This old module is wired together using angular for dependency injection within each JS file.

The new module is simply called qs - it depends on the first module, and its entry point is in ts/app.ts. Whilst this module still uses angular DI, we use ES6 imports/exports with Webpack for wiring.

Tests in the ovo.qs module use Karma and Jasmine (they run in a headless browser using PhantomJs) and have the format *.spec.js; tests in the qs module use Mocha directly (no browser, they run in node) and have the format *.test.ts.

There is a third module qs.demo which is used only when running this project locally, to set up canned API responses using angular multimocks. Its entry point is in ts/demo.ts and this is imported in the demo index.html. (When this application is actually deployed, the index.html file is generated dynamically by public-api-qs and this static index page is excluded from the build)

Testing

To run the tests:

yarn test

A Wallaby.js config file is available for this project. If your editor has the Wallaby plugin, you can use this config file and receive realtime feedback of your tests inside your editor.

Routing

The application uses ui-router for client side routing. The routes (or states) are configured in ts/app.states.ts and src/init/routes.js

Style guide

• Prefer Typescript over Javascript, and use classes for services, controllers etc.
• Folder per route in ts named using hyphen-case - files inside should be named using UpperCamelCase
• API calls should be encapsulated in ts/common/clients - these should be stateless and logicless ideally
• Common business logic should go in ts/common/services and these classes may be stateful
• Common directives should go in ts/common/components
• Document common directives in the wiki
• Use controllerAs (name it ctrl) where possible in directives, and avoid $scope
• Keep the angular global object away from classes - DI construction should happen in ts/app.ts only

Contributing to the project

All code contributed to the project should be submitted via PR. We have a PR template that should be filled out for everything that is applicable (i.e. some changes won't have applicable screenshots, but some will).