Technical NCI Header Design - NCIOCPL/ncids Wiki

Technical: Javascript: NCI Header Design Overview

NCI Header Class Diagram

NCIExtendedHeaderWithMegaMenu

This is the component class for the Extended Header with Mega Menu variant of a NCI Header. The component can be instantiated by selecting the header dom element, and providing a set of options.

NCIExtendedHeaderWithMegaMenuOptions

This class represents the options for a NCIExtendedHeaderWithMegaMenu component. The options are

Option Description
mobileMenuSource This should be an instance of a MobileMenuAdapter. See Mobile Menu Adapters section below
megaMenuSource This should be an instance of a MegaMenuAdapter. See Mega Menu Adapters section below

Mobile Menu Adapters

A mobile menu adapter is a class that implements the MobileMenuAdapter interface. The design system does not force you to have to build your backend systems in any specific way. You can build a mobile menu adapter that fetches the data for the mobile menu however your site needs it to be fetched. The only thing we require is that the menu information conform to a NavItem structure item and only be the data for a single "level" within the navigation. (i.e. not the entire navigation tree)

Adapter Methods

Property Description
getInitialMenuId As users navigate the menu items, the header will request the corresponsind menu from the adapter. It can do this since it is the one drawing the menu items. However, on initial click of the Mobile Menu Button, the header will not know what menu to fetch. This method is provided for just that purpose. See Sequence of Events for a Mobile Menu Adapter below for more information.
getNavigationLevel This method returns a level of navigation to be displayed in the mobile menu. This should include the "Explore ABC

Mobile Menu Data

There are two types that represent a single level of navigation. The classes appear in the diagram above an this section with explain the properties for the types.

MobileMenuItem

A MobileMenuItem type represents a single menu item in the mobile menu.

Property Description
id the identifier for this section
label The display label for this menu item
path The URL for this menu item
langcode The 2 character language code. NOTE: This may not be needed.
hasChildren Indicator noting this menu item has children and therefore should open a new level of navigation.

MobileMenuData

The MobileMenuData type represents a "pane" or "level" of the navigation. This is used to represent 3 primary areas:

  1. The Back Navigation (property: parent)
    • If at the root of the navigation, this does not display
  2. The Explore Link that navigates to the landing page of this section (the MobileMenuItem properties of the MobileMenuData itself)
  3. The items within this menu (property: items)

See the diagram below for 1, 2 and 3.

The MobileMenuData type extends the MobileMenuItem type and inherits all the properties of that.

Property Description
items The collection of menu items to display under the Explore XXX link
parent The parent menu item. If this does not exist we are display the root of the mobile menu, and will not display a Back or Main Menu link at the top of the nav.

Sequence of Events for a Mobile Menu Adapter

Mega Menu Adapters

A mega menu adapter is a class that implements the MegaMenuAdapter interface. The design system does not force you to have to build your backend systems in any specific way. You can build a mega menu adapter that fetches the data for your menus however your site needs it to be fetched. The only thing we require is that you return the HTML for the mega menu contents prebuilt using the correct design system elements.

Adapter Methods

Property Description
useUrlForNavigationId This defines what should be passed to the adapter for fetching menus. If this is true then the HREF of the navigation link will be provided to the adapter. If this is false then the header will use the data-menu-id attribute of the navigation link instead. It is helpful to use an ID if you have some dynamic system which only allows you to fetch menu information by ID instead of a path.
getMegaMenuContent This method gets the megamenu contents (as an HtmlElement) for the given id or URL.

Sequence of Events for a Mega Menu Adapter

Original Mermaid for header-design.svg

  classDiagram
    direction TB
    NCIExtendedHeaderWithMegaMenuOptions "1" o--> "1" MobileMenuAdapter : requires
    NCIExtendedHeaderWithMegaMenuOptions "1" o--> "1" MegaMenuAdapter : requires
    NCIExtendedHeaderWithMegaMenu ..> NCIExtendedHeaderWithMegaMenuOptions : uses
    MobileMenuAdapter ..> MobileMenuData : produces
    MobileMenuItem <|-- MobileMenuData
    MobileMenuData "1" o--> "0..*" MobileMenuItem : items
    MobileMenuData "1" o--> "1" MobileMenuItem : parent

    class NCIExtendedHeaderWithMegaMenu {
      #new(element: HTMLElement, options: Partial~NCIExtendedHeaderWithMegaMenuOptions~)
      unregister()
      create(element: HTMLElement, options: Partial~NCIExtendedHeaderWithMegaMenuOptions~)$
    }

    class NCIExtendedHeaderWithMegaMenuOptions {
      <<type>>
      mobileMenuSource: MobileMenuAdapter
      megaMenuSource: MegaMenuAdapter
    }

    class MobileMenuAdapter {
      <<interface>>
      getInitialMenuId () number|string
      getNavigationLevel (id: number|string) Promise~MobileMenuData~
    }

    class MegaMenuAdapter {
      <<interface>>
      useUrlForNavigationId() boolean
      getMegaMenuContent (id: number|string) Promise~HTMLElement~
    }  

    class MobileMenuData {
      <<type>>
      id: number | string;
      label: string;
      path: string;
      langcode: string;
      hasChildren: boolean;
      items: MobileMenuItem[]
      parent: MobileMenuItem
    }

    class MobileMenuItem {
      <<type>>
      id: number | string;
      label: string;
      path: string;
      langcode: string;
      hasChildren: boolean;
    }

Original Mermaid for megamenu-sequence.svg

sequenceDiagram
    actor Visitor
    Visitor->>Web Page: load
    Web Page->>+NCIExtendedHeaderWithMegaMenu: create()
    Visitor->>Web Page: click primary navigation item
    Web Page->>NCIExtendedHeaderWithMegaMenu: handle click event
    NCIExtendedHeaderWithMegaMenu->>megaMenuAdapter: getMegaMenuContent(id or url)
    megaMenuAdapter-)Remote Data Source: Fetch Data
    Remote Data Source-->>megaMenuAdapter: data
    megaMenuAdapter->>NCIExtendedHeaderWithMegaMenu: HtmlElement
    NCIExtendedHeaderWithMegaMenu-->>Web Page: Open Mega Menu Overlay
    NCIExtendedHeaderWithMegaMenu-->>Web Page: Display Html from adapter

Work Area

sequenceDiagram
    actor Editor
    actor Visitor
    Editor->>/taxonomy/term/32/edit: Enters YAML Content for Mega Menu in Drupal
    Drupal->>/taxonomy/term/32/edit: Validates YAML
    Drupal->>/taxonomy/term/32/edit: Stores YAML

    Visitor->>Web Page: load
    Web Page->>+NCIExtendedHeaderWithMegaMenu: create()
    Visitor->>Web Page: click About Cancer (id: 32)
    Web Page->>NCIExtendedHeaderWithMegaMenu: handle click event
    NCIExtendedHeaderWithMegaMenu->>cgdpMegaMenuAdapter: getMegaMenuContent(id: 32)
    cgdpMegaMenuAdapter-)/taxonomy/term/32/mega-menu: Fetch Data
    /taxonomy/term/32/mega-menu-->>cgdpMegaMenuAdapter: json data
    cgdpMegaMenuAdapter-->>cgdpMegaMenuAdapter: Parse json and create HTML
    cgdpMegaMenuAdapter->>NCIExtendedHeaderWithMegaMenu: HtmlElement
    NCIExtendedHeaderWithMegaMenu-->>Web Page: Open Mega Menu Overlay
    NCIExtendedHeaderWithMegaMenu-->>Web Page: Display Html from adapter
⚠️ **GitHub.com Fallback** ⚠️