Arvados

h1. Hacking Workbench2

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