Web Center Menus

This chapter provides information about Web Center menus.

Menu Overview

This section provides an overview on Web Center menus.

Menu Access Policies

Menu access policies control access of a user to menus and menu items in the navigation bar, and to context menus and their items.

Menu access policies are no substitutes for operational access policies.They do not define which operations a user is allowed to perform, and on which objects.For example, a user may be granted access to the “modify role” menu item while not being allowed to modify any role at all.On the other hand, a user who is denied access to the “modify role” menu item might still be able to modify roles via other means like clicking a respective button or image, by being forwarded to the “modify role” page as result of another action, or by typing the “modify role” URL in his browser’s address bar.

Menu access policies are derived on the basis of object types (like “role”) but for performance reasons not on the basis of specific objects.That means, for example, if a user is granted access to the “delete role” menu item, he is able to select that item on any role, no matter whether or not he is actually allowed to delete it.

Note: Though menu access policies were designed to control access to menu items, they can sometimes be leveraged for different purposes as well. Web Center, for example, controls visibility of open buttons in tables via menu access policies. The <ctrl:checkAccessPolicy> tag allows for checking whether the logged in user is granted the right to a given menu item.

Navigation Menu

This section provides information about the navigation menu.

Menu Handling

The menus in the navigation bar can be operated by mouse and keyboard.

A menu is opened by clicking on its title, or by entering its access key. A menu access key is entered in Internet Explorer by pressing Alt + <key>, in Firefox by Shift + Alt + <key>. The keys are case insensitive. In Internet Explorer, menu access keys may override the browser’s own access keys. Firefox, in contrast, uses a different trigger for its own access keys.

Once open, you can browse thru the entire navigation bar by mouse movements or cursor keys (up, down, left, right).

Moving the mouse onto an item and clicking the main mouse button or pressing the RETURN key selects it. An item gets also selected by pressing its (case insensitive) access key.

A menu is closed by clicking somewhere outside the menu, or by pressing the ESCAPE key.

Menu Definition

A menu is defined in the application’s /WEB-INF/config/identity/menu-defs.xml file as a menu bar definition, for example

<definition name=".defaultMenubar">
    <put name=”items” value=”...”/>
</definition>

For details, see the chapter Menu Configuration in the DirX Identity Web Center Reference.

Menus may be also defined in additional menu-defs.xml files which must then be added to the application’s context descriptor file.

Menu Labels

A menu configuration contains message keys for menu titles and menu item labels. The message text may contain an ampersand indicating that the next letter should be used as access key for that menu or item.

Access keys are case insensitive. Do not use the same access key for more than one menu, or for more than one item in a menu.

A message text may contain a placeholder to be replaced at runtime by the value of the session variable defined in the menu item’s attribute session variable. The supported placeholder formats are

  • {[n]s} – String; the variable value is converted to a string which is substituted for the placeholder. An optional number defines the maximum number of characters to substitute.

  • {[n]dn} – DN; the variable value is expected to be a distinguished name. The placeholder is substituted by the value of the first RDN. An optional number defines the maximum number of characters to substitute.

Samples:

The following lines define the title (with access key “r”) and two items (with access leys “l” and “d”, respectively) for a menu:

roles.title			= &Roles
roles.lastSelection	= &Last selection list: {30s}
roles.summary		= &Display summary: {30dn}

With variable values

  • "(cn=sa*)" and

  • "cn=Sales Tasks,cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company"”",

the item labels resolve to

  • "&Last selection list:(cn=sa*)" and

  • "&Display summary: Sales Tasks",

respectively.

Navigation Bar Location

Web Center supports horizontal menus spanning one or two rows, and vertical menus. The layout JSPs contain definitions for both, horizontal and vertical menus, and switch between them based on a configuration parameter in webCenter.properties.

The JSP “/WEB-INF/jsp/controller/view/tiles/header/header.jsp” defines two tables each containing a single row with id “menubar” and “menubar2”, respectively, the designated location for the horizontal menu:

<table cellpadding="0" cellspacing="0">
    <tr id="menubar" role="menubar"/>
</table>
…
<table cellpadding="0" cellspacing="0">
    <tr id="menubar2" role="menubar"/>
</table>
The id of the second row must match the id of the first one, followed by number 2.

The JSP “/WEB-INF/jsp/controller/view/layoutPage.jsp” defines a table containing a tbody element with id “menubar”, the designated location for the vertical menu:

<table cellpadding="0" cellspacing="0">
    <tbody id="menubar" role="menubar"></tbody>
</table>

