Skip to content

Development

Jump to bottom
Timo Franz edited this page Aug 21, 2018 · 22 revisions

Tech Stack

Here is a list of packages that this application is built on (please see package.json for a full list of dependencies):

Core JavaScript libraries

  • React: A library for component-based development
  • Redux: A state container for managing application state
  • Redux Saga: A library for managing side effects such as loading data
  • Reselect: A selector library for accessing Redux state
  • ImmutableJS: A library for immutable data collections
  • Styled Components: Low-level styling constructs for styling components
  • react-vis: a system for composable data visualisation components based on d3
  • react-hash-route: simple hash-based routing

Development libraries

Installation & usage

Installation

yarn/npm install

Run

yarn start/npm start to start dev server with hot reload, it's live on localhost:3000.

Build

yarn run build/npm run build to build prod bundle, it includes both treeshaking and uglify to optimize the code as much as possible.

The product bundle will be located in the dist/ folder

Code documentation (React Styleguidist)

yarn run doc/npm run doc

The generated code documentation will be located in the styleguide/ folder and can be viewed online using RawGit

Project structure

src/

The application source code structured following a container/component architecture (see also Architecture) with the following folders for JavaScript:

  • src/containers/: 'smart' components connected to Redux store, as well as all other high-level 'path' containers (see also Sitemap)
  • src/components/: 'dumb' components without store access and primarily concerned with layout and presentation
  • src/styles/: primitive Styled Components for re-usable styles
  • src/utils/: JavaScript helper functions

It also contains the following noteworthy JavaSript files:

In addition there are folders for graphics and text:

  • src/assets/: application graphics
  • src/text/: application text, including all labels and static editorial content (see also Text)

data/

Contains example data for development and testing.

dist/

The compiled application bundle for integrating in data.govt CMS page template.

styleguide/

The generated code documentation as raw HTML files. See RawGit to view online.

Processes

Entry point

src/index.js is the application entry point that renders the application into a 'root' HTML element <div id="root"></div>. It also sets up and synchronises the application store, global styles and hash routing.

Storing data

The application state is the single source of truth and kept in the Redux store. Any changes to the store can only be made by reducers that respond to predefined actions) that components can dispatch.

Reading data

Connected, 'smart' components can read data from the store using selectors. In fact these smart components respond to any state changes with the selected data-subset and automatically re-render.

Loading data

Sagas, like reducers, also respond to actions and kick off side effects. The loadDataSaga is responsible for requesting data either from the data.govt API (if (value.source === 'api')) or from example CSV files (if (value.source === 'csv'))

The data endpoints both for API (path and resource Ids) and CSV requests are configured in the application constants. Simply change the value for API to false to load the example test data.

Routing

navigateSaga, another saga, is responsible for navigating within the application by triggering path or query changes using react-hash-route's route function.

Once the route is updated, src/index.js will load the relevant path component, and also update the store which in turn will trigger any connected components and their children to re-render.

*** Data mappings

All data mappings, including specific record IDs or other values, are mapped in the application constants.

In particular it assumes the following (see also Charts & indicators:

  • the subject id for the default subject "All of Government": DEFAULT_SUBJECT_ID = 'all';
  • the focus area indicator ids: FOCUSAREA_INDICATOR_IDS = [ 'fa1', 'fa2', 'fa3', 'fa4', 'fa5', 'fa6' ];
  • the data services indicator ids:
    • HOW_ID: 'q03'
    • STANDARDS_ID: 'q05'
    • SERVICES_ID: 'q04'
  • the data assets indicator ids:
    • ASSETS_ID: 'assets'
    • MACHINEREADABLE_ID: 'assets_machinereadable'
    • NZGOAL_ID: 'assets_nzgoal'
  • survey question answer values: ['yes', 'developing', 'like_to', 'not_sure', 'not_warranted', 'no', 'not_stated']

Assets

All graphics are being inlined and become part of the single application bundle to minimise dependencies.

SVG graphics are not being loaded as base64 image source strings as content security policy prevents loading data: sources. Instead they are being

  • inlined (as required for multi-color graphics) with React components using https://github.com/kossnocorp/desvg
  • or provided by compound path objects as application constants allowing for variable styling (providing a fill colour)

Text

Formattable text is provided as markdown files that are being parsed and inserted as dangerouslySettingInnerHtml HTML and thus packaged into the single application bundle.

All other text fields are being defined referred to by JSON object key and located in a single file for ease of maintainability (see also Text).

Integration

As the distributable application bundles all graphics and styles the integration is very straightforward:

  1. Reference application bundle: `<script type="text/javascript" src="path/to/index.js"></script>
Clone this wiki locally