A toolkit for design patterns used across Digital Marketplace projects
npm install digitalmarketplace-frontend-toolkitA toolkit for design patterns used across Digital Marketplace projects.
Each pattern in ./toolkit/ provides:
- A Jinja template
- SASS
- Javascript (if needed)
- Images (if needed)
Dependency management and integrating these files into a build pipeline are the
concern of each project that uses them. This is already set up for all Digital
Marketplace frontend apps.
The documentation is generated from the contents of this repository.
Create a virtual environment in the checked-out repository folder
```
make virtualenv
``
source ./venv/bin/activate
- In one shell run make serve_pagesmake watch_for_changes
- In another shell run
- Visit http://localhost:8000
You can preview changes you make to the patterns by building the documentation
locally. There are 3 to 5 parts to a pattern:
Usage examples for each pattern are defined in the ./pages_builder/pages
folder. They are YAML files which show what parameters you can pass to a
template. The examples in the documentation are generated from these files.
#### Grids in example pages
Examples can use the grids (see grids example) by setting a grid property in this file.
If all the examples in your page sit in the same column, set the grid class you need with the page-level properties (ie on the textbox example page).
If any of your examples need their own column, set the grid class you need with the example-level properties (ie on the temporary message example page).
If you don't need a grid column, don't set any grid properties in your file.
Templates are found in the ./toolkit/templates folder. They are Jinja.html
templates with an extension. Their name corresponds to the name of the
example. They get rendered once for each of the provided examples, using the
provided examples' data.
Create your SASS file in ./toolkit/templates. Import it into./pages_builder/assets/scss/index.scss.
The ./toolkit/scss, ./pages_builder/govuk_frontend_toolkit/stylesheets and./pages_builder/assets/scss folders are included in the load path so you can
import any files from them.
When writing SASS for this toolkit, follow the styleguide.
Javascript modules should be initialised by calling them from
./pages_builder/assets/javascripts/onready.js.
jQuery is available for you to use but only as last resort.
Javascript should be tested with Jasmine (requires node
and NPM).
To run the tests in ./spec:` shell`
npm install
npm test
Images can be added to ./toolkit/images
Use the file-url mixin to reference them in your stylesheet. It will resolve`
paths, eg: SCSS`
background: file-url('your-image.png');
A local checkout of the frontend-toolkit repo can be shared with locally-running services (i.e. frontend applications)
as follows, assuming you have a system-wide install of npm available:
- from this repo, run npm linknpm link digitalmarketplace-frontend-toolkit
- from each app, run
Your frontend apps will then be using your local copy of the frontend-toolkit patterns rather than the version specified
in their package.json - for example, whenever you:
- rebuild the app's toolkit directory by running make frontend-build; ornpm run frontend-build:watch
- run to automatically rebuild the frontend-toolkit content whenever a pattern file
changes.
Releases of this project follow semantic versioning, ie
> Given a version number MAJOR.MINOR.PATCH, increment the:
>
> - MAJOR version when you make incompatible API changes,
> - MINOR version when you add functionality in a backwards-compatible manner, and
> - PATCH version when you make backwards-compatible bug fixes.
To make a new version:
- run npm version to update the version number;.npmrc
- (note that npm has been configured not to create a new tag when you run this command - see )package.json
- if you are making a major change, also update the change log;
- commit and CHANGELOG.md` if appropriate - for a small PR, this could be in the same commit as other
changes you are making; for a larger PR you might want a separate commit with a message that summarises the entire PR.
When the pull request is merged
Github Actions
will be run to tag and publish the new version.
Unless stated otherwise, the codebase is released under [the MIT License][mit].
This covers both the codebase and any sample code in the documentation.
The documentation is [© Crown copyright][copyright] and available under the terms
of the [Open Government 3.0][ogl] licence.
[mit]: LICENCE
[copyright]: http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/
[ogl]: http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/