Assigning a Menu to a Navigation Bar

For the horizontal menu, the header layout JSP “/WEB-INF/jsp/controller/view/tiles/header/header.jsp” invokes the <view:menu> tag assigning the menu bar with name “.defaultMenubar” to the table row with id “menubar”:

<view:menu menubarId="menubar" definition=".defaultMenubar"/>.

For the vertical menu, the JSP “/WEB-INF/jsp/controller/view/layoutPage.jsp” invokes the tag with attribute vertical set to “true”:

<view:menu menubarId="menubar" definition=".defaultMenubar" vertical=”true”/>

The tag is also invoked at other times in order to update the menu during asynchronous requests that update only the content area of a Web Center page. Such requests may have an impact on the menu for example by changing entry selection.

Generated Javascript Code

The tag generates Javascript code that is inserted into the response sent to the browser, like:

<script ...>menu.init("menubar","/webCenter/",”menu”,[...])</script>

The first argument is the navigation bar’s table row id. It tells the browser where to place the menu bar.

The second argument is Web Center’s context path, used when sending a request on selection of an item.

The third argument defines a prefix for the menu and menu item labels which is used by accessibility tools to indicate that a label belongs to a menu.

The fourth argument is an array representation of the menu bar. The labels and confirmation messages are localized, message arguments substituted by their actual values.

The optional fifth argument, a boolean, indicates whether to display a vertical (true) or horizontal menu (false); its default value is false.

Menu Display

The browser executes the menu.init function, creates the corresponding DOM elements, resolves ampersands in labels to access keys, and handles events like opening a menu or selecting an item. The menu layout is affected by several CSS classes defined in /resources/build/styles/<fontSize>/styles.css.

Requests on Menu Selection

On selection of a menu item, the browser sends a request for the action configured for that item in menu-defs.xml. The request includes several HTTP parameters:

  • The parameter “startAction” with value “true” is evaluated by the JSP checkSession.jsp and initiates a session clean-up.

  • The parameter “WT” is used for CSRF prevention.

  • The parameter “ajax” specifies whether the request should update the entire HTML page or just the content area.

  • The parameter “actionConfirmed” specifies whether the end user confirmed the request (for example a request to delete some entries).

The item definition

modify:/editUserData.do:selectedUser:mod

in menu-defs.xml, for example, corresponds to the request URI

http://localhost:8080/webCenter/editUserData.do

Context Menus

Context menus apply to tables.

A context menu is comprised of three sections. The methods in the first section apply to the visually highlighted entry (see below), the methods in the second section are applied to all selected table entries (for tables with selection checkboxes only), and the methods in the third section apply to the entire table. All sections are optional.

Context menus can be assigned to most tables, including search result lists and tables displaying attributes of an entry, like a user’s roles or a group’s members. There are, however, some exceptions where context menus conflict with other table features, e.g. during delegation. And attribute tables do not support methods that apply to the selected entries or the entire table.

Context Menu Handling

You can display and select context menus with the mouse only.

Placing the cursor on a table entry and clicking the context menu mouse button opens a context menu. The table entry is visually highlighted as long as the context menu is open. Note that the highlighted entry gets not automatically selected, that is the items in the second section apply to it only if its selection checkbox is ticked.

Once open, you can browse through the context menu by mouse movements. Moving the mouse onto an item and clicking the main mouse button select it. A context menu is closed by clicking somewhere outside the menu or by hitting the escape key.

Context Menu Definition

Context menus are defined in the application’s /WEB-INF/config/identity/menu-defs.xml file, for example

<definition name=".contextMenuRoles">
    <put name="accessPolicyKey"	value="RoleMgt"/>
    <put name="msgPrefix"		value="ctx.objects"/>
    <put name="items"  			value="summary;modify;sep;
									assignPrivileges;assignUsers;unassignUsers;sep;
									runReport;
									ms;delete:confirm.roles,dueDate.delete;
									list;export”/>
</definition>

For details, see the chapter Menu Configuration in the DirX Identity Web Center Reference.

Note that simply switching an item from one section to another will usually not work since the underlying Struts action must support the respective entry set (highlighted entry, selected entries or entire table).

Context menus may be also defined in additional menu-defs.xml files which must then be added to the application’s context descriptor file.

Context Menu Assignments

A context menu is assigned to a table in the attribute contextMenu of the table’s <form-property> element within a forms-config.xml file. The assignment includes the context menu name, and flags to enable the second and third menu section (if applicable). By default, only the first section is enabled. The same context menu can be assigned to different tables, and with different flags.

