Utility Bar

The utility bar is the horizontal area between header and content area. It displays the navigation history, a quick search control and a link to an advanced search page.

Utility Bar

The standard Web Center application displays a control to search for users, and a link that leads to the user search panel. You can reconfigure the control to search for another type of object, like roles. And you can let the link point to another search panel.

Control and link are the same on each page of an application; they do not vary with the content of the main area.

The visibility of the utility bar may be controlled by a menu policy. For example, the standard utility bar is visible to users that are allowed to search for users via the main menu bar.

The visibility of the utility bar and its components is also controlled by some global properties in configuration file webCenter.properties.

Utility Bar Definition

The utility bar is defined in config/identity/tiles-defs.xml.The definition supports the following attributes:

  • navigationHistory – The Tiles definition name of the navigation history.

  • advancedSearch – The Tiles definition name of the advanced search link.

  • quickSearch – The Tiles definition name of the quick search link.

  • menuPolicyKey – The key of the menu policy controlling the visibility of the utility bar.

  • menuPolicyItem – The item of the menu policy controlling the visibility of the utility bar.

The Web Center provides quick search and advanced search definitions for users, roles, permissions and groups.

Sample

<definition name=".utilityBar"
            path="/WEB-INF/jsp/view/tiles/utilityBar/utilityBar.jsp">
    <put name="navigationHistory"  value=".navigationHistory"/>
    <put name="advancedSearch"     value=".usersAdvancedSearch"/>
    <put name="quickSearch"        value=".usersQuickSearch"/>
    <put name="menuPolicyKey"      value="UserMgt"/>
    <put name="menuPolicyItem"     value="select"/>
</definition>

Navigation History

The navigation history control allows the user return back to some pages that were displayed previously.The control displays just meaningful pages and is highly recommended to be used instead of built-in browser back navigation.

The navigation history control is defined in a Tiles definition file tiles-defs.xml.

The definition doesn’t support any attributes.

Sample

<definition name=".navigationHistory"
    path="/WEB-INF/jsp/view/tiles/utilityBar/navigationHistory.jsp"/>

Maximum Number of Items

The maximum number of items in the navigation history list is configured in
WEB-INF/config/webCenter.properties under key navigationHistory.maxItems.

navigationHistory.maxItems = <number>

Sample

navigationHistory.maxItems = 15

Configuring Tooltips and Labels

Tooltips and labels for the navigation history are configured in message file text.properties.

A general prefix for navigation history components to be used by accessibility tools to distinguish them from other page components:

navigationHistory.label         = History

The tooltips for the back button, the selection list and the forward button:

navigationHistory.label.back    = Go to previous page
navigationHistory.label.forward = Go to next page
navigationHistory.label.select  = Visited pages

The history item labels are automatically derived from the menu whenever possible. Other item labels must be explicitly configured:

navigationHistory.<actionName> = <item display text>

The action name is the name of the Struts action referenced by the history item.The message supports expressions that reference other message keys, as well as argument expressions similar to the main menu.Some examples are:

navigationHistory.listAccounts  = List accounts
navigationHistory.home          = ${home.home}
navigationHistory.resetPassword = ${users.resetPassword}: {30dn}
navigationHistory.runReport     = Run report: {30s}

Quick Search

A quick search control is defined in a Tiles definition file tiles-defs.xml.The definition supports the following attributes:

  • action – The Struts action to be invoked to perform the search operations (without leading slash).

  • objectClass – The object class for the search filter.

  • operand – The search filter operand.Supported values are “beginsWith”, “contains”, “endsWith” and “isPresent”.

  • attribute – The name of the filter attribute.You can specify a comma-separated list of attribute names for an “or”-filter.

  • type – The type of objects to be searched, like “users” or “roles”.Is used only to display type specific prompts, labels and so on.

Sample

The base quick search definition in WEB-INF/config/identity/tiles-defs.xml defines the JSP displaying the control and the default filter operand:

<definition name=".quickSearch"
            path="/WEB-INF/jsp/view/tiles/utilityBar/quickSearch.jsp">
    <put name="operand" value="beginsWith"/>
</definition>

The user quick search definition in WEB-INF/config/users/tiles-defs.xml is derived from the base definition. Therefore, it inherits filter operand “beginsWith”.

<definition name=".usersQuickSearch" extends=".quickSearch">
    <put name="action"      value="getUsers.do"/>
    <put name="attribute"   value="cn"/>
    <put name="objectClass" value="dxrUser"/>
    <put name="type"        value="users"/>
</definition>

The user quick search finds all users whose common name starts with the entered value.

If you change the definition to

    <put name="attribute"   value="sn,gn"/>

a quick search will return users whose surname or given name starts with the input value.

Configuring Tooltips and Labels

Tooltips and labels for the quicksearch control are configured in message file text.properties.

A general prefix for quicksearch components to be used by accessibility tools to distinguish them from other page components:

utility.quickSearch.label = Quicksearch

The label for the input field is not displayed but used by accessibility tools to create a distinct and meaningful name for the field:

utility.quickSearch.label.roles = Role name
utility.quickSearch.label.users = User

The initial text for the input field:

utility.quickSearch.prompt.roles = Enter role name
utility.quickSearch.prompt.users = Enter user name

The tooltip for the search button:

utility.quickSearch.title.roles = Search roles
utility.quickSearch.title.users = Search users

Advanced Search

The advanced search link is defined in a Tiles definition file tiles-defs.xml.The definition supports the following attributes:

  • action – The Struts action displaying the advanced search page (without leading slash).

  • label – The message key for the text for the link.

Samples

The base advanced search definition in WEB-INF/config/identity/tiles-defs.xml defines the JSP displaying the control and the default label:

<definition name=".advancedSearch"
            path="/WEB-INF/jsp/view/tiles/utilityBar/advancedSearch.jsp">
    <put name="label" value="utility.advancedSearch.label"/>
</definition>

The user advanced search definition in WEB-INF/config/users/tiles-defs.xml is derived from the base definition. Therefore, it inherits the label.

<definition name=".usersAdvancedSearch" extends=".advancedSearch">
    <put name="action" value="getUsers.do"/>
</definition>

Configuring the Link Text

The text for the advanced search link is configured in message file text.properties:

utility.advancedSearch.label = Advanced search

Global Options

The following options in file webCenter.properties control the visibility of the utility bar and its components:

  • utilityBar - Whether to display the utility bar.Default: true.

  • utilityNavigationHistory – Whether to display the navigation history control.Default: true.

  • utilityQuickSearch – Whether to display the quick search control.Default: true.

  • utilityAdvancedSearch – Whether to display the advanced search link.Default: true.

Sample

utilityBar               = true
utilityNavigationHistory = true
utilityQuickSearch       = true
utilityAdvancedSearch    = true