Hybrid rendering app for the GOV.UK Performance Platform using Backbone and D3. JavaScript is shared between the client and server, and the app makes use of progressive enhancement to provide a great experience in every browser.
Just Spotlight: The simplest way to get started is to run just this app, against production data.
Firstly, it is recommended that you set up Node Version Manager on your host. See the (nvm) README for installation instructions.
Next checkout the Spotlight repo and create an .nvmrc file in its
root directory containing the version of node specified in the 'engines' entry
in package.json
e.g. 0.10.26.
Now install the specified version of node using nvm:
nvm install 0.10.26
To check you have the correct version of node installed:
nvm which
Found '/Users/<username>/<path to>/spotlight/.nvmrc' with version <0.10.26>
/Users/<username>/.nvm/v0.10.26/bin/node
Now tell nvm to use the version of node specified in the .nvmrc
file:
nvm use
You can then run the app as follows:
npm install -g grunt-cli # install grunt globally
npm install
grunt
Now you should be able to connect to the app at http://localhost:3057
. If you're running the app from the govuk vm, you need to replace localhost with the IP address of your vagrant machine in the url. Currently this is: http://10.1.1.254:3057
The app uses node-supervisor and grunt-contrib-watch to monitor changes, automatically restart the server and recompile Sass.
By default, this will look at production data, but perhaps you want to connect
to a different data source. You can do that
by creating your own config file in /config/config.development_personal.json
that mimics
/config/config.development.json
with a different backdropUrl
property. It'll be ignored by Git.
Full stack: if you're using our development environment then you can run all our apps in one go and use a real database for development. As a bonus, this will let you test the image fallbacks using the screenshot-as-a-service app.
First, you need to set up the Performance Platform development environment.
Once you have a machine with the required system-level dependencies, you can run the application with:
cd /var/apps/pp-puppet/development
bowl performance
Tests are divided into ones that work on both client and server (test/spec/shared
), ones that are server-only (test/spec/server
) and ones that are client-only (test/spec/client
).
grunt test:all
runs all three of these tests, as well as linting the codebase:
grunt jasmine_node
executes shared and server Jasmine tests in Node.jsgrunt jasmine
executes shared and client Jasmine tests in PhantomJSgrunt shell:cheapseats
executes feature tests using cheapseats with a small subset of dashboards, for speedgrunt shell:cheapseats_full_run
runs cheapseats with all dashboardsgrunt test:functional
executes functional tests using [nightwatch][https://github.com/beatfactor/nightwatch]
As part of the CI (travis) grunt test:functional:ci
is run. This spins up an instance of spotlight, nightwatch and phantomjs to run the tests in a headless environment.
To assist with debugging the functional tests can also be run in a selenium webdriver using the following command grunt test:functional:ff
If you want to run against firefox,chrome and phantom you can also do grunt test:functional:all
.
All the functional tasks except ci
will require a server to be running already.
When the app is running in development mode, Jasmine tests for shared
components are available at /tests
. The specrunner gets automatically
recreated on server start and when the specfiles change. Due to a
bug in grunt-contrib-watch, new spec files are not currently
detected automatically. When you add a new spec file, either restart the
app or run grunt jasmine:spotlight:build
.
Install node-inspector where the app runs with sudo npm install -g node-inspector@0.5.0
and run it with node-inspector
.
Start the app with node --debug app/server.js
and visit http://spotlight.perfplat.dev:8080/debug
to view the console.
grunt build:production
to create a production release.
NODE_ENV=production node app/server.js
to run the app in production mode.
If you want to deploy the app to Heroku, follow these instructions.
Using the web interface, or the CLI:
heroku create <app-name>
The app runs on Heroku using a custom buildpack for Grunt.js support.
This means it will run the grunt commands we need to compile the app when deploying code.
heroku config:set BUILDPACK_URL=https://github.com/mbuchetics/heroku-buildpack-nodejs-grunt.git
heroku config:set NODE_ENV=development # makes app run in development mode
heroku config:set npm_config_production=true # does not install dev dependencies
If the code you're deploying is not in master, then you'll need to make sure you specify your local branch to push to master. Otherwise it will just deploy your local master (and probably not work as expected).
git push heroku <your-branch-name>:master
heroku open # opens the freshly deployed app in a browser
If you want the Heroku app to be password-protected, set config variables as follows, before pushing the code.
heroku config:set BASIC_AUTH_USER=xxxx
heroku config:set BASIC_AUTH_PASS=xxxx
heroku config
You might also want to enable some logging in your Heroku app to assist with debugging. You can use logentries to do that:
heroku addons:add logentries
You can then access the logs from your app's dashboard on Heroku (under the "Add-ons" section).
For Javascript, follow the styleguide (apart from the sections on GOV.UK modules as we don't use these)
Functionality should work without Javascript where possible.
All content should work well with screenreaders (at least Voiceover and JAWS). 'Work well' means
- a screenreader user can orientate themselves effectively and use the page.
- async updates are reported to the user (an 'accessibility' module exists for this).
Tables are used in the following places:
- To display a list of dashboards on the services, web-traffic and other dashboards pages
- To display data on a dashboard, e.g. a web-traffic dashboard
- To be displayed instead of a graph if javascript is disabled.
As there are more tables underpinning graphs than any other tables in spotlight, table columns are configured as though they are the axes on a graph.
Columns defined in the x-axis will appear before those in the y-axis.
For example, axes defined as:
axes: {
x: {
key: 'key_X',
label: 'Label X'
},
y: [
{
key: 'key_Y_one',
label: 'Label Y1',
format: 'integer'
},
{
key: 'key_Y_two',
label: 'Label Y2',
format: 'integer'
}
]
}
Will be displayed as:
Label X | Label Y1 | Label Y2 |
---|---|---|
Value X | Value Y One | Value Y Two |
The y-axis only accepts a list of column configuration.
The x-axis will accept a list or a single value. If a list is provided, the columns will appear in reverse order in the table. For example, x-axis columns defined as:
x: [
{
key: 'key_X_one',
label: 'Label X1'
},
{
key: 'key_X_two',
label: 'Label X2'
}
]
Will be displayed as:
Label X2 | Label X1 |
---|---|
Value X Two | Value X One |
Axes configuration is most commonly found in the module visualisation settings, and can be edited via the admin app.
Configuration for tables displaying lists of dashboards can be found in their respective controllers.