README.md

Pugin Components

Pugin Components is a front-end dust component library for beta.parliament.uk. It is built on Shunter.

Contents

• Requirements
• Quick start
• Running the application
• Using the Library
• Running tests on single files or directories
• i18next Note
  • Double moustaches
  • Prefixing the variable name with a hyphen
• Contributing
• License

Requirements

Pugin Components requires the following:

• NodeJS - click here for the exact version
• NPM

Quick start

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

Running the application

To run the application locally, run:

make develop

This runs foreman that starts the app and shunter erve

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

Using the Library

To use the package, you need to add it and save it into the list of dependencies in your package.json file:

npm install --save pugin-components

Then go to your shunter application's config (for example app.js or index.js). Add modules to the file, like the example below:

const app = shunter({
    path: {
        themes: __dirname
    },
    routes: config.routes,
    jsonViewParameter: 'json',
    modules: ['pugin-components']
});

You should now be able to call on the components as if they were in a view folder in your root directory.

Updating versions of Pugin assets (CSS/JS)

The make build task compiles the css and javascript assets from Pugin. This task is used when you would like to specify a different tag release of Pugin as to what was originally installed.

For example, in the package.json amend parliamentuk-pugin to another tag release:

"parliamentuk-pugin": "git+https://github.com/ukparliament/parliament.uk-pugin.git#1.11.3",

then run:

"make build"

After which you then run npm update in your local application.

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/unit/components/card/generic.spec.js

Or to run a directory of tests:

npm run testfocus test/unit/components/card/

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>

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

Pugin Components is licensed under the MIT.