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:
launchWorkspace2to open or restore a workspacelaunchWorkspaceGroup2to open a group before the first workspace launch when your app needs group-level context or an app-wide action menucloseWorkspaceGroup2to close the current groupWorkspace2DefinitionProps.closeWorkspaceto close a workspace from inside its componentWorkspace2DefinitionProps.launchChildWorkspaceto open child workspaces in the same window
Store Shape
The v2 store tracks registered definitions and currently opened UI:
registeredGroupsByName- workspace group definitions registered fromworkspaceGroups2registeredWindowsByName- workspace window definitions registered fromworkspaceWindows2registeredWorkspacesByName- workspace definitions registered fromworkspaces2openedGroup- the currently open workspace group and its group propsopenedWindows- the open windows in that group, including each window’s workspace stackisMostRecentlyOpenedWindowHidden- whether the front-most window is currently hiddenworkspaceTitleByWorkspaceName- 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 });