--- title: SAIF.Presentation.Web.Controls.V2.Menu operations and processes summary: Business and technical operations supported by this library. status: draft owner: SAIF Doc Gen last_reviewed: 2026-08-17 library: SAIF.Presentation.Web.Controls.V2.Menu reference_type: package --- # SAIF.Presentation.Web.Controls.V2.Menu operations and processes This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under `operations/`. ## Operation catalog | Operation | Intent | Trigger | Inputs | Outputs | Rules | | --- | --- | --- | --- | --- | --- | | [Acquire navigation data](operations/acquire-navigation-data.md) | Obtain the signed-in user's authorised menu items, loading them once per session. | First access to `NavigationData` in a control's page lifecycle within a given ASP.NET session. | Windows logon identity (`Request.LogonUserIdentity.Name`); `Session("navdata")`. | A `NavigationContext` holding the user's authorised menu items, cached in session. | [BR-MENU-001](business-rules.md#br-menu-001-no-navigation-data-is-loaded-at-design-time), [BR-MENU-002](business-rules.md#br-menu-002-navigation-data-is-cached-once-per-session) | | [Build the left menu](operations/build-the-left-menu.md) | Construct the `SAIFMenu` control tree — icons, context box, favourites, and applications accordion — on the page lifecycle. | `SAIFMenu.OnInit` (icon/header setup) followed by `OnLoad` (full control tree build) on every page life-cycle pass. | Hosting page cast to `ViewPageBase`; navigation data from [Acquire navigation data](acquire-navigation-data.md). | Fully populated `SAIFMenu` control tree, registered client scripts. | [BR-MENU-005](business-rules.md#br-menu-005-the-hosting-page-must-be-castable-to-viewpagebase), [BR-MENU-006](business-rules.md#br-menu-006-a-zero-sized-default-submit-button-renders-first) | | [Present the context search box](operations/present-the-context-search-box.md) | Render and manage the context search textbox, including its watermark/placeholder behaviour and change notification. | `SAIFMenu.InitializeControls`, invoked from `CreateControls` during `OnLoad`; property access on `ContextValue`. | `ContextViewStyle`, `ContextLabel`, `UpperCaseContextValue`, posted textbox value. | Rendered context textbox; `ContextValue` property; `OnContextChanged` event. | [BR-MENU-011](business-rules.md#br-menu-011-the-context-box-supports-three-display-modes), [BR-MENU-012](business-rules.md#br-menu-012-an-empty-context-box-displays-its-label-as-watermark-text) | | [Render favourites](operations/render-favourites.md) | Render the favourites list — the user's pinned pages plus, for external clients, a self-service password-change link. | `SAIFMenu.AddFavorites`, invoked from `CreateControls` during `OnLoad`. | `NavigationData.MenuAuthorizedItems.Favorites`; `AppGlobal.EnvironmentService.IsClientExternal`; current item. | One `LinkButton` per favourite, wired to `LinkButtonClick`; an optional `ChangePWLink`. | [BR-MENU-018](business-rules.md#br-menu-018-design-mode-shows-placeholder-favourites), [BR-MENU-019](business-rules.md#br-menu-019-favourites-are-displayed-in-menuorder-sequence) | | [Render the applications accordion](operations/render-the-applications-accordion.md) | Build the collapsible, per-category applications accordion trimmed to the user's authorised, visible menu items. | `SAIFMenu.AddLinks`, invoked from `CreateControls` during `OnLoad`, and again when the applications section is expanded. | `ShowApps`; `NavigationData.MenuAuthorizedItems`; `SelectedCategory`. | An `AjaxControlToolkit.Accordion` (`UMenu`) with one pane per category and a `LinkButton` per visible item. | [BR-MENU-024](business-rules.md#br-menu-024-the-applications-list-is-a-fixed-size-timed-accordion), [BR-MENU-025](business-rules.md#br-menu-025-application-items-are-ordered-by-category-then-order) | | [Expand or collapse the applications section](operations/expand-or-collapse-the-applications-section.md) | Toggle the applications accordion between expanded and collapsed, and persist the user's choice. | Clicking the expand/collapse toggle icon (`SAIFMenu.ExpandClick`). | Current `ContextValue`; current `ShowApps` state; `Preferences` (may be `Nothing`). | Rebuilt or removed accordion; updated `ShowApps`; persisted `SHOWAPPS` preference. | [BR-MENU-032](business-rules.md#br-menu-032-the-context-value-is-preserved-before-menu-driven-postback-navigation), [BR-MENU-033](business-rules.md#br-menu-033-the-applications-section-toggles-between-expanded-and-collapsed) | | [Restore menu state on page pre-load](operations/restore-menu-state-on-page-pre-load.md) | Re-establish the left menu's session-scoped state (expanded/collapsed, current page, context value) at the start of each page life cycle. | `SAIFMenu.Page_PreLoad`, subscribed via the `ViewPageBase.PreLoad` event. | `m_Page.ViewID`; `IsPostBack`; authenticated identity; stored `SHOWAPPS` preference; `Session("CVTextBox" & ViewID)`. | `ShowApps` state; cached `CurrentPage`; restored `ContextValue`. | [BR-MENU-036](business-rules.md#br-menu-036-session-keys-are-namespaced-by-the-pages-viewid), [BR-MENU-037](business-rules.md#br-menu-037-the-showapps-preference-is-applied-only-on-the-initial-authenticated-request) | | [Resolve the user's preference store](operations/resolve-the-users-preference-store.md) | Construct the `clsPreferences` instance used to read and write the `SHOWAPPS` layout preference, or determine that preferences are unavailable. | `SAIFMenu.Preferences` property access (called from [Restore menu state on page pre-load](restore-menu-state-on-page-pre-load.md) and [Expand or collapse the applications section](expand-or-collapse-the-applications-section.md)). | `HttpContext.Current.User.Identity.Name`. | A `clsPreferences` instance scoped to ``/`BOMENU`, or `Nothing`. | [BR-MENU-041](business-rules.md#br-menu-041-preferences-are-keyed-by-the-user-name-portion-of-domainuser), [BR-MENU-042](business-rules.md#br-menu-042-preferences-are-stored-under-the-fixed-application-code-bomenu) | | [Handle a menu link click](operations/handle-a-menu-link-click.md) | Resolve a clicked favourite or application link back to an authorised menu item and raise navigation for the host page. | `SAIFMenu.LinkButtonClick`, the `Click` event of a favourite or application `LinkButton`. | Clicked control's `ID`; `NavigationData.MenuAuthorizedItems`. | `MenuNavigate(ApplicationPath, PageLink)` event, or a direct redirect for the change-password link. | [BR-MENU-044](business-rules.md#br-menu-044-the-change-password-link-redirects-with-the-view-id), [BR-MENU-045](business-rules.md#br-menu-045-the-clicked-menu-item-is-identified-by-the-numeric-suffix-after-_lb) | | [Handle menu icon and Enter-key actions](operations/handle-menu-icon-and-enter-key-actions.md) | Route clicks on the favourites-configuration icon, the hidden default-submit button, and the Enter-key link button to the correct event. | `SAIFMenu.MenuImage_Click` (icon clicks) and `m_EnterControl_Click` (hidden `EC` LinkButton postback). | Clicked control identity; current `ContextValue`. | `MenuNavigate("MenuCache", "frmFavoriteMaint.aspx")`; `DefaultOnSubmit()`; `MenuNavigate("ContextValue", "ENTER")`. | [BR-MENU-049](business-rules.md#br-menu-049-the-favourites-configuration-icon-navigates-to-the-favourite-maintenance-page), [BR-MENU-050](business-rules.md#br-menu-050-the-hidden-default-submit-button-raises-defaultonsubmit) | | [Build the top menu and toolbar](operations/build-the-top-menu-and-toolbar.md) | Construct the `SAIFMenuTop` control tree — the top page-link row and the full set of toolbar action icons. | `SAIFMenuTop.CreateChildControls`, invoked during the ASP.NET control-tree creation phase. | Navigation data (see [Acquire navigation data](acquire-navigation-data.md)). | `TopMenuApp-row` link panel; `TopMenuIcons` panel with all toolbar `SAIFImageButton` icons. | [BR-MENU-052](business-rules.md#br-menu-052-top-page-links-render-inside-the-topmenuapp-row-panel), [BR-MENU-053](business-rules.md#br-menu-053-every-toolbar-icon-is-a-registered-saifimagebutton) | | [Build top page links](operations/build-top-page-links.md) | Render the top row of page links for the currently selected category, trimmed to authorised, visible items. | `SAIFMenuTop.BuildLinkCollection`, invoked from [Build the top menu and toolbar](build-the-top-menu-and-toolbar.md). | `NavigationData.MenuAuthorizedItems.AppItemsByCategory(SelectedCategory)`. | One `LinkButton` (`top_LB`) per visible item. | [BR-MENU-055](business-rules.md#br-menu-055-design-mode-shows-placeholder-page-links), [BR-MENU-056](business-rules.md#br-menu-056-top-links-show-only-the-currently-selected-category) | | [Derive toolbar button visibility from the current page](operations/derive-toolbar-button-visibility-from-the-current-page.md) | Gate each toolbar button's visibility, enabled state, and tooltip on the current authorised page's action-capability flags. | `SAIFMenuTop.Page_PreLoad`, subscribed via the `ViewPageBase.PreLoad` event. | `m_Page.ViewID`; `NavigationData.GetCurrentPage()`; `IsPostBack`. | Updated `Visible`/`Enabled`/`ToolTip` on each toolbar `clsMenuButton`; registered one-click guard scripts. | [BR-MENU-036](business-rules.md#br-menu-036-session-keys-are-namespaced-by-the-pages-viewid), [BR-MENU-039](business-rules.md#br-menu-039-the-current-page-is-resolved-once-and-cached-in-view-state) | | [Prepare and render the toolbar](operations/prepare-and-render-the-toolbar.md) | Synchronise each toolbar icon's rendered image/access-key/tooltip from its logical button model, then render the navigation and toolbar markup in a fixed order. | `SAIFMenuTop.OnPreRender` followed by `RenderControl` during the ASP.NET render phase. | `clsMenuButton` state per icon; `EnableButtonIndicators`; browser user agent (for Firefox detection). | Rendered navigation and toolbar markup; client-side one-click/indicator attributes. | [BR-MENU-062](business-rules.md#br-menu-062-rendered-icon-image-access-key-and-tooltip-are-synchronised-from-the-model), [BR-MENU-063](business-rules.md#br-menu-063-access-key-tooltips-are-prefixed-for-firefox) | | [Render an image button](operations/render-an-image-button.md) | Apply the shared SAIFImageButton CSS class and, when the activity indicator is enabled, wire up the client-side indicator/form-disable script. | `SAIFImageButton.PreRender`, during the ASP.NET render phase for any `SAIFImageButton` instance. | `EnableIndicator`. | CSS class on the rendered ``/``; registered `ImageButton.js` reference; `DisableFormControls` attribute. | [BR-MENU-072](business-rules.md#br-menu-072-every-image-button-carries-css-class-saifimagebutton), [BR-MENU-073](business-rules.md#br-menu-073-enabling-the-indicator-switches-the-css-class-and-publishes-disableformcontrols) | | [Handle a toolbar click](operations/handle-a-toolbar-click.md) | Map a clicked toolbar icon to its logical `ToolBarButton` action and raise the corresponding event(s) for the host page. | `SAIFMenuTop.MenuImage_Click`, the `Click` event of a toolbar `SAIFImageButton`. | Clicked control's `ID`. | `ToolbarClick(ToolBarButton)`; `DefaultOnSubmit()`; `MenuNavigate("", "Help")` (help icon only). | [BR-MENU-075](business-rules.md#br-menu-075-each-toolbar-icon-maps-to-exactly-one-toolbarbutton-value), [BR-MENU-050](business-rules.md#br-menu-050-the-hidden-default-submit-button-raises-defaultonsubmit) | ## Process flow diagram The following diagram visualizes the primary operational flow across operations. ```mermaid flowchart TD Start([Page request]) --> Acquire["Acquire navigation data"] Acquire --> Left["Build the left menu"] Acquire --> Top["Build the top menu and toolbar"] Left --> Restore["Restore menu state on page pre-load"] Top --> Derive["Derive toolbar button visibility from the current page"] Restore --> Render1["Render favourites / applications accordion"] Derive --> Render2["Prepare and render the toolbar"] Render1 --> Click{"User clicks a link or icon?"} Render2 --> Click Click -->|Menu link| Handle1["Handle a menu link click"] Click -->|Toolbar icon| Handle2["Handle a toolbar click"] Handle1 --> Nav([MenuNavigate to host page]) Handle2 --> Tool([ToolbarClick to host page]) ``` ## Failure and edge-case behavior - Design-time rendering never touches session, the database, or navigation data; all three controls emit static placeholder content instead ([BR-MENU-001](business-rules.md#br-menu-001-no-navigation-data-is-loaded-at-design-time), [BR-MENU-018](business-rules.md#br-menu-018-design-mode-shows-placeholder-favourites), [BR-MENU-055](business-rules.md#br-menu-055-design-mode-shows-placeholder-page-links)). - A malformed or unresolvable menu-link click is silently ignored rather than raising an error ([BR-MENU-048](business-rules.md#br-menu-048-a-malformed-link-id-or-failed-navigation-is-silently-ignored)). - Toolbar click handlers do not re-check button visibility or enabled state on the server, so a forged postback targeting a hidden/disabled action still raises its event ([BR-MENU-077](business-rules.md#br-menu-077-toolbar-click-handling-does-not-re-check-visibility-or-enabled-state)). - Unhandled exceptions during `SAIFMenu`/`SAIFMenuTop` rendering 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)). - Invalid accordion pane IDs (empty, `_Header`, or duplicate) throw `ApplicationException` rather than silently skipping the pane ([BR-MENU-028](business-rules.md#br-menu-028-pane-ids-must-be-non-empty-non-reserved-and-unique)). ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Dependencies](dependencies.md) - [Business rules](business-rules.md) - [Database tables](database-tables.md) - [Security and authorization](security-authorization.md) - [Control catalog](control-catalog.md) - [API reference](api/index.md) ## Sources - `SAIF.Presentation.Web.Controls.V2.Menu/SAIFMenu.vb` - `SAIF.Presentation.Web.Controls.V2.Menu/SAIFMenuTop.vb` - `SAIF.Presentation.Web.Controls.V2.Menu/SAIFImageButton.vb`