Adding Data to the ODN Frontend

After adding your dataset to the ODN Backend, you can add it to the ODN Frontend.

Setup

If your changes have not yet been merged into backend production, you should run a local instance of the frontend and point it to a local instance of the backend running with your changes.

Running Frontend Locally

Instructions for running the frontend locally are here.

The quick version:

• Open one terminal and run gulp to build the app continuously as the source changes.
• Open another terminal and run gulp start to start the server on localhost:3000.

Running Backend Locally

Instructions for running the backend locally are here.

The quick version:

• Open one terminal and run npm run server to start the server on localhost:3001.

Make the Frontend use the Local Backend

• Update GlobalConstants._ODN_API_HOST_AND_PORT to localhost:3001;
• Update GlobalConstants._ODN_API_BASE_URL to use http instead of https.

Make sure that you never submit these changes to version control. They will break everything.

Now, go to localhost:3000, and go to an entity from your new dataset. You should see a tab for the new dataset. The tab will have a map but no charts. To add charts, see the next section.

Chart Configuration

To add charts for the new dataset, add an entry to the chart configuration at src/dataset-config.js. The key for the new entry should be the ID of the new dataset (e.g. demographics.population).

Each chart has the following options:

• id (required): CSS ID of the chart. Each chart must have an ID that is unique within its dataset.
• type (required): Type of the chart. Can be bar, column, line, stepped-area, or table.
• name (required): Descriptive name of the chart. This will appear as a heading above the chart.
• variables (required): List of variables to chart. If more than one variable is selected, values must be specified for every constraint in the dataset.
• constraints (sometimes required): Constraint values to use in the chart. If only one variable is specified, then values must be specified for all but one constraint. If more than one variable is specified, values must be specified for all constraints.
• forecast (optional): Available on numerical charts with one variable. This is the number of steps to forecast into the future. Note that forecasting does not work well with non-linear data, and that the number of steps should be kept low (less than five).
• options (optional): Options for Google Charts used to customize the formatting of charts. For a full list of options for line charts, see the Google Charts API. These settings will override the default chart configuration.
• mobileOptions (optional): Google Chart options for use on mobile devices. These settings will override both the chart options and the default chart configuration.

Examples

Population Count over Time

The following chart shows population over time. Since we don't specify a value for year, the chart knows to show all of the available years.

{
    name: 'Population count over time',
    id: 'demographics.population.count.count-over-time',
    type: 'line',
    variables: [
        'demographics.population.count'
    ]
}

Population Count and Change in 2013

We can also create a table that shows population and population change in one year.

{
    name: 'Population count and population change in 2013',
    id: 'demographics.population.count.count-and-change',
    type: 'table',
    constraints: {
        year: 2013
    },
    variables: [
        'demographics.population.count',
        'demographics.population.change'
    ]
}

To show all variables in a dataset, we can just list the dataset ID instead of the IDs of each variable in the dataset. The following configuration produces the same chart as the above configuration:

{
    name: 'Population count and population change in 2013',
    id: 'demographics.population.count.count-and-change',
    type: 'table',
    constraints: {
        year: 2013
    },
    variables: [
        'demographics.population'
    ]
}

Formatting Axis Labels

To format the axis labels, use the vAxis and hAxis format options. For example, to format the vertical axis as a percent:

options: {
    vAxis: {
        format: 'percent'
    }
}

This will display a percent with no decimal points. To add decimal points, use a custom formatter. For example, for two decimal points of precision, use #.##%.

For a list of all format types, refer to the Google Charts documentation.

Submitting Changes on GitHub

Create a new branch with your changes and push it to GitHub. Create a pull request to merge your new branch into staging and notify a member of the ODN team to review your changes.