defra / admin-prototype-kit

[Archived] Brings the GDS govuk admin template into an environment suitable for rapid prototyping by service teams

Admin prototyping kit

Note: The GOVUK admin template that this was supposed to provide a prototyping kit for has now been marked as deprecated and will not be getting any new updates. Hence work on this project has also now stopped. There will be no further changes and the project has now been archived.

Based on a stripped down Rails 4.2 application, this kit provides a way to create high-res prototypes based on the GOV.UK admin template that users can interact with, as quickly and simply as possible.

Use in production

In a word, DON'T! This kit has been designed for prototyping, not production code. Take only the lessons learned and your designs into a production system.

Versions

The project is currently using Ruby version 2.2.3 and Rails 4.2.

Obtain the source

You'll need git to work with the source code. Once you have it clone the repository:

git clone https://github.com/DEFRA/admin-prototype-kit.git

This will copy the project into a new directory called admin-prototype-kit created in the folder you ran the command from. We refer to this as the working directory.

Drop into the working directory using cd admin-prototype-kit before attempting any of the steps below.

Installation (local)

You will need to ensure you have version 2.2.2 of Ruby available, and we would suggest you manage your ruby installations with a tool like rvm or rbenv.

Application gems (local)

You will then also need to install the bundler gem.

gem install bundler

When it finishes install the application gems using

bundle install

Start the service (local)

To start the service locally simply run

. bin/startup.sh

You can then access it at http://0.0.0.0:3001

Stop the service (local)

To stop the service use ctrl+c

Installation (vagrant)

If the above instructions are new to you, or you would prefer to just be given a ready made environment then you can make use of the fact we have enabled Vagrant in the project.

Vagrant is a tool that enables quick and simple setup of development environments, generally using virtual machines (though other containers are also supported). The simplest way to get up and running is to first install VirtualBox, then install Vagrant.

Back in the working directory run the following command:

vagrant up

This will take awhile the first time it runs as it needs to build the virtual machine from scratch. Once done it will remain running in the background. You can access the machine using vagrant ssh if you need to.

Start the service (vagrant)

To start both the vagrant box and the service simply run;

. bin/vagrant_startup.sh

You can then access it at http://0.0.0.0:3001

Stop the service (vagrant)

To stop the service use vagrant halt

Working with the code

Irrespective of whether you installed it locally or are using the Vagrant box, you will work with the code in the same way.

Edit the code using your preferred editor. Generally changes to any files in the app/ won't require you to restart rails, but any changes in config/ will. (If you are working with any of the other folders we assume you know what you are doing 😃!)

Examples

We have included examples on how to add new pages to the kit, and how to use the underlying Rails engine to add additional functionality. Both the example and the how to instructions are part of the kit. Links to the examples can be found on the home page.

Currently the examples cover the following

• Static pages
• Dynamic routing
• Read records
• Form options

Protecting your prototypes

The kit contains a simple method to restrict access to your site to only those people you want to see it. Please note the method is intended to be as simple and maintainable as possible, but should not be considered as secure. If you truly need to protect your work please do not rely on this method.

Enabling the key

By default when the kit is running anyone who knows the url can access the site and the pages within. If however you want to restrict access you simply need to create an environment variable within the OS you're running the kit on.

export ACCESS_KEY='let-me-in'

It must be named ACCESS_KEY and contain a value, however the value can be whatever you want. From then on whenever someone requests a page without supplying the access key they will instead see the public/private.html.erb page.

Providing the key

Having set the key you should then give it to only those users permitted to access the site. In order to supply it they should use a URL like this mysite.co.uk?access_key=let-me-in when first accessing the site. As long as it matches the kit will then create a permanent cookie with the key value in, so any subsequent requests and visits to the site will no longer need the argument specified.

Contributing to this project

If you have an idea you'd like to contribute please log an issue.

All contributions should be submitted via a pull request.

License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.

admin-prototype-kit's Issues

Add prototype page generator

Rails has the concept of generators. This are commands that can be called to make changes automatically to the app rather than manually editing the files. For example when you first create a new Rails app you are using a generator.

rails new my-new-app

Within the kit a page could be said to be made of three parts

• the page itself
• the before_show method
• the after_update method

We feel users of the kit would benefit from a generator that automatically creates these 3 parts based on a supplied page name. We believe not only would it simplify working with the kit for users, but it will also reduce errors.

Add data generator

As explained in issue #8 Rails as the concept of generators. We would like to add another custom generator to the kit, this time to help working with data.

If you wish to add your own fake dataset to the kit you first need to add a new model, and then create a method in config/initializers/dummy_data.rb which uses the model to create the dataset.

We believe users will benefit from a generator which given a name for the dataset and the names of the fields you want it to have, creates both the model and the method in dummy_data.rb for you. You will still need to amend the method to create as many fake records as required, but at least it has been created correctly and you will have an example to work from when then adding your own.