{"type":"doc","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"left panel(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://zeroheight.com/23a080e38/p/796c6a-left-panel"}}]},{"text":" provides navigation within an App in O3. It is based on Carbon's ","type":"text"},{"text":"UI shell left panel(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://carbondesignsystem.com/components/UI-shell-left-panel/usage/"}}]},{"text":", and is positioned below the header, fixed to the left edge of the page. It is possible to add a left panel to any page in O3 if you need to leverage its navigation capabilities.","type":"text"}]},{"type":"paragraph","content":[{"text":"This guide will walk you through the process of adding a left panel to the ","type":"text"},{"text":"Bed Management app(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/METS-Programme/esm-ugandaemr-bed-management-app"}}]},{"text":", which is a frontend module that's part of the UgandaEMR+ instance. The bed management app handles the management of beds in a hospital, and is a good candidate for a left panel because it has multiple pages that need to be navigated to.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Example: Adding a left panel to the Bed Management app","type":"text"}]},{"type":"paragraph","content":[{"text":"The Bed Management app has the following screens that need to be navigated to:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The landing screen, which shows a summary of the number of beds in each ward.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A detail screen for a specific ward, which shows the number of beds in that ward and their current status.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ward allocation screen, which allows you to add, edit and delete beds, as well as allocating beds to wards.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"We'll need to setup the following navigation links in the left panel:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"Summary","type":"text","marks":[{"type":"code"}]},{"text":" link for the landing screen and the ward detail screen.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An ","type":"text"},{"text":"Administration","type":"text","marks":[{"type":"code"}]},{"text":" link for the bed management administration screen.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Below is a screenshot of how the app looks like:","type":"text"}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":250,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2048,"alt":"Screenshot of the bed management app landing page showing the left panel","id":"ed6f43d2-f617-4dd2-881a-21aab274c51b","collection":"contentId-150962840","type":"file","height":1043}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"To achieve this, we're going to follow the steps below:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Set up the left panel","type":"text"}]},{"type":"paragraph","content":[{"text":"Begin by updating your root component (or whatever component your app uses to set up routing) as follows:","type":"text"}]},{"type":"paragraph","content":[{"text":"src/root.component.tsx","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"import React, { useEffect } from \"react\";import { BrowserRouter, Route, Routes } from \"react-router-dom\";import { LeftNavMenu, setLeftNav, unsetLeftNav } from \"@openmrs/esm-framework\";import BedAdministrationTable from \"./bed-administration/bed-administration-table.component\";import Home from \"./home.component\";import WardWithBeds from \"./ward-with-beds/ward-with-beds.component\";import styles from \"./root.scss\"; const Root: React.FC = () => { const spaBasePath = window.spaBase; useEffect(() => { setLeftNav({ name: \"bed-management-left-panel-slot\", basePath: spaBasePath, }); return () => unsetLeftNav(\"bed-management-left-panel-slot\"); }, [spaBasePath]); return (

} /> } /> } />

);}; export default Root;","type":"text"}]},{"type":"paragraph","content":[{"text":"Some key things to note here are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're importing the ","type":"text"},{"text":"LeftNavMenu","type":"text","marks":[{"type":"code"}]},{"text":" component from the ","type":"text"},{"text":"@openmrs/esm-framework","type":"text","marks":[{"type":"code"}]},{"text":" package. This component renders the left panel. We're also importing the ","type":"text"},{"text":"setLeftNav","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"unsetLeftNav","type":"text","marks":[{"type":"code"}]},{"text":" functions from the same package. These functions are used to register and unregister the left panel with the ","type":"text"},{"text":"LeftNav store(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/da401641b4b1895e593e9bcea73af8f8dbd505e5/packages/framework/esm-styleguide/src/left-nav/index.tsx#L18"}}]},{"text":" respectively. The LeftNav store is a ","type":"text"},{"text":"Zustand(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/pmndrs/zustand"}}]},{"text":" store that keeps track of all the left panels that have been registered in the app.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're calling the ","type":"text"},{"text":"setLeftNav","type":"text","marks":[{"type":"code"}]},{"text":" function in a ","type":"text"},{"text":"useEffect","type":"text","marks":[{"type":"code"}]},{"text":" hook. This function takes an object with two properties:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":": The name of the slot that the left panel should be rendered in. This is the same name that you'll use when adding the left panel to the ","type":"text"},{"text":"extensions","type":"text","marks":[{"type":"code"}]},{"text":" array of your ","type":"text"},{"text":"routes.json","type":"text","marks":[{"type":"code"}]},{"text":" file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"basePath","type":"text","marks":[{"type":"code"}]},{"text":": The base path of the app (","type":"text"},{"text":"/openmrs/spa","type":"text","marks":[{"type":"code"}]},{"text":" by default). This is used to ensure that the left panel links are relative to the app's base path.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're calling the ","type":"text"},{"text":"unsetLeftNav","type":"text","marks":[{"type":"code"}]},{"text":" function in a ","type":"text"},{"text":"useEffect","type":"text","marks":[{"type":"code"}]},{"text":" cleanup function. This function takes the name of the slot that the left panel was rendered in. This ensures that the left panel gets unregistered when the component unmounts.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're rendering the ","type":"text"},{"text":"LeftNavMenu","type":"text","marks":[{"type":"code"}]},{"text":" component as the first child of the ","type":"text"},{"text":"BrowserRouter","type":"text","marks":[{"type":"code"}]},{"text":" component. This ensures that the left panel gets rendersd in all the routes of the app.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're setting up three routes for the Bed Management app:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"/summary","type":"text","marks":[{"type":"code"}]},{"text":" route that renders the ","type":"text"},{"text":"Home","type":"text","marks":[{"type":"code"}]},{"text":" component.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"/ward/:wardUuid","type":"text","marks":[{"type":"code"}]},{"text":" route that renders the ","type":"text"},{"text":"WardWithBeds","type":"text","marks":[{"type":"code"}]},{"text":" component. The ","type":"text"},{"text":":ward","type":"text","marks":[{"type":"code"}]},{"text":" portion of the route is a URL parameter that gets passed to the ","type":"text"},{"text":"WardWithBeds","type":"text","marks":[{"type":"code"}]},{"text":" component as a prop. This component is used to render the detail page for a specific ward.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An ","type":"text"},{"text":"/ward-allocation","type":"text","marks":[{"type":"code"}]},{"text":" route that renders the ","type":"text"},{"text":"BedAdministrationTable","type":"text","marks":[{"type":"code"}]},{"text":" component.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Wiring up the root page","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, we'll create a named export for the ","type":"text"},{"text":"Root","type":"text","marks":[{"type":"code"}]},{"text":" component inside the ","type":"text"},{"text":"index.ts","type":"text","marks":[{"type":"code"}]},{"text":" file. This is the component that we'll use to wire up the ","type":"text"},{"text":"Root","type":"text","marks":[{"type":"code"}]},{"text":" component to the ","type":"text"},{"text":"bed-management","type":"text","marks":[{"type":"code"}]},{"text":" route so that it gets rendered when you navigate to that route.","type":"text"}]},{"type":"paragraph","content":[{"text":"Add the following to your ","type":"text"},{"text":"index.ts","type":"text","marks":[{"type":"code"}]},{"text":" file:","type":"text"}]},{"type":"paragraph","content":[{"text":"src/index.ts","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"import rootComponent from './root.component'; export const root = getSyncLifecycle(rootComponent), options);","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, modify your ","type":"text"},{"text":"routes.json","type":"text","marks":[{"type":"code"}]},{"text":" file to include the following page definition:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{ \"$schema\": \"https://json.openmrs.org/routes.schema.json\", \"backendDependencies\": { \"fhir2\": \"^1.2.0\", \"webservices.rest\": \"^2.24.0\" }, \"pages\": [ { \"component\": \"root\", \"route\": \"bed-management\" } ]}","type":"text"}]},{"type":"paragraph","content":[{"text":"This page definition tells O3 to render the ","type":"text"},{"text":"Root","type":"text","marks":[{"type":"code"}]},{"text":" component when you navigate to the ","type":"text"},{"text":"bed-management","type":"text","marks":[{"type":"code"}]},{"text":" route.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Add links to the left panel","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, we'll want to add the two links that we mentioned earlier to the left panel:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"Summary","type":"text","marks":[{"type":"code"}]},{"text":" link for the landing screen.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"Ward allocation","type":"text","marks":[{"type":"code"}]},{"text":" link for the ward allocation screen.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"To do this, we'll need to create two extensions that render the links. We'll then add those extensions to the ","type":"text"},{"text":"extensions","type":"text","marks":[{"type":"code"}]},{"text":" array of our ","type":"text"},{"text":"routes.json","type":"text","marks":[{"type":"code"}]},{"text":" file. The named exports of those extensions will be used as the ","type":"text"},{"text":"component","type":"text","marks":[{"type":"code"}]},{"text":" property of the extensions, and look like the following:","type":"text"}]},{"type":"paragraph","content":[{"text":"src/index.ts","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"export const summaryLeftPanelLink = getSyncLifecycle( createLeftPanelLink({ name: \"summary\", title: t(\"summary\", \"Summary\"), }), options); export const wardAllocationLeftPanelLink = getSyncLifecycle( createLeftPanelLink({ name: \"ward-allocation\", title: t(\"wardAllocation\", \"Ward Allocation\"), }), options);","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"createLeftPanelLink","type":"text","marks":[{"type":"code"}]},{"text":" function is a higher-order function that takes a ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" and a ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" property. The ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" property is the unique path that the URL segment gets matched against. If the name matches the last portion of the URL, then the matching link gets some special styling to indicate that it is the active link. The ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" property gets rendered as the link text.","type":"text"}]},{"type":"paragraph","content":[{"text":"We're importing this ","type":"text"},{"text":"createLeftPanelLink","type":"text","marks":[{"type":"code"}]},{"text":" function from a separate file called ","type":"text"},{"text":"left-panel-link.component.tsx","type":"text","marks":[{"type":"code"}]},{"text":" that looks like the following:","type":"text"}]},{"type":"paragraph","content":[{"text":"src/left-panel-link.component.tsx","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"import React, { useMemo } from \"react\";import last from \"lodash-es/last\";import { BrowserRouter, useLocation } from \"react-router-dom\";import { ConfigurableLink } from \"@openmrs/esm-framework\"; export interface LinkConfig { name: string; title: string;} function LinkExtension({ config }: { config: LinkConfig }) { const { name, title } = config; const location = useLocation(); let urlSegment = useMemo(() => decodeURIComponent(last(location.pathname.split(\"/\"))), [location.pathname]); const isUUID = (value) => { const regex = /^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$/; return regex.test(value); }; if (isUUID(urlSegment)) { urlSegment = \"summary\"; } return ( {title} );} export const createLeftPanelLink = (config: LinkConfig) => () => ( );","type":"text"}]},{"type":"paragraph","content":[{"text":"Some key things to note here are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're using the ","type":"text"},{"text":"ConfigurableLink(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/f5538148b48f5f8c3fc621ffde0e2d25fb60db6d/packages/framework/esm-react-utils/src/ConfigurableLink.tsx#L42"}}]},{"text":" component from the ","type":"text"},{"text":"@openmrs/esm-framework","type":"text","marks":[{"type":"code"}]},{"text":" package to render the link. The ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" property gets rendered as the link text. The link also gets some special styling if the ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" property matches the last portion of the URL that distinguishes it as the active link.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're using the ","type":"text"},{"text":"useLocation","type":"text","marks":[{"type":"code"}]},{"text":" hook from the ","type":"text"},{"text":"react-router-dom","type":"text","marks":[{"type":"code"}]},{"text":" package to get the current URL. We then extract the last segment of the current pathname and decode it. This segment is stored in the ","type":"text"},{"text":"urlSegment","type":"text","marks":[{"type":"code"}]},{"text":" variable. We then use the ","type":"text"},{"text":"urlSegment","type":"text","marks":[{"type":"code"}]},{"text":" variable to determine whether the link is active or not.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We're using the ","type":"text"},{"text":"createLeftPanelLink","type":"text","marks":[{"type":"code"}]},{"text":" higher-order function to create a component that renders the link. This function takes a ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" and a ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" property. The ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" property is the unique path that the URL segment gets matched against. If the name matches the last portion of the URL, then the matching link gets some special styling to indicate that it is the active link. The ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" property gets rendered as the link text.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When the last segment of the URL is a UUID (which is the case when you click on a ward card on the landing page), we're setting the ","type":"text"},{"text":"urlSegment","type":"text","marks":[{"type":"code"}]},{"text":" variable to ","type":"text"},{"text":"summary","type":"text","marks":[{"type":"code"}]},{"text":". This ensures that both the landing and detail screen s get the ","type":"text"},{"text":"Summary","type":"text","marks":[{"type":"code"}]},{"text":" link highlighted as the active link.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Finally, we're exporting the ","type":"text"},{"text":"createLeftPanelLink","type":"text","marks":[{"type":"code"}]},{"text":" function so that it can be used to create the ","type":"text"},{"text":"Summary","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"Ward allocation","type":"text","marks":[{"type":"code"}]},{"text":" links.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Add the extensions to the routes.json file","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, we'll need to add the two extensions that we created in the previous step to the ","type":"text"},{"text":"extensions","type":"text","marks":[{"type":"code"}]},{"text":" array of our ","type":"text"},{"text":"routes.json","type":"text","marks":[{"type":"code"}]},{"text":" file as shown below:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"extensions\": [ { \"component\": \"adminCardLink\", \"name\": \"bed-management-admin-card-link\", \"slot\": \"system-admin-page-card-link-slot\" }, { \"component\": \"summaryLeftPanelLink\", \"name\": \"bed-management-left-panel-link\", \"slot\": \"bed-management-left-panel-slot\", \"order\": 0 }, { \"component\": \"wardAllocationLeftPanelLink\", \"name\": \"ward-allocation-left-panel-link\", \"slot\": \"bed-management-left-panel-slot\" }]","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Profit!","type":"text"}]},{"type":"paragraph","content":[{"text":"That's it! When you navigate to the ","type":"text"},{"text":"bed-management","type":"text","marks":[{"type":"code"}]},{"text":" route, you should see the landing screen of the Bed Management app, which should look like the following:","type":"text"}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":250,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2048,"alt":"Screenshot of the bed management app landing page showing the left panel","id":"ed6f43d2-f617-4dd2-881a-21aab274c51b","collection":"contentId-150962840","type":"file","height":1043}}]},{"type":"paragraph","content":[{"text":"Clicking on the ","type":"text"},{"text":"General Men Ward","type":"text","marks":[{"type":"code"}]},{"text":" card navigates you to a detail page for a specific ward, which should look like the following:","type":"text"}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":250,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2048,"alt":"Screenshot of the ward page which is a nested route of the landing page","id":"1cf695c9-603e-4ea6-a227-2589aad55fa6","collection":"contentId-150962840","type":"file","height":1214}}]},{"type":"paragraph","content":[{"text":"Finally, clicking the ","type":"text"},{"text":"Ward Allocation","type":"text","marks":[{"type":"code"}]},{"text":" link in the left panel leads you to the Ward Allocation page, which looks like the following:","type":"text"}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":250,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":2048,"alt":"Screenshot of the administration page of the bed management app","id":"fa6a98e3-2882-4c62-be25-c07c57ac6329","collection":"contentId-150962840","type":"file","height":1318}}]}],"version":1}

Browser not supported