Class idx.app.Header

Extends dijit._TemplatedMixin, dijit._Widget.
The Header widget generates the HTML and CSS to provide an IBM One UI header according to the design specification and templates.

To construct a header, initialise the widget with the required properties. The appropriate HTML and CSS is created immediately, and subsidiary dijit components may be created and marshalled. No dynamic layout is performed: once the HTML has been injected into the DOM, all layout is delegated to the renderer and associated CSS rules.

Defined in: <idx\app\Header.js>.

Constructor Summary

Constructor Attributes	Constructor Name and Description
	idx.app.Header() Creates a new idx.app.Header

Field Summary

Field Attributes	Field Name and Description
	actions An array of objects defining actions which will be displayed as action buttons in the context part of the header.
	additionalContext Text containing additional context information, such as when page content was last updated and by whom.
	baseClass The base CSS class for the widget.
	contentContainer The id of a content container which is to be controlled by tabs included in the header, or the widget itself.
	contentTabsInline If true, content tabs will be placed on the same line as a context title and/or other secondary banner content.
	help A dijit.Menu to be used as the popup of available site help actions.
	layoutType Specifies the desired layout mode, which can be "fixed" for a fixed-width layout independent of the browser width (extra space will be left at the side margins, and a scroll bar will appear if the browser window is too narrow) or "variable" for a variable-width layout that exploits the full browser window width (extra space will be left within the layout, which will change as the browser window is resized).
	navigation A menu bar, which can contain items and popup menu items, which will be displayed as navigation actions/menus in the header.
	primaryBannerType The desired style of primary (black) banner: "thick" or "thin".
	primarySearch Specifies that a primary search box should be included in the header, and supplies the parameters for it.
	primaryTitle The IBM Brand/product name.
	secondaryBannerType The desired style of secondary (context) banner: "blue" or "lightgrey".
	secondarySearch Specifies that a secondary search box should be included in the header, and supplies the parameters for it.
	secondarySubtitle A subtitle which gives additional context information.
	secondaryTitle The context title which shows users where they are, for example if they have arrived here by selecting a menu item.
	settings A dijit.Menu to be used as the popup of available site settings actions.
	showHelpDropDownArrow True (the default) if a drop-down arrow affordance is to be shown on the site help icon when a popup menu of site help items is supplied.
	showNavigationDropDownArrows True (the default) if navigation menu items that have a popup menu associated with them are to show a drop-down arrow affordance.
	showSettingsDropDownArrow True (the default) if a drop-down arrow affordance is to be shown on the site settings icon when a popup menu of site settings items is supplied.
	showUserDropDownArrow True (the default) if a drop-down arrow affordance is to be shown on the user identification when a popup menu of user actions is supplied.
	user The identity of the user to be included in the header.

Method Summary

Method Attributes	Method Name and Description
	addChild(child) Overridden so that the child is run through setup after being added and a refresh is triggered or at least a flag is set indicating it is needed.
	deferRefresh() Sets the flag to defer refresh.
	destroy()
	getTextBoxWidget(isSecondary) Return the textbox widget.
	refresh() Clears the refresh deferral flag and refresshes the header.
	removeChild(child) Overridden to handle the special children so as to clear out help, navigation, or settings as needed.

Constructor Detail

idx.app.Header()

Creates a new idx.app.Header

var hdr = new idx.app.Header({ primaryTitle: "Hello" }, "myHeader");

Field Detail

{Object[]} actions

An array of objects defining actions which will be displayed as action buttons in the context part of the header. Each object must contain the following properties:

label: text label for the action
onClick: click handler for the action button

{string} additionalContext

Text containing additional context information, such as when page content was last updated and by whom.

baseClass

The base CSS class for the widget.

{string | dijit.StackContainer} contentContainer

The id of a content container which is to be controlled by tabs included in the header, or the widget itself. Each ContentPane in the StackContainer may additionally include the following properties (all optional):

closable: {boolean} If true, a close affordance will be displayed on the corresponding tab and will close the content pane when activated. If false, or if this property is not set, no close affordance is shown.
actions: {dijit.Menu} A menu of items to be presented when the drop-down affordance on the tab is activated. The drop-down affordance will be displayed on the tab if this property is set and either the tab is selected or alwaysShowMenu is true.
alwaysShowMenu: {boolean} If true, a drop-down affordance will be displayed on the tab if the actions property has been set, regardless of whether the tab is currently selected. If false, a drop-down affordance will only be displayed on the tab if the actions property has been set AND the tab is currently selected.

{boolean} contentTabsInline

If true, content tabs will be placed on the same line as a context title and/or other secondary banner content. If false, the tabs will occupy their own row within the secondary banner. The default value is false.

{dijit.Menu | dijit.MenuItem} help

A dijit.Menu to be used as the popup of available site help actions. If a single dijit.MenuItem is supplied, a simple site help action will be presented and onClick will be triggered on the menu item when that action is selected.

{string} layoutType

Specifies the desired layout mode, which can be "fixed" for a fixed-width layout independent of the browser width (extra space will be left at the side margins, and a scroll bar will appear if the browser window is too narrow) or "variable" for a variable-width layout that exploits the full browser window width (extra space will be left within the layout, which will change as the browser window is resized).

Default Value:: "variable".

{string | dijit.MenuBar | DOMNode} navigation

A menu bar, which can contain items and popup menu items, which will be displayed as navigation actions/menus in the header. The menu bar may be supplied as an instance or by id or as a DOM node.

{string} primaryBannerType

The desired style of primary (black) banner: "thick" or "thin".

Default Value:: "thin"

