---
title: SAIFMenu
summary: API reference for SAIFMenu.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.V2.Menu
reference_type: package
---

# SAIFMenu

`SAIFMenu` is the left-hand navigation control for the Business Online application: it owns the context search box, the favourites list, and a collapsible per-category applications accordion. It sources every rendered link from the signed-in user's authorised menu items (`NavigationContext.MenuAuthorizedItems`, session-cached under `Session("navdata")`), casts the hosting page to `SAIF.Presentation.Web.MVC.ViewPageBase` to key session/view-state entries by `ViewID`, and persists the user's expand/collapse choice through `SAIF.Presentation.clsPreferences`. It never navigates itself: clicking a link raises `MenuNavigate` for the hosting page to act on, except the "Change Password" link, which redirects directly for external clients ([BR-MENU-023](../../business-rules.md#br-menu-023-the-change-password-link-is-offered-only-to-external-clients), [BR-MENU-044](../../business-rules.md#br-menu-044-the-change-password-link-redirects-with-the-view-id)).

## Purpose
- Render a context search textbox with three display modes (normal, read-only, hidden) and watermark/placeholder behaviour, notifying the host page of changes via `OnContextChanged` ([BR-MENU-011](../../business-rules.md#br-menu-011-the-context-box-supports-three-display-modes)–[BR-MENU-017](../../business-rules.md#br-menu-017-setting-the-context-value-raises-oncontextchanged)).
- Render the user's favourites list, trimmed to authorised items and ordered by `MenuOrder`, with an optional self-service "Change Password" link for external clients ([BR-MENU-019](../../business-rules.md#br-menu-019-favourites-are-displayed-in-menuorder-sequence), [BR-MENU-023](../../business-rules.md#br-menu-023-the-change-password-link-is-offered-only-to-external-clients)).
- Build and manage a collapsible `AjaxControlToolkit.Accordion` of application categories and links, trimmed to the user's authorised, visible items ([BR-MENU-024](../../business-rules.md#br-menu-024-the-applications-list-is-a-fixed-size-timed-accordion)–[BR-MENU-031](../../business-rules.md#br-menu-031-the-accordion-opens-on-the-selected-category)).
- Resolve menu link clicks back to an authorised menu item and raise `MenuNavigate` for the hosting page, rather than navigating directly ([BR-MENU-046](../../business-rules.md#br-menu-046-navigation-targets-come-only-from-the-authorised-item), [BR-MENU-047](../../business-rules.md#br-menu-047-the-control-never-navigates-itself-it-raises-menunavigate)).
- Persist and restore the user's "show applications pane" layout choice (`SHOWAPPS`) via `SAIF.Presentation.clsPreferences` ([BR-MENU-035](../../business-rules.md#br-menu-035-the-expandcollapse-choice-is-saved-as-a-user-preference)).

## Context
- Namespace: `SAIF.Presentation.Web.Controls.V2.Menu`
- Assembly/package: `SAIF.Presentation.Web.Controls.V2.Menu` (shipped merged into `SAIF.Presentation.Web.Infragistics111.dll` via ILMerge)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `OnContextChanged` | `Public Event OnContextChanged(oldValue As String, newValue As String)` | Notifies the host page whenever the context search value changes, carrying both the previous and new values. |
| `MenuNavigate` | `Public Event MenuNavigate(application As String, page As String)` | Raised whenever a favourite or application link is clicked; carries the resolved authorised item's application path and page link for the host page to act on. |
| `DefaultOnSubmit` | `Public Event DefaultOnSubmit()` | Raised when the hidden default-submit button is triggered (e.g., by pressing Enter outside the context box), letting the host page define its own Enter-key behaviour. |
| `DisplayChangePW` | `Public Property DisplayChangePW As Boolean` | Controls whether the "Change Password" favourite link can be shown at all, in addition to the external-client gate. |
| `ShowApps` | `Public Property ShowApps As Boolean` | Whether the applications accordion is currently expanded; drives both rendering and the persisted `SHOWAPPS` preference. |
| `SelectedCategory` | `Public Property SelectedCategory As String` | The menu category currently selected; determines which accordion pane opens and which top-row links `SAIFMenuTop` shows. |
| `MaxContextValueLength` | `Public Property MaxContextValueLength As Integer` | Maximum character length accepted by the context search textbox. |
| `UpperCaseContextValue` | `Public Property UpperCaseContextValue As Boolean` | When true, forces the value returned by `ContextValue` to upper case. |
| `ContextViewStyle` | `Public Property ContextViewStyle As ContextViewStyleEnum` | Selects whether the context box renders editable, read-only, or hidden. |
| `ContextLabel` | `Public Property ContextLabel As String` | Watermark/placeholder text shown in the context box when it is empty. |
| `ContextValue` | `Public Property ContextValue As String` | The user-entered (or watermark-suppressed) search value; setting it raises `OnContextChanged` with the old and new values. |
| `HighlightPage` | `Public Property HighlightPage As Boolean` | Whether the current page's favourite/application link should be visually highlighted. |
| `DefaultSubmitButton` | `Public Property DefaultSubmitButton As String` | The control ID that should act as the default submit target when Enter is pressed. |
| `getImageButton` | `Public Function getImageButton(logicalName As String) As SAIFImageButton` | Resolves the rendered `SAIFImageButton` instance for a logical menu icon name, letting host pages further customize a specific icon. |

## Behavioral notes
- `GetNavigationData` is duplicated verbatim in `SAIFMenuTop` rather than shared, so the two controls must be kept in sync manually.*
- The left menu control tree is fully rebuilt on every page load rather than cached across postbacks ([BR-MENU-007](../../business-rules.md#br-menu-007-the-left-menu-control-tree-is-rebuilt-on-every-page-load)).
- Rendering exceptions are caught and their message, source, and stack trace are written directly into the page rather than raised ([BR-MENU-071](../../business-rules.md#br-menu-071-rendering-failures-are-reported-in-page-rather-than-raised)), an information-disclosure risk in production.

## Constraints and usage notes
- The hosting page should be (or be castable to) `SAIF.Presentation.Web.MVC.ViewPageBase`; when it is not, `m_Page` is `Nothing` and `ViewID`-based session/view-state keys fall back to an empty string ([BR-MENU-005](../../business-rules.md#br-menu-005-the-hosting-page-must-be-castable-to-viewpagebase)).*
- `SAIFMenuTop.NavigateToItem` locates the left menu by the literal control ID `SAIFMenu1`; hosting pages should not rename the `SAIFMenu` instance.**
- Preference persistence (`SHOWAPPS`) requires the authenticated identity to be in `DOMAIN\user` form; otherwise preference read/write is silently skipped ([BR-MENU-043](../../business-rules.md#br-menu-043-preference-handling-is-skipped-for-non-domainuser-identities)).

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `SAIF.Presentation.Web.Controls.V2.Menu/SAIFMenu.vb`