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

Unsaved Changes

Workspace v2 does not use promptBeforeClosing. Instead, 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 });