Hacking Workbench2¶

References¶

Redux
Material UI

Startup¶

The application logically begin in workbench2/src/index.tsx with a call to fetchConfig() and then (when the promise is fulfilled) the constructs the major pieces of the application architecture:

Services¶

"services" interact with external resources. These classes define methods for reading and writing to various types of backend (as far as I can tell, they don't hold any state themselves, but talk to external stateful services). Services defined include a service for each of the API server endpoints that workbench uses, WebDAV server, workbench2 configuration like vocabulary and file viewers, and preferences kept in the browser local store.

Store¶

"store" is a Redux state container. State is divided into a groups. Each group defines a "reducer". A reducer is a function that takes (current state, action) and "reduces" it to a new state. At start, reducers are executed with an undefined state to get the initial starting state. After that, state is updated by "dispatching" an action to the state container.

App¶

The "App" is the root react component. It is invoked to regenerate the page, producing a "virtual DOM". ReactDOM merges the virtual DOM changes into the actual browser DOM.

Split implementation¶

Many program features (for example, the "process" panel for displaying a container request) consist of both actions and/or thunks (and their associated reducers or middleware) in the store/ tree as well as React components that live in the views/ tree. For example, loadProcess in store/workbench/workbench-actions is responsible for initializing the state that will be used to create and update the ProcessPanel DOM tree.

Interaction loop¶

1. Render the DOM (based on state from redux store)
2. User clicks on something
3. onClick handler dispatches an action
4. reducer produces a new state based on the action
5. subscribers are notified that the state has changed

'react-redux' links the data store to components use those state items. As part of defining a react component, call connect with a function that extracts only the state required to render the component from the data store. This returns a function, call this with the actual react component definition. This optimizes re-rendering by only updating components that are potentially affected by a given state change.

Defining new state items¶

workbench2/src/store/store.ts

createRootReducer defines the reducer groups. Pick one which is relevant, or define a new one. A reducer group "xyz" is defined in workbench2/src/store/xyz/xyz-reducer.ts

Add the state item to interface XyzState and initialState: XyzState for the group.

Defining new actions¶

Actions types are declared in xyzActions in workbench2/src/store/xyz/xyz-actions.ts.

Actions are implemented in xyzReducer in workbench2/src/store/xyz/xyz-reducer.ts

The reducer for the action reduces (current state, action) to (new state). The new state must have all the state items. There is a shorthand syntax for this: { ...state, open: false } which means "construct a new object with all the items from 'state', except those declared explicitly"

A common pattern seems to be to define functions that can be called or used as event handlers that implement high level behaviors by calling services and dispatching actions.

Middleware and thunks¶

Redux middleware is a chain of functions that the action is passed through before it gets to the store.

Middleware enables these three things:

• Execute code that should happen before an action modifies store
• Modify or suppress actions before they get to the store
• Execute code in response to an action after it has modified the store

If you read the redux documentation, you'll notice that it only talks about dispatching actions, not functions. Workbench2 uses a library called redux-thunk . The redux-thunk middleware intercepts dispatched functions and calls them with (dispatch, getState, services). They don't go to the store. You can use a thunk to invoke an asynchronous function that will proceed independently from the caller.

As a design principal, use a thunk when you need to do some asynchronous action before putting data into the store. For example, making an API call, and then updating the store with the result.

Middleware should be acting on data in the store. For example, synchronizing browser local storage.

DataExplorer¶

The DataExplorer uses middleware.

1. An event callback dispatches to a thunk, such as "loadCollection" or "loadProcess"
2. The thunk's call tree calls REQUEST_ITEMS
3. The middleware responds to REQUEST_ITEMS by starting an asynchronous API request.
4. When the API response comes back, the handler uses SET_ITEMS to put data into the table.

Running tests¶

See Running tests: "Running workbench2 tests"