Augustus

Augustus is a front-end application for beta.parliament.uk. It's built on Shunter, with our components library Pugin.

Contents

• Requirements
• Quick start
• Running the application
• Using components
• Starting Augustus and Shunter serve in a Docker Image
• Running tests on single files or directories
• i18next Note
  • Double moustaches
  • Prefixing the variable name with a hyphen
• Contributing
• License

Requirements

Augustus requires the following:

• NodeJS - click here for the exact version
• NPM

Quick start

git clone https://github.com/ukparliament/augustus.git
cd augustus
npm install
npm cache clean --force && npm test

Running the application

To run the application locally using example data, open 2 terminal shells. In one run:

npm cache clean --force && node app.js

To run the app.

In the other shell run:

node_modules/.bin/shunter-serve

To run the shunter serve.

If you wish to use live data you will need to have a JSON feed coming into port 5401.

The application should now be available at http://localhost:5400.

Using components

Augustus uses Pugin as its components library which uses the Dust templating language. However, you can use your own Dust components by placing them in the view directory in the project's root. You can refer to the Shunter templating documentation for more information on how to do this.

Starting Augustus and Shunter serve in a Docker Image

If you wish to run Augustus with shunter serve in a docker image in a development environment, use the following commands:

To build the Docker image

docker-compose build --no-cache

To run Augustus and Shunter serve

docker-compose up

The application will then be available from http://localhost/.

Testing

The test suite can be run using npm test.

Shunter comes with test helpers that allow us to test that given some JSON, we render some expected HTML. The testHelper uses ShunterHelper to setup and teardown our tests.

createFixture is a helper which will generate HTML fixtures to be used in testing. For example, to generate an HTML fixture for an integration test:

testHelper.createFixture('index', 'layout', 'statutory-instruments', true)

This would generate an HTML fixture named index.html which would be located at test/fixtures/html/integration/statutory-instruments/. It would be generated from the JSON file index.json located at data/statutory-instruments/.

For a unit test an example could be:

testHelper.createFixture('index', 'layout', 'statutory-instruments', false)

This would generate an HTML fixture name index.html which would be located at test/fixtures/html/statutory-instruments/. It would be generated from the JSON file index.json located at data/fixtures/json/statutory-instruments/.

Running tests on single files or directories

The npm run testfocus command will let you specify a directory or file of tests to be run.

For example, to run one test:

npm run testfocus test/integration/index_page.spec.js

Or to run a directory of tests:

npm run testfocus test/integration/

i18next Note

Passing in data to the translation with double moustaches sanitises input. If you wish to pass in a URL or other data that you do not wish to be sanitised, for it be rendered correctly you must prefix the variable name with a hyphen. For example:

Double moustaches

The following translation:

"cookie-policy": "<a href='{{link}}'>Cookie Policy</a>"

Will be rendered incorrectly as:

<a href='*&meta*&cookie'>Cookie Policy</a>

Prefixing the variable name with a hyphen

The following translation:

"cookie-policy": "<a href='{{-link}}'>Cookie Policy</a>"

Will be rendered correctly as:

<a href='/meta/cookie'>Cookie Policy</a>

Beautify

Beautify *.json files by running:

make json

Contributing

If you wish to submit a bug fix or feature, you can create a pull request and it will be merged pending a code review.

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Ensure your changes are tested using Mocha
6. Create a new Pull Request

License

Augustus is licensed under the MIT.