The following example assigns the first section of the context menu with name ".contextMenuRoles”:

<form-property name="assignedRoles”
    type="com.siemens.webMgr.model.DirectoryEntryBean[]" ...
    contextMenu=".contextMenuRoles">

The following example assigns all sections of the context menu with name ".contextMenuRoles":

<form-property name="roles"
    type="com.siemens.webMgr.model.DirectoryEntryBean[]" ...
    contextMenu=".contextMenuRoles:ms,list">

Generated Javascript Code

The Javascript representation of a context menu is a Javascript array generated as part of the code for the table and inserted into the response sent to the browser.

The HTML code snippet “WEB-INF/snippets/simpleTable/table.htm” for the table includes a placeholder for the context menu.

<script>
    new Table ("${name.id}",${size.jsInt},...,${contextMenu.jsArr},...)
</script>

At runtime, the placeholder is replaced by the Javascript array. The labels and confirmation messages are localized.

<script>
    new Table ("roles",15,...,
    ['contextMenuRoles.do',
        ['Entry','E'],['Display summary','summary'],['Modify data','modify'],[],
        ['Assign privileges','assignPrivileges'],
        ['Assign users','assignUsers'],['Remove users','unassignUsers'],[],
        ['Run report','runReport'],
        ['Selected entries','S'],['Delete','delete','Delete the selected roles?',1,0],
        ['List','L'],['Export','export']],...)
</script>

The first array item denotes the Struts action that handles requests initiated via the context menu, in this case “contextMenuRoles.do”. Usually, this is just the context menu name, without leading dot but with extension “.do”.

Each other array item comprises the label of a menu section header or item, a forward and, optionally, a confirmation message text, the index of the default button of the confirmation box, and the due date enabled flag. Some special forwards (E, S and L) are used to denote the section headers. Empty arrays denote separators.

Context Menu Display

The browser creates the new table. On context menu activation, it creates the corresponding DOM elements, displays the menu, and handles events like item selection. The context menu layout is affected by several CSS classes defined in /resources/build/style/<fontSize>/styles.css.

Requests on Context Menu Selection

On selection of a context menu item, the browser sends a request for the action configured for that item in menu-defs.xml. The request parameters depend on the subset of entries the item is applied to.

  • Entry – The request includes the following parameters:

  • dn – The DN of the highlighted entry.

  • forward – The item forward, the value of the item’s label attribute in the menu configuration.

  • startAction – With value “true”. The parameter is evaluated by the JSP checkSession.jsp and initiates a session clean-up.

  • Selected Entries – The request includes the following parameters:

  • forward – The item forward, the value of the item’s label attribute in the menu configuration.

  • <selectedItems> – The indexes of the selected items. The exact parameter name depends as usual on the table definition.

  • startAction – With value “false”. The parameter is evaluated by the JSP checkSession.jsp. In this case, it prevents a session clean-up since the table is stored in session-scope and used to handle the request.

  • List – The request includes the following parameters:

  • forward – The item forward, the value of the item’s label attribute in the menu configuration.

  • startAction – With value “false”. The parameter is evaluated by the JSP checkSession.jsp. In this case, it prevents a session clean-up since the table is stored in session-scope and used to handle the request.

Context Menu Handler Actions

Struts actions handling requests initiated by context menus usually forward to the action JSP “/WEB-INF/jsp/controller/tasks/contextMenu.jsp” and define the name of the session-scoped variable that contains the selected entry.

The JSP simply assigns the value of request parameter “dn” to that variable, and forwards to the value of request parameter “forward”. Therefore, the labels used in the context menu configuration must match the action forwards of the Struts action.

The following sample shows the action handler for the roles context menu:

<action path="/contextMenuRoles"
        type="com.siemens.webMgr.controller.action.JSPAction"
        parameter="jspPage:/WEB-INF/jsp/controller/tasks/contextMenu.jsp;
        selectedObject:com.siemens.webMgr.selectedRole">
    <forward name="assignPrivileges"	path="/assignRolePrivileges.do"/>
    <forward name="assignUsers"		    path="/usersToRole.do"/>
    <forward name="delete"		    	path="/deleteSelectedRoles.do"/>
    <forward name="export”			    path="/exportRoleList.do"/>
    <forward name="modify"		        path="/editRoleData.do"/>
    <forward name="runReport"	    	path="/runReportForRole.do"/>
    <forward name="summary"		        path="/showRoleData.do"/>
    <forward name="unassignUsers"	    path="/usersFromRole.do"/>
</action>