{Object} primarySearch

Specifies that a primary search box should be included in the header, and supplies the parameters for it. All the properties are optional:

entryPrompt: {string | function} A string containing the prompt text for entering the search terms, or a function (which will be called with no arguments) which returns the prompt text.
submitPrompt: {string | function} A string containing the prompt text for submitting the search, or a function (which will be called with no arguments) which returns the prompt text.
onChange: {function} A function which will be called whenever the text in the search box changes. The function will receive one argument, which is the text currently in the search box.
onSubmit: {function} A function which will be called whenever the user submits a search (eg, by pressing enter, or activating a search affordance). The function will receive one argument, which is the text currently in the search box.

{string} primaryTitle

The IBM Brand/product name.

{string} secondaryBannerType

The desired style of secondary (context) banner: "blue" or "lightgrey".

Default Value:: "blue"

{Object} secondarySearch

Specifies that a secondary search box should be included in the header, and supplies the parameters for it. All the properties are optional:

entryPrompt: {string | function} A string containing the prompt text for entering the search terms, or a function (which will be called with no arguments) which returns the prompt text.
submitPrompt: {string | function} A string containing the prompt text for submitting the search, or a function (which will be called with no arguments) which returns the prompt text.
onChange: {function} A function which will be called whenever the text in the search box changes. The function will receive one argument, which is the text currently in the search box.
onSubmit: {function} A function which will be called whenever user submits a search (eg, by pressing enter, or activating a search affordance). The function will receive one argument, which is the text currently in the search box.

{string} secondarySubtitle

A subtitle which gives additional context information.

{string} secondaryTitle

The context title which shows users where they are, for example if they have arrived here by selecting a menu item.

{dijit.Menu | dijit.MenuItem} settings

A dijit.Menu to be used as the popup of available site settings actions. If a single dijit.MenuItem is supplied, a simple site settings action will be presented and onClick will be triggered on the menu item when that action is selected.

{boolean} showHelpDropDownArrow

True (the default) if a drop-down arrow affordance is to be shown on the site help icon when a popup menu of site help items is supplied. If false, a drop-down arrow is not shown on the site help icon.

{boolean} showNavigationDropDownArrows

True (the default) if navigation menu items that have a popup menu associated with them are to show a drop-down arrow affordance. If false, drop-down arrows are not shown on navigation items.

{boolean} showSettingsDropDownArrow

True (the default) if a drop-down arrow affordance is to be shown on the site settings icon when a popup menu of site settings items is supplied. If false, a drop-down arrow is not shown on the site settings icon.

{boolean} showUserDropDownArrow

True (the default) if a drop-down arrow affordance is to be shown on the user identification when a popup menu of user actions is supplied. If false, a drop-down arrow is not shown on the user identification.

{Object} user

The identity of the user to be included in the header. All properties are optional.

displayName: {string | function} A string containing the displayable name of the current user, or a function (which will be called with no arguments) which returns the displayable name of the current user. The displayable name may include mark-up (for example, entities for accented characters, etc). A displayName should always be supplied whenever feedback of the user's identity is required. The displayName can be modified after construction by setting the "userDisplayName" property of the header. Examples: "Clark, D. J. (Dave)"
displayImage: {string | Object | function} A string containing the URI of an image to be displayed alongside the user name or welcome message, or an HTML image object (or other suitable mark-up object) to be used as the image alongside the user name or welcome message, or a function (which will be called with no arguments) which returns either a string or an object to specify the image to use. If omitted, null or undefined, no image is shown. The displayImage can be modified after construction by setting the "userDisplayName" property of the header.
messageName: {string | function} A string containing the displayable name of the current user as it should appear in the message shown in the header to confirm the user's identity, if that is different from the displayName (for example, a shortened or simplified form of the user's name might be used as the messageName). If messageName is not supplied, the displayName is used. Note that displayName should still be supplied as well as messageName, because although it is the messageName that is substituted into the message for display, the displayName is also added as alternative text/title to add clarity for the user. The messageName can be set or modified after construction by setting the "userMessageName" property of the header. Examples: "Dave", "Noël"
message: {string | function} A string containing the message to be shown in the header to confirm the current user's identity, or a function (which will be called with no arguments) which returns the message to be shown. The string pattern will have the following substitutions applied:
- ${messageName} - the message name of the current user, if supplied, othewise the display name is used, if supplied
- $(displayName} - the display name of the current user
The message may include mark-up (for example, entities for accented characters, etc). If message is not supplied, the message that is used is "${messageName}". The message can be set or modified after construction by setting the "userMessage" property of the header. Examples: "Welcome back, ${messageName}", "Welcome, new user"
actions: {string | dijit.Menu | dijit.MenuItem} A dijit.Menu to be used as the popup of available actions for the current user. If a single dijit.MenuItem is supplied, the current user name will be presented as a simple action and onClick will be triggered on the menu item when that action is selected. The menu or item may be supplied as an instance or by id.

Method Detail

addChild(child)

Overridden so that the child is run through setup after being added and a refresh is triggered or at least a flag is set indicating it is needed.

Parameters:
child

deferRefresh()

Sets the flag to defer refresh. This means that changes to the header will not immediately change the header but rather a call to "refresh()" will be required to trigger a change.

destroy()

getTextBoxWidget(isSecondary)

Return the textbox widget.

Parameters:
{boolean} isSecondary: indicating which widget should be returned the primary textbox or the secondary textbox

refresh()

Clears the refresh deferral flag and refresshes the header.

removeChild(child)

Overridden to handle the special children so as to clear out help, navigation, or settings as needed.

Parameters:
child