eLabSDK2.UI.Navigation

Hierarchy

unknown

↳ Navigation

Methods

addMainMenuAction

Static addMainMenuAction(menuItem): void

Add a custom action button to the main navigation bar.

This adds an action button to the main navigation, typically appearing as a clickable
icon or button in the navigation bar. Action buttons usually trigger immediate actions
rather than navigation.

Parameters

Name	Type	Description
`menuItem`	`MenuItemConfiguration`	{id: string, label: string, action: () => void, isVisible?: () => boolean, icon: string}

Returns

void

Example

// Add quick-create sample action
eLabSDK2.UI.Navigation.addMainMenuAction({
  id: 'quick-create-sample',
  label: 'Create Sample',
  action: () => openCreateSampleDialog(),
  isVisible: () => true,
  icon: 'fas fa-plus-circle'
});

addMainMenuItem

Static addMainMenuItem(menuItem): void

Add a custom menu item to the main navigation bar.

This adds a new item to the main application navigation menu, typically appearing
in the top navigation bar alongside default menu items like Dashboard, Inventory,
Journal, etc. Menu items can navigate to custom pages, trigger actions, or open
dialogs. Visibility can be controlled conditionally using the isVisible function.

Parameters

Name	Type	Description
`menuItem`	`MenuItemConfiguration`	{id: string, label: string, action: () => void, isVisible?: () => boolean, icon?: string}

Returns

void

Example

// Add a simple menu item
eLabSDK2.UI.Navigation.addMainMenuItem({
  id: 'custom-reports',
  label: 'Reports',
  action: () => {
    window.location.href = '/members/custom/?rootVar=myAddon&page=myAddon_reports';
  },
  isVisible: () => true,
  icon: 'fas fa-chart-bar'
});

addPage

Static addPage(config): void

One method covers both a top-level main-menu page and a submenu page. The page content
is supplied as a typed CustomPageContent union with two kinds:

{ kind: 'iframe', src } — the host builds a sandboxed <iframe> for the given URL. src must
be an absolute https:// URL and must not be the eLab host origin; otherwise the page is ignored
and a warning is logged to the console. The frame runs with
sandbox="allow-scripts allow-same-origin allow-forms allow-popups" and referrerpolicy="no-referrer",
so your embedded app may run scripts, use its own origin's storage/cookies, submit forms, and open popups.
{ kind: 'html', html } — a static string sanitized through DOMPurify: standard markup and inline
style attributes are preserved, but <style> blocks, scripts, and event handlers are removed and
forms cannot submit off-site. The html shares the host page, so escape any untrusted values you interpolate.

Omit mainMenu for a top-level page. For a submenu, pass an existing menu label
('Journal', 'Inventory', 'Protocols', 'Supplies', 'Configuration', 'File Storage') or
the id of a custom main-menu page from the same add-on. The value is matched against the
existing labels first (exact, case-sensitive); anything else is treated as a custom parent
page id and auto-prefixed with rootVar (as is your own id) to keep add-ons isolated. If it
matches neither an existing label nor a registered page from this add-on, the page is stored but
never shown, and a warning is logged to the console when the menu renders.

Once registered, a page is reachable at /members/custom/?rootVar=<rootVar>&page=<rootVar>_<id>
(the addressable id is the prefixed ${rootVar}_${id}, not the id you passed). A bare
/members/custom/?rootVar=<rootVar> (no &page) opens that add-on's first top-level page.

Call addPage from your add-on's initialization. Registrations last for the current page load
only — re-register your pages on each load. There is no persistence, removal, or update API.

Parameters

Name	Type	Description
`config`	`CustomPageConfiguration`	{rootVar: string, id: string, label: string, icon?: string, content: CustomPageContent, mainMenu?: string, onAfterRender?: () => void}

Returns

void

Example

// A top-level main-menu page — appears in the main nav next to Journal, Inventory, …
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'dashboard',
  label: 'My Dashboard',
  icon: 'fas fa-gauge',
  content: { kind: 'html', html: '<div style="padding:24px"><h1>Dashboard</h1><p>Welcome to my add-on.</p></div>' },
});

Example

// A submenu page under an EXISTING menu — set `mainMenu` to the menu's visible label.
// Valid labels: 'Journal', 'Inventory', 'Protocols', 'Supplies', 'Configuration', 'File Storage'.
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'stock-report',
  label: 'Stock Report',
  mainMenu: 'Inventory',
  content: { kind: 'html', html: '<div style="padding:24px"><h1>Stock Report</h1></div>' },
});

Example

// A CUSTOM main menu with its own submenu pages. Register the main page first, then give each
// child `mainMenu` = the parent's bare `id` ('tools'); the SDK prefixes it for you, so do NOT
// pass the prefixed 'myAddon_tools' or a URL.
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'tools',
  label: 'Tools',
  icon: 'fas fa-toolbox',
  content: { kind: 'html', html: '<div style="padding:24px"><h1>Tools</h1><p>Pick a tool from the menu.</p></div>' },
});
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'importer',
  label: 'Importer',
  mainMenu: 'tools',
  content: { kind: 'html', html: '<div style="padding:24px"><h1>Importer</h1></div>' },
});
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'exporter',
  label: 'Exporter',
  mainMenu: 'tools',
  content: { kind: 'html', html: '<div style="padding:24px"><h1>Exporter</h1></div>' },
});

Example

// `html` is just a string, so real pages are usually composed (template literals, a builder
// function, …) into a variable and passed in. The markup is sanitized before it is rendered.
const rows = ['Acetone', 'Ethanol', 'Methanol']
  .map((name) => `<tr><td>${name}</td><td>In stock</td></tr>`)
  .join('');
const pageHtml = `
  <div style="padding:24px">
    <h1>Reagent Overview</h1>
    <table>
      <thead><tr><th>Reagent</th><th>Status</th></tr></thead>
      <tbody>${rows}</tbody>
    </table>
  </div>`;
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'reagents',
  label: 'Reagents',
  content: { kind: 'html', html: pageHtml },
});

Example

// A top-level page embedding an external web app in a sandboxed iframe.
// `src` must be an absolute https:// URL and not the eLab host itself.
eLabSDK2.UI.Navigation.addPage({
  rootVar: 'myAddon',
  id: 'external',
  label: 'External Tool',
  icon: 'fas fa-up-right-from-square',
  content: { kind: 'iframe', src: 'https://example.com' },
});

clearMainMenu

Static clearMainMenu(): void

Remove all default entries from the main navigation menu.

This clears all standard navigation menu items from the main menu, providing a blank
slate for building a completely custom navigation structure. After clearing, add your
custom menu items using addMainMenuItem().

Warning: This removes all default navigation items including Dashboard, Inventory,
Journal, etc. Users will not be able to access these areas unless you provide
alternative navigation.

Returns

void

Example

eLabSDK2.UI.Navigation.clearMainMenu();