README
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 sourcetest
contains unit tests for this old Javascriptassets
contains assets used by old Javascriptts
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 usinghyphen-case
- files inside should be named usingUpperCamelCase
- 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 itctrl
) 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).