ptcs-menubar

Visual

Overview

A ptcs-menubar presents the user with a vertical list of menu items. Each menu item might have optional subitems, which might also have submenus, and so on. There is no physical limit to the nesting depth.

The subitems can be displayed in two different ways, either in flyout or in nested accordion mode.

In nested mode, all items are displayed within the menu area itself. Items with subitems can be clicked to reveal the items below within the boundaries of the menu.

In flyout mode, subitems are displayed in a popup window when the parent item is clicked.

The ptcs-menubar takes an array of objects. Fixed field names are used to extract the values from each object in the array:

• label is used for the title of the menu item
• icon for the item icon (if any)
• disabled is a boolean flag, specifying if the item should be grayed out and non-interactive. Default is false.
• tooltip / tooltipIcon specifies the tooltip / tooltip icon to display for the menu item (if any)
• content is an array, defining any (optional) subitems.

The Menu bar has four distinct areas:

• The Header area, containing the reveal icon (that toggles the compact mode)
• The Primary area
• The Secondary area
• A Footer area for branding information (e.g. a Company logo)

The Primary area is displayed at the top of the Menu bar whereas the Secondary and the Footer areas are displayed at the bottom of the Menu bar. The Footer area is optional and may be hidden.

In nested mode, the Secondary area is not available. Any data passed to it will be appended to the data in the Primary area.

The ptcs-menubar can be displayed in Compact mode, showing the items on the primary level with just an icon, without the text. This is activated by clicking of the reveal icon in the header.

The ptcs-menubar has three internal helper objects:

• ptcs-menu-flyout, which handles the data in the Primary and Secondary areas if the Menu bar type is flyout.
• ptcs-menu-item represents an item in either the flyout menu or in a popup menu (with an (optional) icon, a title, and an optional submenu)
• ptcs-menu-submenu is a popup menu, displayed when selecting a menu item, containing the menu items of the submenu

These should not be exposed or used separately, but their parts are available for styling.

In the nested accordion case, the data in the Primary and Secondary areas are handled by a ptcs-accordion object.

Usage Examples

Basic Usage

<ptcs-menubar items="[[itemsTop]]"
           items2="[[itemsBottom]]"></ptcs-menubar>

Component API

Properties

Property	Type	Description	Default	Triggers a changed event?
menuType	String	Defines the type of the Menu bar, how subitems are displayed. Should be either 'flyout' or 'nested'.	"flyout"
items	Array	Array of objects to display in the Primary area	[ ]
items2	Array	Array of objects to display in the Secondary area	[ ]
matchSelectorF	Function	Function that determines if a given menu item matches a selectedKey string. This allows the user to match any property in the item, not just e.g. the title
selectedKey	String	When used to set the selection from the "outside", this is the 'key' to select (it is interpreted by the user-supplied matchSelectorF function)
maxMenuItems	Number	Defines the maximum number of visible primary items. If there are more items added to this area, they will be "collapsed" as a submenu under a "virtual" More items... entry. This is only supported in flyout mode.
maxSubmenuItems	Number	Defines the maximum number of items in a popup menu. If there are more items in the popup, they will be "collapsed" as a submenu under a "virtual" More items... entry
moreItemsLabel	String	The string to use for the text of the virtual "More..." entry	"More..."
moreItemsIcon	String	The icon to use for the virtual More items... entry	"cds:icon_more_horizontal"
brandingItem	String	The data to use for the branding/footer section. Uses the same format as the "main" data, there should be a property called label for the text, icon for the (optional) icon and additional logo that overrides both label and icon on expanded mode. Any other data can also be added, this items is returned to the callback when the user clicks the footer.	null
hideBrandingArea	Boolean	Hides the footer/branding area
allowMissingIcons	Boolean	Deprecated. Should any missing icons be replaced by a 'default' icon?
fillMissingIcons	Boolean	Displays a filler icons next to items with a missing icon
stayOpenAfterSelection	Boolean	In 'nested' mode, should the Menu bar "collapse" or remain open after a selection has been made?	false
alwaysOpen	Boolean	Should the Menu bar always be open, and the reveal button in the header thus be hidden?	false
preventResize	Boolean	Should the resize handle be visible or not?	false
displayIconsInUpperRegion	Boolean	Should the icons in the upper (Primary) region be visible?	false
displayIconsInLowerRegion	Boolean	Should the icons in the lower (Secondary) region be visible?	false
compactMode	Boolean	Deprecated. Should the main Menu bar be displayed in Compact mode (showing just the icons)?
disableCompactMode	Boolean	Disables compact mode	false
maxWidth	Number	Minimum width of accordion. Directly mapped to CSS max-width.
minWidth	Number	Minimum width of accordion. Directly mapped to CSS min-width.
menuMaxWidth	String	Max width of the popup menus
menuMinWidth	String	Min width of the popup menus
disabled	Boolean	Should the Menu bar be disabled?	false
iconWidth	String	Sets a fixed width for the icon (both iconWidth and iconHeight should be set, otherwise the icon default size is set)		No
iconHeight	String	Sets a fixed height for the icon (both iconWidth and iconHeight should be set, otherwise the icon default size is set)		No

Parts Structure

The Menu bar has the following parts:

Part	Description
root	Root element of the Menu bar (including items and expand/handle parts)
main-area	Contains the header, the items-area, and the footer
header	Contains the reveal button that toggles the compactMode
header-icon	The reveal ptcs-icon
items-area	The core of the Menu bar where the items are displayed, either in flyout or nested mode
footer	Containing the branding information
branding-item	A ptcs-menu-item used to display the footer data
flyout	In flyout mode, this contains the ptcs-menu-flyout object that holds the Primary and Secondary areas
accordion	In nested mode, Contains a ptcs-accordion object that displays the items
expand	The "line" to the right of the items
handle	The clickable handle displayed in the middle of the expand area to allow resizing by dragging
handle-icon	The ptcs-icon of the handle
popup	Each ptcs-menu-submenu that displays the items of a submenu has this part name

Note that the popup elements are not added as children of the ptcs-menubar element in the DOM tree but rather appended to the document element itself.

The flyout menu has the following parts:

Part	Description
navigator-items	Root element of the items, both primary and profile
primary-items	The Primary items displayed at the top of the Menu bar
profile-items	The Secondary items displayed at the bottom of the Menu bar
menu-item	Each menu item (regardless of its area) has this part name

For the nested menu type, see the ptcs-accordion documentation for details.

The menu item has the following parts:

Part	Description
icon	A ptcs-icon displaying the item icon (if any)
label	A ptcs-label displaying the menu item text
submenu-icon	A ptcs-icon displayed to the right of the label to indicate that an item has a submenu

The popup menu has the following parts:

Part	Description
root	Root element of the popup menu
menu-item	Each menu item has this part name

Events

Name	Data	Description
action	ev.detail = { item }	Generated when the user clicks on a "leaf" in the menu tree (an item without a submenu)

Methods

ptcs-menubar has no methods.

State attributes

Attribute	Description	Part
disabled	Is the Menu bar disabled?	:host
selected	Is a menu item currently selected (does it have an open popup menu)	menu-item
overflow	Set if the popup menu (or one of its parents) is not displayed in the "default" location (aligned with the right edge of the "parent" menu item) due to size constraints, this allows different styling in these cases	popup
header	Set on the menu item in the header section	menu-item
branding	Set on menu items in the branding section (normally just one)	menu-item
no-content	Set on items that don't have any content/submenu, this allows for styling these items differently	menu-item
all-siblings-childless	Set on menu items within a popup menu where none of the items in the menu has any content/submenu	menu-item