Skip to content

Development

Jump to bottom
Timo Franz edited this page Aug 27, 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.

Before producing the styleguide, the above command will also produce and include documentation using documentation.js for those functions that are not React components (in particular index.js, Redux functions, utility functions). See styleguide.config.js for how the different parts are pieced together.

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.

Patterns

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>
  2. In your template or HTML file create a tag with id 'oggd-root': <div id="ogdd-root"></div>
  3. Done =)

However there are a few issues that can arise, especially with content security policies or global leaky styles in place (see also issues labeled integration):

White-list font

Please make sure the Google font 'Barlow' is white-listed (set in global-styles)

Beware of those leaky styles

Please make sure to override any parent global styles without scope (defined in the parent app) to prevent the parent app messing up the OGDD styles.

Also make sure to prefix any OGDD global-styles with the #ogdd-root selector to prevent messing with the parent app

Clone this wiki locally