Arvados

h1. Hacking Workbench2

h2. References

"Redux":https://redux.js.org/api/api-reference

"Material UI":https://material-ui.com/getting-started/installation/

h2. 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:

h2. 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 the API server endpoint that workbench uses, WebDAV server, workbench2 configuration like vocabulary and file viewers, and preferences kept in the browser local store.

h2. Store

"store" is a "Redux":https://redux.js.org/ 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.

h2. 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.

h2. 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.

h2. Interaction loop

# Render the DOM (based on state from redux store)

# User clicks on something

# onClick handler dispatches an action

# reducer produces a new state based on the action

# 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.

h2. 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.

h2. 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.

h2. Middleware and thunks

Redux "middleware":https://redux.js.org/api/applymiddleware 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":https://github.com/reduxjs/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.

h2. DataExplorer

The DataExplorer uses middleware.  

# An event callback dispatches to a thunk, such as "loadCollection" or "loadProcess"

# The thunk's call tree calls REQUEST_ITEMS

# The middleware responds to REQUEST_ITEMS by starting an asynchronous API request. 

# When the API response comes back, the handler uses SET_ITEMS to put data into the table.

h2. Running tests

See [[Running tests#Running-workbench2-tests]]: "Running tests"