Skip to Content
DocsWorkspacesImplementation: Under the hood

Implementation: Under the Hood

Workspace v2 state is managed by the framework’s workspace store. Most application code should use the public APIs instead of manipulating the store directly:

  • launchWorkspace2 to open or restore a workspace
  • launchWorkspaceGroup2 to open a group before the first workspace launch when your app needs group-level context or an app-wide action menu
  • closeWorkspaceGroup2 to close the current group
  • Workspace2DefinitionProps.closeWorkspace to close a workspace from inside its component
  • Workspace2DefinitionProps.launchChildWorkspace to open child workspaces in the same window

Store Shape

The v2 store tracks registered definitions and currently opened UI:

  • registeredGroupsByName - workspace group definitions registered from workspaceGroups2
  • registeredWindowsByName - workspace window definitions registered from workspaceWindows2
  • registeredWorkspacesByName - workspace definitions registered from workspaces2
  • openedGroup - the currently open workspace group and its group props
  • openedWindows - the open windows in that group, including each window’s workspace stack
  • isMostRecentlyOpenedWindowHidden - whether the front-most window is currently hidden
  • workspaceTitleByWorkspaceName - titles supplied by each rendered <Workspace2> wrapper

Each opened window contains windowName, props, maximized, and openedWorkspaces. Each opened workspace stores its workspaceName, launch props, generated uuid, and hasUnsavedChanges state.

Reading Workspace Context

Inside a workspace component, use the props supplied by Workspace2DefinitionProps or the useWorkspace2Context hook to read the current workspace context:

import { useWorkspace2Context } from '@openmrs/esm-framework'; export function WorkspaceDebugPanel() { const { workspaceName, windowName, workspaceProps, windowProps, groupProps } = useWorkspace2Context(); return ( <pre> {JSON.stringify( { workspaceName, windowName, workspaceProps, windowProps, groupProps, }, null, 2, )} </pre> ); }

The lower-level workspace store is an implementation detail. Prefer the public launch, close, group, and context APIs unless you are working inside the framework itself. If a component needs to close the entire window instead of only itself and its child workspaces, call closeWorkspace({ closeWindow: true }).

Rendering a Workspace Outside the Workspace Window

<ExportedWorkspace> renders the content of a registered workspace (the children of its <Workspace2>) inside your own component tree, independent of the global workspace window system. It emulates the window that contains the workspace, so launchChildWorkspace and closeWorkspace navigate within the component, using a local store. It renders no chrome (no title bar, maximize, hide, close, or icon), so callers can render their own.

import { ExportedWorkspace } from '@openmrs/esm-framework'; <ExportedWorkspace name="gastrodynamics-form-workspace" workspaceProps={{ patientUuid }} />;

Changing name, workspaceProps, windowProps or groupProps (props are compared shallowly) discards the current workspaces without prompting for unsaved changes and opens name afresh. Use onWindowChanged to observe the emulated window’s state.

Unsaved Changes

Pass hasUnsavedChanges to the <Workspace2> wrapper:

<Workspace2 title={t('editVisit', 'Edit visit')} hasUnsavedChanges={formState.isDirty}> {/* workspace content */} </Workspace2>

When a user closes a workspace, closes a window, changes incompatible props, or switches groups, the workspace system checks the hasUnsavedChanges flags for the affected workspaces and prompts when needed.

After saving, close the workspace without showing the unsaved-changes prompt:

await closeWorkspace({ discardUnsavedChanges: true });
Last updated on