Skip to content

Latest commit

 

History

History
194 lines (140 loc) · 7.17 KB

DEV_GUIDE.md

File metadata and controls

194 lines (140 loc) · 7.17 KB

Accessibility Theme Builder Application

This document serves as a getting started guide for working with the Accessibility Theme Builder Application.

Install Dependencies

The Theme Builder application can be built and run locally using two variations (Quick and Easy, Javascript Runtime Environment) that differ on complexity of setup (devops).

Basic Requirements

  • Install git
  • Learn how to fork and clone GitHub repositories.

Quick and Easy

If you simply desire to run the application and do not require to perform any development enhancements, the easiest approach for running the application locally is to install Docker Desktop.

Javascript Runtime Environment

If you desire to extend or enhance the application, a local development environment will need to be configured. This requires the installation of Node.js prerequisites, specifically NodeJS 16+ and npm 8+. Visit nodejs downloads for latest versions.

Install and Use

Perform the following steps to run a local version of the application.

Fetch Latest Code

These instructions assume you have a local copy of a forked instance of discoverfinancial/a11y-theme-builder.

cd <WORKSPACE>
git clone https://github.com/<YOUR-ORG>/a11y-theme-builder
cd a11y-theme-builder

where:

  • <WORKSPACE> is path to the local folder where you have created a copy of the GitHub repository.
  • <YOUR-ORG> is the name of your GitHub account or personal GitHub organization.

Quick and Easy

Building and running the application using Docker can be achieved in a few simple steps, which all assume a /code as the working directory.

cd <WORKSPACE>/a11y-theme-builder/code

Embedded Database

The Theme Builder application requires the use of a persisted embedded database. This requirement is satisfied by attaching a local host directory, /code/src/data, to the running docker container.

Build image

docker build . -t a11y-theme-builder

Start new container

docker run -p 8080:3001 -v ${pwd}:/code/src/data --name a11y-theme-builder -d a11y-theme-builder

View Application

To access the running application, load the following URL into a browser:

http://localhost:8080

Stop container

docker stop a11y-theme-builder

Start a stopped container

docker start a11y-theme-builder

Remove a stopped container

docker rm a11y-theme-builder

Javascript Runtime Environment

The following commands will build and run the application using a local Node.js environment running on a Linux distribution such as MacOS:

cd a11y-theme-builder/code
npm run build
npm run debug

To access the application, load the following URL into a browser:

http://localhost:3001

Development

The Theme Builder is a web application that uses Node for the server and React for the UI. Both server and UI use typescript, which is compiled into javascript and saved in the build directories:

Directory Description
code/build Server JS
code/src/ui/build UI React JS

The command npm run build builds both the server and UI. To build just the server, run

npm run build-api

or to build the UI, run

npm run build-ui

To simplify developing of the UI, the React Development Server can be run

npm run dev-ui

To access the application through the React Development Server, load the following URL into a browser:

http://localhost:3000

Any changes made to the React source code will automatically be updated in the browser on port 3000.

Note that the build directory is not updated with these changes until an npm run build or npm run build-ui is performed.

Potential Windows Issue

One problem you might run into on a Windows system is that themes may not appear, load, or be created. If this is the case, it most likely means there is a problem with you themes file, which acts as the database. The most common explanation is that your environment has automatically changed the line endings of this file to CRLF. To fix this either use your editor to change the line endings to LF, or better, follow this guide to ensure git does not do this in the future by running the command git config --global core.autocrlf false, and reseting the repo.

Understanding Server APIs

The Theme Builder server serves the React application at the / endpoint.

The APIs are under the /api/ endpoint, with the following apis available:

/api/themes?metadata - Get list of all themes or metadata for all themes

  • Method: GET
  • Returns: Array of theme names
  • Return Errors: None
  • Example: GET /api/themes => [ "theme1", "theme2" ]
  • Example: GET /api/themes?metadata => [ {id:"theme1", metadata:{..}}, {id:"theme2", metadata: {..}} ]

/api/themes - Create a new theme

  • Method: POST
  • Body: Theme object
  • Returns: Theme object
  • Return Errors: 500, 501 invalid document, 502 document already exists
  • Example: POST /api/themes { id:"theme3", key1:themeData} => { id:"theme3", key1:themeData}

/api/themes - Delete all themes (This deletes the database, so use with caution)

  • Method: DELETE
  • Returns: returns boolean (true=success, false=fail)
  • Return Errors: none
  • Example: DELETE /api/themes => true

/api/themes/:id - Get a theme and return all fields

  • Method: GET
  • Returns: Theme object
  • Return Errors: 404 document :id was not found, 500
  • Example: GET /api/themes/theme5 => { id:"theme5", key1:themeData}

/api/themes/:id?fields=field1,field2,... - Get a theme and return only fields

  • Method: GET
  • Returns: Partial theme object
  • Return Errors: 404 document :id was not found, 500
  • Example: GET /api/themes/theme5?field=key1 => {key1:themeData}

/api/themes/:id?returnDoc=true - Update a theme or fields of a theme

  • Method: PUT
  • Body: Theme object or {?set: Partial theme object}
  • Returns: If returnDoc, then return Theme object, else return true
  • Return Errors: 404 document :id was not found, 500
  • Example: PUT /api/themes/theme5 {key2:{subkey1: updatedSubData1}} => true
  • Example: PUT /api/themes/theme5?returnDoc=true {key2:{subkey1: updatedSubData1}} => {id:"theme5", key2:{subkey1: updatedSubData1}
  • Example: PUT /api/themes/theme5?returnDoc=true {?set: {"key2.subkey1": updatedSubData1}}} => {id:"theme5", key1:themeData, key2:{subkey1: updatedSubData1}

/api/themes/:id - Delete a theme

  • Method: DELETE
  • Returns: Theme object
  • Return Errors: 404 document :id was not found, 500
  • Example: DELETE /api/themes/theme5 => { id:"theme5", key1:themeData}