Customization Examples

The following sections describe several examples of how to customize Web Center. These examples range from very simple changes to Web Center layout to adding your own pages with new functionality.

Changing the JSP Page Layout

If the Web Center layout delivered with DirX Identity does not match your requirements, you can change the layout of the JSP pages.

The JSP pages for resulting HTML pages (that is, the view) are located in the WEB-INF/jsp/view directory of the installation.This directory contains the directories forms and tiles.The forms define complete pages, while tiles contain the "building blocks" for pages.

Common Layout Template layout.jsp

All JSP pages used by Web Center have a common basic tiles definition that is used to construct a final page with a set of page tiles.The item names used in the definition tag correspond directly with the layout template stored in the layout.jsp page that is located in the jsp/view/forms directory.

Inserting selected components from the jsp/view/tiles directory filled with dynamic content completes the view.To complete the page, the renderer implementation uses HTML and JavaScript code snippets from the WEB-INF/snippets folder, JavaScript files from the resources/build/scripts folder, and a cascading style sheet file stored in the resources/build/styles directory.Any graphics object is taken from the resources/images directory.

The layout chosen for the template conforms to the Fibonacci grid. The heights and widths, fonts, foreground and background colors of particular elements are defined in styles.css. Web Center delivers three different sets of cascading style sheets: small, medium and large. The user can select one in the sub-header part of each page.

The last tag inside the body tag of layout.jsp is <view:alert/>. This tag should not be removed, because it provides a message pop-up window when errors or notifications occur.

Changing the basic layout template can be a time-consuming task, since the entire body is an HTML table with partial percentage heights and widths. Removing an item may cause the page to be displayed incorrectly. Use an HTML analog and try the changes in an HTML editor before making any layout template modification.

The following sections provide a brief description of some of the styles as they are used in the Web Center configuration delivered with DirX Identity. You can add other styles for the individual design of controls. For the definition of style elements, see the books, articles and Web sites dealing with HTML on the Internet.

CSS Styles

Some styles in the style sheets differ between Internet Explorer and Firefox, some between Firefox 3 and later versions of Firefox.

The body element of each Web Center page has the HTML id “msie” in Internet Explorer, and “firefox” in other browsers (like Firefox and Chrome).

You can use this to define browser-dependent styles as shown in the following samples:

  • Style “#msie .labelCell“ applies to Internet Explorer.

  • Style “#firefox .labelCell” applies to all other browsers (like Firefox and Chrome).

Form Styles (styles.css)

.accountList

Form style for the account list (width).

.buttonGap

Space between last form field row and button row (padding).

.calWeekdayPanel

Layout for the calendar weekday panel (background-color, color, padding, font).

.calWindow

Basic layout of the calendar window (background-color and size).

.formLogin

Login form layout (width).

.imageButton

Image button layout (color, border, size). Used for the calendar button.

.labeledButton

Standard labeled button layout (background, border, color, cursor, font).

.pressedButton

Layout for a permanently pressed day button in the calendar panel (border, color, cursor, font).

.releasedButton

Layout for a released day button in the calendar panel (border, color, cursor, font).

.roLabel

Label layout for read-only text fields (border, color, font).

.rwLabel

Label layout for read-write text fields (border, color, font).

.roStringList

Layout for read-only string lists (background-color, border, color, font).

.rwStringList

Layout for read-write string lists (background-color, border, color, font, overflow, scrollbar).

.roTextField

Layout for read-only text fields (background-color, border, color, font).

.rwTextField

Layout for read-write text fields (background-color, border, color, font).

.roTokenString

Layout for read-only string lists (background-color, border, color, font, overflow).

.rwTokenString

Layout for read-write string lists (background-color, border, font, overflow).

.searchPanel

Layout for the search panel; that is, the panel containing the search controls (width).

.selfAssignList

Layout for the self-assignment list of roles or permissions (width).

.tableBody

Layout for the table body; that is, the area where all table rows are contained (background-color, overflow, scrollbar).

.tableBorder

Table border layout (border).

.tableHeaderCell

Layout for the header cells of a table (background-color, border-left, color, cursor, padding).

.tableInfo

Layout for the information field below a table (background-color, border, color, font).

.tableNavigationButton

Layout for the scrollbar buttons of a simple table (border, background-color, color, cursor, width).

.tableSelectedCell

Layout for the cell of a selected row of a table (background-color, border, color, cursor, padding).

.tableUnselectedCell

Layout for the cell of an unselected row of a table (background-color, border, color, cursor, padding).

.tabSelected

Tab layout for the selected tab button in a tab sheet (background).

.tab

Tab layout for unselected tab buttons in a tab sheet (background).

.tabDisabled

Tab layout for disabled tab buttons in a tab sheet (background, color)

.userList

User list form layout (width).

Page Styles (styles.css)

p,h1,h2,h3,h4,ul,
ol,li,div,td,th,
address,blockquote,
nobr,b,i

Predefined text styles.

.bcnFont

Font style for the bread-crumb-navigation text.

.bodyText

Style of the text used in the text-content tile.

.footerFont

Font style used for the text in the footer.

.footerLine

Layout for the footer’s horizontal line (padding, width).

Layout for the header area (background, padding, height).

.headlineText

Header font for the text-content.

.headerKeyVisual

Layout for the key visual in the upper-left corner of the page (size).

.leftContent

Style for the left content area (color and width).

.headerCompanyLogo

Layout for the company logo appearing in the header (height, padding).

.headerCompanyName

Layout for the company name appearing in the header (height, font, height).

Layout for the horizontal and vertical secondary-navigation bar, respectively (color and width).

a:link,a:visited,a:active

Style for anchors.

Adding Languages

DirX Identity Web Center is delivered with the languages en (English) and de (German).You can add additional languages to this set.

A language variant is stored in a separate directory identified by the locale name (en, de, fr, it, and so on).The language directory is found in the directory
WEB-INF/classes/resources/languages.

Content of a Language Directory

A language directory contains a set of .html and .jsp files and a text.properties file.The .html and .jsp files contain the pure informal text for the respective pages (which may be in most cases derived from the name), while the text.properties file contains all texts used in the forms and in common parts of all pages.

Using Language-Dependent Texts

Language-dependent texts of labels and messages are contained in the text.properties file. The file contains the text fragments as key/value pairs; the key represents the message identifier and the value represents the message text.

These texts can be accessed in the JSP pages in various ways:

Java Standard Tag Library (JSTL):

  • Using the JSTL tag <fmt:message>. You must include the fmt library into the JSP page as follows:

    <%@ taglib uri="http://java.sun.com/jstl/fmt" prefix="fmt" %>

Once you include this library, you can access any text.properties item to be used in a JSP page with the definition:

<fmt:message key="textKey"/>

where textKey is a valid key contained in the text.properties file and the tag is placed at exactly the position at which the text is required, since the tag is simply replaced with the key value. Use these keys also as error messages when developing controller JSP pages for forms and tiles configurations.

Web Center controller Library:

  • Using the tag <ctrl:setMessage> of Web Center controller tag library. The tag stores the message key and optional message parameters in session-scoped variables. The variables are evaluated later on by the <view:alert> tag that generates a Javascript message to be displayed when the response page is loaded into the browser. Include the tag into your page as follows:

    ++<++%@ taglib uri="http://www.siemens.com/directory/webManager/controller" prefix="ctrl" %++>++

Then you can include the text that corresponds to the given key with the following definition:

<ctrl:setMessage key="application.error.missingSurname"/>

  • A note about tag parameters:

Some tag implementations need to display labels or other text messages. Often they expect the message key as a parameter rather than the text fragment itself. See the respective tag library definitions in the DirX Identity Web Center Reference.

Using Text Files

The text files are included into a result page by tiles configuration. They are defined in the page attribute textFile:

<definition name=".typicalPage" extends=".base">
    <put name="bcn" value="login.title:/logout.do"/>
    <put name="formContent" value=".typicalPageForm"/>
    <put name="textFile" value="typicalPage.html"/>
</definition>

Adding a New Language

If you start with the English language, it is quite easy to add a new language to the Web Center by simply translating the key values in the text.properties file and the information texts contained in the .html and .jsp files.Do not touch the contained key names, because this can lead to erroneous output.

Store the translated files in a directory at the same level as the other language directories and give it the name of your locale.

For more detailed instructions refer to chapter “Adding Languages”.

Changing Attribute Lists in Pages

If you are satisfied with the default presentation and just want to display and modify some other attributes, you can simply change the form bean definitions.

Form beans are defined in files forms-config.xml as <form-bean> elements.A <form-bean> lists the attributes to be handled for the object in <form-property> child elements.For a property, you define its name, type, label and some other attributes as shown in the following excerpt for the property “c(ountry)”:

<form-property name="c"
               type="java.lang.String"
               label="ldap.attribute.c"
               readonly="true"
               width="100%" y="3" x="0"/>

Add and remove properties in the form bean definition as necessary.Make sure the properties exist in the DirX Identity domain with this name and type and are known to the respective object description.

Note that the label definition in the above sample can be omitted since the default label for a form property is “ldap.attribute.form property name”.

Removing Parts of the Default Application

Web Center ships with two application variants: A complete application that covers all management tasks and a self-service application.But what should you do if you just want to deploy part of the functionality?This section shows you how to perform this task simply by changing the configuration.For example, suppose we want to offer only role management in our application and strip out all the other functionality.This example also shows how to cut off part of the application.

Customizing the Context Configuration webCenter-domain.xml

First, deploy your new application in a separate folder.Copy the files from the default application to a new folder, for example, to a folder install_path/web/rolemanagement.

Next, provide a proper context configuration file and remove all Struts and form configuration files that you do not need.

In a Tomcat deployment, the default context configuration webCenter-domain.xml is located in the directory conf/Catalina/localhost.To create a separate application that is different from the delivered default, you can rename the context configuration, for example, to rolemanagement.xml.This action determines the context path for your new application: <http://localhost:8080/rolemanagement>.Change the context parameter docPath to point to the directory where you have copied your application files.

The parameter “Struts.Path” lists the folders containing the Struts and form bean configuration files for all your application modules. Keep only the folders you need. In our sample, these are /WEB-INF/config/imports, /WEB-INF/config/identity, /WEB-INF/config/privileges and /WEB-INF/config/privileges/roles.

Struts and Forms Configuration

Make sure that your application presents the proper start page at login. To accomplish this task, you need to change the settings in the Struts configuration file identity/struts-config.xml.

The action with which you want to start when the user has authenticated is defined as start action in file identity/menu-defs.xml. Change it to the search page for roles:

<definition name=".startActions">
	<put name="items" value=".menuRoleManagement:select"/>
</definition>

Then change the action “getStartAction” in identity/struts-config.xml accordingly:

<action path="/getStartAction" . . .>
    <forward name=".menuRoleManagement:select"
             path="/getRoles.do" redirect="true"/>
    <forward name="default"
             path="/logout.do" redirect="true"/>
</action>

If you want to clean the Struts configuration, remove all the action and form bean definitions you do not need. To keep the form bean definitions consistent, remove them in struts-config.xml and also remove the details in forms-config.xml.

Tiles and Menu Definitions

In addition to changing the form bean definitions, you also need to change the tiles and menu definitions. The most important task is to change the menus. Especially reduce the menu of administration operations displayed with nearly every page.

All the menus are defined in the central file identity/menu-defs.xml. The parts required for role management are “.menuRoleManagement”, “.contextMenuRoles”, “.toolbarRole” and “.toolbarRoles”. Keep also some basic definitions: “.menuSelectors”, “.menu”, “.menuLogout”, “.defaultMenubar” and “.startActions”. Remove all other definitons.

Then change the default menubar to

<definition name=".defaultMenubar">
	<put name="items"
        value=".menuRoleManagement;sep;menuLogout"/>
</definition>

Integrating Management of a New Object Type

This section shows you how to extend the default Web Center application with the management of a new object type – let’s say contracts.Contract management comprises:

  • Searching contracts.

  • Displaying data of a selected contract.

  • Modifying contract data.

  • Creating contracts.

  • Creating menus for contract management.

Since no special widgets are requested and all required operations are present in Web Center, the task only requires editing configuration files, namely struts-config.xml, tiles-defs.xml, forms-config.xml, and menu-defs.xml.

Creating Separate Configuration Files

Web Center offers the possibility of using multiple sets of configuration files struts-config.xml, tiles-defs.xml, forms-config.xml, and menu-defs.xml. In order to separate the customization from the original files as much as possible, we propose to create separate files for this customization task and store them in the directory WEB-INF/custom/config. This approach makes it easier to handle version upgrades.

We need to add a reference to the new configuration folder to the context configuration file webCenter-domain.xml:

 <Context docBase="@doc_path@" …
	<Parameter override="false" name="Struts.DefaultFiles"
		value="struts-config.xml:forms-config.xml:tiles-defs.xml menu-defs.xml"/>

	<Parameter override="false" name="Struts.Path"
		value="/WEB-INF/config/imports,
		       /WEB-INF/config/workflows,
…
		       /WEB-INF/config/bo/projects,
		       /WEB-INF/custom/config/contracts"/>

	<Parameter override="false" name="ObjectConfig.Path"
		value="/WEB-INF/config/objects-config.xml,
		       /WEB-INF/custom/config/objects-config.xml"/>
	<Parameter override="false" name="RendererConfig.Path" value="/WEB-INF/config/renderers-config.xml"/>

	<!-- Disable session persistence across application reloads and Tomcat restarts -->
	<Manager pathname=""/>
</Context>

In addition, we have to add our custom objects-config.xml file to the configuration (see above).

Searching Contracts

To create a new dialog for searching contracts, the following configuration entries are required:

  • The declaration of an action form (in our case, called “contractListForm”) in
    struts-config.xml.

  • The definition of an action “/getContracts” in struts-config.xml.

  • The definition of a page (in our case, “contracts”) containing header, footer, and the “contractsForm” (containing the contract list) in tiles-defs.xml.

  • The configuration of the contractListForm in forms-config.xml.

Struts-Config.xml

You must configure the action form and the necessary action mappings.

For the declaration of the action form you must add a form bean with a form name and the type “com.siemens.webMgr.model.DynaLocaleForm” to the form beans section:

<form-beans>
    <!-- ActionForm to handle a list contracts request -->
    <form-bean name="contractListForm"
          type="com.siemens.webMgr.model.DynaLocaleForm"/>
</form-beans>

Definition of the getContracts-Action:

<action-mappings>
<!-- Action to list contracts -->
<action path="/getContracts"
    type="com.siemens.webMgr.controller.action.JSPAction"
    name="contractListForm"
    parameter="jspPage:/WEB-INF/jsp/controller/core/listObjects.jsp;
    elements:contracts;
    selectSingleItem:true;
    excludeTopNodes:2;
    resetPoint:true;
defaultSearchBase:cn=Contracts,cn=Custom,cn=BusinessObjects,${initParam['com.siemens.webMgr.ldap.baseDN']};
    defaultFilter:(objectClass=dxrContext);
defaultNameRoot:cn=Contracts,cn=Custom,cn=BusinessObjects,${initParam['com.siemens.webMgr.ldap.baseDN']};
treeRootNode:cn=Contracts,cn=Custom,cn=BusinessObjects,${initParam['com.siemens.webMgr.ldap.baseDN']}">
	<forward name="cancel" path="/logout.do"/>
	<forward name="search" path="/getContracts.do"/>
	<forward name="selectContract"        path="/showContractData.do?ignoreSubmit=true"/>
	<forward name="tile" path=".contracts"/>
	<forward name="updateList" path=".updateContracts"/>
</action>
</action-mappings>

The action tag is configured by the attributes path, type, name and parameter:

  • Path - The action path (last part of the URL). The action is accessed by the URL http://*host:8080/webCenter-domain/getContracts.do*.

  • Name - The name of the form to be used.

  • Type - The Java action class com.siemens.webMgr.controller.action.JSPAction

  • Parameter - The Parameter list. JspPage references the JSP to be used to list the objects. The rest of the parameters are passed to the JSP as request parameters.

Five action forwards are defined for the action:

  • “search” is called if the search button is clicked on the search panel.

  • “cancel” is called if the request is cancelled.

  • selectContract” is called if a table entry is selected. The name is derived from the “elements” parameter entry: “select” + “Contract”.

  • “tile” references the whole page named “.contracts” in the tiles-defs.xml configuration file.

  • “updateList” is called in case only the result table of the search is refreshed.

Another Struts action is used to go back to the last search result. The action can be invoked from the main menu or from the toolbar on a contract’s overview page.

<action path="/lastSelectionContracts"
    type="com.siemens.webMgr.controller.action.JSPAction"
    parameter="jspPage:
        /WEB-INF/jsp/controller/tasks/lastSelection.jsp;
        elements:contracts">
    <forward name="tile" path="/getContracts.do"/>
</action>

Tiles-defs.xml

Three entries are required in tiles-defs.xml: one entry describing the page as a whole, a second entry describing the form dialog, and last not least an entry describing the list form.

The page as a whole is described by the entry named “.contracts”:

<definition name=".contracts" extends=".base">
<put name="formContent" value=".contractsForm"/>
<put name="textFile" value="custom/contracts/list.html"/>
</definition>

The definition extends a common “.base” definition, which is normally used for all pages with standard page layout. The <put> definitions override or set properties in the base definition:

  • formContent - references the Tiles definition of the content.

  • textFile - references a static HTML file that contains a comment for the user on how to use the form.

The form content “.contractsForm” is described by the following definition:

<definition name=".contractsForm" path="/WEB-INF/jsp/view/tiles/objectList.jsp">
<put name="action" value="/getContracts.do"/>
<put name="attributes" value="cn;dxrType::contractType;description"/>
<put name="form" value="contractListForm"/>
<put name="listPageSizeItems" value="default"/>
<put name="multiSelectionAllowed" value="true"/>
<put name="objectClasses" value="dxrContext"/>
<put name="objects" value="contracts"/>
<put name="selectedItemsAttribute" value="selectedContract"/>
<put name="size" value="15"/>
<put name="styleClass" value="fullWidthList"/>
<put name="targetId" value="contracts_table"/>
</definition>

This contracts form extends the “view JSP” objectLists.jsp, which is used for creating and managing the search panel. The specific parameters to be set are:

  • action - The default action.

  • attributes - The list of LDAP attribute names and labels to be displayed as search attributes.

  • form – A reference to the form bean definition in Struts configuration.

  • listPageSizeItems – The identifier for the value list of the list’s page size selector. The value must match a key listPageSizeItems.<value> in file webCenter.properties which defines the actual value list.

  • multiSelectionAllowed – A Boolean to turn on multi-selection in the table.

  • objectClasses – The object classes to be searched.

  • objects – the element name from object-config.xml extended by plural s

  • selectedItemsAttribute – The attribute of the HTTP session where the selected item is stored. It is used to pass the selection to further actions (such as edit or display).

  • Size – the number of rows to be displayed.

  • styleClass – a reference to a styles.css style.

  • targetId – A unique identifier for the result table, usually <objects>_table

The definition for the dynamic list update is described as follows:

<definition name=".updateContracts" path="/WEB-INF/jsp/view/tiles/updateList.jsp">
<put name="form" value="contractListForm"/>
<put name="listPageSizeItems" value="default"/>
<put name="multiSelectionAllowed" value="true"/>
<put name="objects" value="contracts"/>
<put name="selectedItemsAttribute" value="selectedContract"/>
<put name="size"  value="15"/>
<put name="tableRenderer" value="tableUpdate"/>
<put name="updateMenu" value="true"/>
</definition>

The parameters are widely the same as in the .contractsForm definition. In addition, the following parameters exist:

  • tableRenderer – The table renderer to be used for update: “tableUpdate”

  • updateMenu – a flag indicating the context menu has to be updated when the result table is updated.

Forms-config.xml

In the forms configuration file forms-config.xml we need to describe the form layout to display the search result in a <form-bean> element:

<!-- List contracts -->
<form-bean name="contractListForm">
<form-property name="contracts" height="239" width="510"
type="com.siemens.webMgr.model.DirectoryEntryBean[]" readonly="true"
openAction="/openContract.do:ContractMgt.summary" contextMenu=".contextMenuContracts:ms,list"
secondarySortColumns="$displayName,$parentFolder">
<data-property name="$displayName" label="contract.id" type="java.lang.String" cellRenderer="link"
width="20%"/>
<data-property name="$parentFolder" type="java.lang.String"
width="20%" cellRenderer="roDN" rendererProperties="includeNodes:[0,-1];link:true"/>
<data-property name="dxrVersion" label="ldap.attribute.dxrStartDate" type="java.util.Date" cellRenderer="time"
width="20%" />
<data-property name="description" type="java.lang.String" cellRenderer="link" width="40%"/>
</form-property>
<form-property name="selectedContract" type="java.lang.String" value="-1" transient="true" visible="false"/>
</form-bean>

The form property “contracts” is a pseudo-property that contains an array of DirectoryEntryBean objects. This is a special class to handle table rows. Its name is build from the object name in the objects-config.xml file, extended by a plural ‘s’. Height and width define the table size in pixels.

Each DirectoryEntryBean contains the information about one object that is returned by the search (in our case, contracts). The table columns are defined by using the data properties. For each data property, you define the following XML attributes:

  • name - the LDAP name of the contract’s attribute or a pseudo-attribute (starting with a ‘$’ character).

  • type - a Java class that represents the value. In this case, all values are single strings, so the type is “java.lang.String”.

  • label - the column label definition. It contains a key that references an entry in the language-dependent text properties files. If it is missing, the default key “ldap.attribute.<name>” applies.

  • width - the relative column width.

  • readonly - if true, the field does not accept any input.

  • cellRenderer - as a default, the text field renderer is used for the String type. The type “link” here does not permit editing the text but returns the index of the row when clicked. In our sample, the ldap attribute dxrVersion is used to hold the contract’s start date. Thus, the field renderer “time” has to be used.

The form property itself supports some additional attributes that apply to the entire table:

  • openAction – defines the action to be called when a table row is selected.
    In our sample, the open action is defined as follows in the struts-config.xml file:

    <action path="/openContract"type="com.siemens.webMgr.controller.action.JSPAction"
parameter="jspPage:/WEB-INF/jsp/controller/core/openEntry.jsp;entryType:contract">
<forward name="tile" path="/showContractData.do"/>
</action>

    This action sets the session variable holding the selection and then calls the action to display the contract using the “tile” forward.

  • contextMenu – references a definition of a context menu being displayed on the results table (see context menu definition below).

  • secondarySortColumns – specifies the secondary sort columns for each column; the primary sort criterion is the column itself.

Creating Menus and Static HTML Pages

At this point we still have some problems with our solution:

  • We do not want to enter the requested URL manually, but select the action from a menu instead. Therefore, we need to add a menu entry.

  • We have to add a static html file with information what to do on the page. If the file is missing, we will get an error message:

    “The requested resource ((/WebCenter/WEB-INF/classes/resources/languages/de/custom/contracts/list.html) is not available.” Reason: the static HTML page custom/contracts/list.html is missing.

Creating a Menu for Contract Processing

The menu is described in a file menu-defs.xml. We put the file into the same folder as the forms-config.xml, struts-config.xml, and tiles-defs.xml files.

The menu definition for the pull-down menu (from the menu bar) is

<definition name=".menuContractManagement" extends=".menu">
<put name="accessPolicyKey" value="ContractMgt"/>
<put name="msgPrefix"       value="contracts"/>
<put name="items" value="select:/getContracts.do;
lastSelection:/lastSelectionContracts.do:contractsFilter;
create:/createContract.do;
sep;
summary:/showContractData.do:selectedContract;
modify:/editContractData.do:selectedContract:mod"/>
</definition>
The menu .menuContractManagement has to be referenced from the .defaultMenubar definition being located in the /WEB-INF/config/identity/menu-defs.xml file

Creating Contract Context Menus

To create a context menu for the result list of contract search, the following menu definition is added to our menu-defs.xml file:

<definition name=".contextMenuContracts">
<put name="accessPolicyKey" value="ContractMgt"/>
<put name="msgPrefix" value="ctx.objects"/>
<put name="items"     value="summary;modify;
list;export"/>
</definition>

To get a context menu working, it has to be referenced from the form definition “contractListForm” in its contextMenu attribute.

In addition, an associated action "/contextMenuContracts" has to be defined in the struts-config.xml file, to connect the items with the actions:

<action path="/contextMenuContracts"
    type="com.siemens.webMgr.controller.action.JSPAction"
    parameter="jspPage:/WEB-INF/jsp/controller/tasks/contextMenu.jsp;
    selectedObject:com.siemens.webMgr.selectedContract">
<forward name="export"                 path="/exportContractList.do"/>
<forward name="modify"                 path="/editContractData.do"/>
<forward name="summary"                path="/showContractData.do"/>
</action>

This action has to use the JSP contextMenu.jsp.

Extending the Message Files

Do not forget to add the appropriate label keys and message texts into the message properties files. By default, these are:

  • “WEB-INF/classes/resources/languages/en/text.properties” and

  • “WEB-INF/classes/resources/languages/de/text.properties”.

It’s a good idea to put custom messages into separate files named

  • “WEB-INF/classes/resources/languages/en/text_en.properties” and

  • “WEB-INF/classes/resources/languages/de/text_de.properties”.

The following sample shows English message texts:

# The custom definitions start here

contract.id             = Contract

contracts.title         = Contracts
contracts.select        = Select contract
contracts.create        = Create contract
contracts.summary       = Show contract
contracts.modify        = Modify contract
contracts.lastSelection = &Last selection list: {30s}

searchPanel.title.contracts = Search contracts
form.title.data.contract    = Contract data
The message id contract.id is defined as a label in the forms-config.xml file. The main menu definitions above define message key prefix “contracts”. The message key for a menu item label is then comprised of prefix and item name, separated by a dot:

Label=<prefix>.<item>, for example “contracts.select“.

Note also that we defined additional messages for the title of the search panel for the contracts list, the overview form title and others which we will use later on.

Creating Static HTML Texts

The static HTML pages normally contain textual comment shown near the top of the page content beneath the header. These pages must be created for all supported languages; by default, English and German. We place them in the folders “WEB-INF/classes/resources/languages/en/custom/contracts” and “WEB-INF/classes/resources/languages/de/custom/contracts”.

As templates to copy, you can use the corresponding context text files, for example, “bo/contexts/list.html”.

Extending the Navigation History Control

We announce our new object type to the navigation history control in order to automatically get visited contract pages added to the navigation history. In file WEB-INF/config/webCenterCustom.properties, append the object type to the property with name “navigationHistory.conf.objects”:

navigationHistory.conf.objects = Contract

Displaying Contract Data

For this sample, we use a simplified variant of the existing form bean definition for the overviewContextForm.

Definitions in forms-config.xml

The dialog to display contract data is defined as follows:

<form-bean name="overviewContractForm">
<form-property name="$parentFolder" type="java.lang.String" transient="true"
	   fieldRenderer="roDN" rendererProperties="includeNodes:[0,-1]"
	   width="600" spanX="4" readonly="true" y="0"/>
<form-property name="$displayName" label="contract.id" type="java.lang.String" fieldRenderer="boldText" readonly="true"
	   width="100%" y="+1"/>
<form-property name="description" type="java.lang.String" readonly="true"
	   width="600" spanX="4" y="+1"/>
<form-import name="subjectModifyOrders"/>
<form-property-group name="operationalAtts" y="+1" spanX="4" groupRenderer="groupWithLabel"/>
<form-property name="owner" type="java.lang.String[]" fieldRenderer="userLinks" readonly="true"
	   width="100%" y="+1"/>
<form-property name="dxrVersion" type="java.util.Date" label="ldap.attribute.dxrStartDate" readonly="true"
   width="180" y="+1"/>
<form-property name="dxrState" type="java.lang.String" readonly="true"
	   width="180" y="+1"/>
</form-bean>

The $parentFolder pseudo-property contains the parent folder’s DN. It is rendered by the special fieldRenderer roDN. includeNodes defines which nodes of the DN are displayed. The first number gives the position of the first RDN, in this case 0 for the first RDN. The second number defines the position of the last RDN to display; negative numbers count from the end, so -1 is the second but last RDN. Note that the topmost node, the domain, is already stripped off by default due to setting dn.excludeTopNode to 1 in webCenter.properties and config.js.

The $displayName pseudo-property contains the value of the naming attribute, that is defined in the object description for contracts. In our case it is the contract’s cn. The cn’s default-label ldap.attribute.cn, evaluating to ‘name’, is overwritten with the label definition “contract.id”, evaluating to “contract” or “Vertrag”.

The description attribute is a standard X500 attribute, holding the contract’s description.

The property "subjectModifyOrders" is a pseudo-property. It is used to display active orders for subject modifications.

The property “owner” holds the contract owners.

The property “dxrVersion” is used in this sample to display the contract’s start date.

Last-not-least the property dxrState holds the object’s state.

Definitions in struts-config.xml

We define a new action showContractData the following way:

<action path="/showContractData"
type="com.siemens.webMgr.controller.action.JSPAction"
name="overviewContractForm"
parameter="jspPage:/WEB-INF/jsp/controller/ core/showData.jsp;
objectVar:selectedContract;
object:${sessionScope['com.siemens.webMgr.selectedContract']}">
<forward name="tile" path=".overviewContract"/>
</action>

We can use the existing “showData.jsp” to display the contract data. The DN of the selected contract is read from the session attribute ‘com.siemens.webMgr.selectedContract”. This corresponds to the element definition ‘contracts’ in the Struts configuration of the action “getContracts”.

Now we have to add the used form bean “overviewContractForm” to the form beans list at the top of the file:

<form-beans>
    …
    <form-bean name=" overviewContractForm"
          type="com.siemens.webMgr.model.DynaLocaleForm"/>
</form-beans>

Definitions in tiles-defs.xml

We need two entries in tiles-defs.xml: one that describes the page as a whole and one that describes the form dialog.

The page as a whole is described in the “.overviewContract” entry:

<definition name=".overviewContract" extends=".base">
<put name="formContent" value=".overviewContractForm"/>
<put name="textFile" value="custom/contracts/overview.html"/>
<put name="readonly" value="true"/>
</definition>

The following "put" parameters are to be set:

  • formContent – a reference to the Tiles definition form for the content.

  • textFile – a reference to a static HTML file that contains the comment for the user on how to use this form.

  • readonly - if true, the form does not accept any input.

The referenced form content is defined in the following “.overviewContractForm” entry:

<definition name=".overviewContractForm" path="/WEB-INF/jsp/view/tiles/form.jsp">
<put name="action"      value="/showContractData.do"/>
<put name="formTitles"  value="data.contract"/>
<put name="formToolbar" value=".toolbarContract"/>
<put name="styleClass"  value="overviewForm"/>
<put name="readonly"    value="true"/>
</definition>

and needs these "put" parameters:

  • action – a reference to the Struts action defined above.

  • formTitles – the message key for the form title.

  • formToolbar – the toolbar definition name from menu-defs.xml.

  • styleClass – a reference to a styles.css style.

  • readonly - the value true sets the read-only mode.

Modify a Contract

For contract modification, we need the appropriate form beans and actions for edit and save.

Definitions in struts-config.xml

We need to:

  • Define a form bean for the modification form (modifyContractForm)

  • Create an action to edit a contract: “editContractData”. We use “showData.jsp” to fill the form with the existing attributes.

  • Create a second action to edit a contract: “editContractData2”. This action is required when the owner is edited. In this case, another dialog to select the owner is displayed. After selecting the owner, process flow returns to “editContractData2”, being configured with clearForm:false. Thus, edits added to the form prior to editing the owner are not cleared when the modifyContractForm is displayed again. We use “showData.jsp” to fill the form with the existing attributes.

  • Create an action to store the contract in the Identity domain: “storeContractData”. We use “storeData.jsp” to save the modifications.

Here are the corresponding definitions:

<action path="/editContractData"
type="com.siemens.webMgr.controller.action.JSPAction"
name="modifyContractForm"
parameter="jspPage:/WEB-INF/jsp/controller/ core/showData.jsp;
operation:modify;
object:${sessionScope['com.siemens.webMgr.selectedContract']}">
<forward name="disallowed" path="/showContractData.do" redirect="true"/>
<forward name="tile" path=".modifyContract"/>
</action>

<action path="/editContractData2"
type="com.siemens.webMgr.controller.action.JSPAction"
name="modifyContractForm"
parameter="jspPage:/WEB-INF/jsp/controller/ core/showData.jsp;
operation:modify;
object:${sessionScope['com.siemens.webMgr.selectedContract']};
clearForm:false;attributes:!owner">
<forward name="disallowed" path="/showContractData.do" redirect="true"/>
<forward name="tile" path=".modifyContract"/>
</action>

<action path="/storeContractData"
type="com.siemens.webMgr.controller.action.JSPAction"
name="modifyContractForm"
parameter="jspPage:/WEB-INF/jsp/controller/ core/storeData.jsp;
objectVar:selectedContract;
object:${sessionScope['com.siemens.webMgr.selectedContract']}">
<forward name="owner"
path="/getUsersForObject.do?mainAction=/editContractData2.do&amp;forward=owner&amp;attributes=dn.owner[]"/>
<forward name="next" path="/showContractData.do" redirect="true"/>
<forward name="tile" path=".modifyContract" />
</action>

The contract object is again identified by the session attribute “com.siemens.webMgr.selectedContract”.

The action forward ‘owner’ at the ‘storeContractData’ action is called when the button to select a new owner is pressed. This is a property of the field renderer ‘userLinks’ being used to render the owner. The path attribute contains the action ‘getUsersForObject’, being used to search and select the owner. After this, process flow returns to the mainAction ‘editContractData2’, as already mentioned. The attributes-property defines that the selected user’s dn is stored in the contract’s owner attribute. The array brackets are used since here owner is multi-valued, i.e. the new or modified owner is added to the array of owners.

Finally, we have to add the used form bean “modifyContractForm” to the form beans list at the top of the file:

<form-beans>
    …
    <form-bean name="modifyContractForm"
          type="com.siemens.webMgr.model.DynaLocaleForm"/>
</form-beans>

Definitions in tiles-defs.xml

We need the two entries in tiles-defs.xml for the page as a whole and for the form dialog:

<definition name=".modifyContract" extends=".base">
<put name="formContent" value=".modifyContractForm"/>
<put name="textFile" value=" custom/contracts/modify.html"/>
</definition>

<definition name=".modifyContractForm" path="/WEB-INF/jsp/view/tiles/form.jsp">
<put name="action" value="/storeContractData.do"/>
</definition>
We use the action “storeContractData” to save the modifications. This action is called after the form is submitted by clicking Save or Cancel.

Definitions in forms-config.xml

For the modification form layout, we take the appropriate context modification form “modifyContextForm” as a template and change it:

<form-bean name="modifyContractForm"
buttons="dueDate.modify;enterConfirm:application.submit;resetConfirm:application.cancel">
<form-property name="$parentFolder" type="java.lang.String" transient="true"
fieldRenderer="roDN" rendererProperties="includeNodes:[0,-1]"
width="600" spanX="4" readonly="true" y="0"/>
<form-property name="cn" type="java.lang.String" mandatory="true" label="contract.id"
   width="100%" y="+1"/>
<form-property name="description" type="java.lang.String"
   width="600" spanX="4" y="+1"/>
<form-property-group name="operationalAtts" y="+1" spanX="4" groupRenderer="groupWithLabel"/>
<form-property name="owner" type="java.lang.String[]" fieldRenderer="userLinks"
   width="100%" y="+1"/>
<form-property name="dxrVersion" type="java.util.Date" label="ldap.attribute.dxrStartDate"
   width="180" y="+1"/>
<form-property name="dxrState" type="java.lang.String" readonly="true"
   width="180" y="+1"/>
</form-bean>
The form needs a Save and a Reset button. The dueDate.modify button is a button to enter a due date, to create a ticket for the modification. Since forms for simply viewing and for editing are defined separately, they may show a different layout with different attributes.

Creating a Contract

For creating a contract, we need to define the form beans for the creation form and actions to fill the form with default data and to create the contract object.

Definitions in struts-config.xml

We need to:

  • Define a form bean for the creation form (createContractForm)

  • Create an action “createContract” that uses “createObject.jsp” to fill the form with default data.

  • Create an action “createContract2” that uses “createObject.jsp” to create the account object.

<action path="/createContract"
    type="com.siemens.webMgr.controller.action.JSPAction"
    name="createContractForm"
    parameter="jspPage:
        /WEB-INF/jsp/controller/core/createObject.jsp;
        elements:contracts">
    <forward name="tile" path=".createContract"/>
</action>

<action path="/createContract2"
    type="com.siemens.webMgr.controller.action.JSPAction"
    name="createContractForm"
    parameter="jspPage:
        /WEB-INF/jsp/controller/core/createObject.jsp;
        clearForm:false;
        elements:contracts;
        selectedItemsAttr:selectedContract">
    <forward name="cancel" path="/getContracts.do"
        redirect="true"/>
    <forward name="owner"
        path="/getUsersForObject.do?
              mainAction=/createContract2.do&amp;
              forward=owner&amp;attributes=dn.owner[]"/>
    <forward name="show" path="/showContractData.do"
        redirect="true"/>
    <forward name="tile" path=".createContract"/>
</action>

The “createObjects.jsp” expects the following parameters:

  • elements – a reference to an entry in objects-config.xml. The object id is generated by removing the last character ("s" here). Thus, we reference a new entry ‘contract’ in the object-configs-xml file. It has the following definition:

    <object id="contract"
   nodeClass= "siemens.dxr.organization.nodes.SvcContext"
   set="Contexts"
   dirClass="Contract"
   def="false"
   policyType="Contract" />
    The name of the contract’s object description (in our sample ‘Contract’) has to be used for dirClass and policyType. />

  • clearForm - if set to false, the existing form contents is not cleared.

  • selectedItemsAttr - In this session attribute, the DN of the created object is stored for processing in the next actions.

    Once again, add the form bean to the list of form beans at the top of the file

<form-beans>
    …
    <form-bean name="createContractForm"
          type="com.siemens.webMgr.model.DynaLocaleForm"/>
</form-beans>

Definitions in tiles-defs.xml

We need the two entries in tiles-defs.xml for the page as a whole and for the form dialog:

<definition name=".createContract" extends=".base">
    <put name="formContent" value=".createContractForm"/>
    <put name="textFile"
         value="custom/contracts/create.html"/>
</definition>
<definition name=".createContractForm"
            path="/WEB-INF/jsp/view/tiles/form.jsp">
    <put name="action" value="/createContract2.do"/>
</definition>

Definitions in forms-config.xml

The form to create contracts can be derived from the modification form. The parent folder is made editable and assigned the field renderer “dn”. The due date button label is changed from dueDate.modify to dueDate.create. The dxrType attribute is omitted since it is read-only.

<form-bean name="createContractForm"
           buttons="dueDate.create;
                    enterConfirm:application.submit;
                    resetConfirm:application.cancel">
    <form-property name="$parentFolder"
        type="java.lang.String" transient="true"
        fieldRenderer="dn"
        rendererProperties="includeNodes:[0,-1]"
        width="600" spanX="4" y="0"/>
    <form-property name="cn"
        type="java.lang.String" mandatory="true"
        label="contract.id"
        width="100%" y="+1"/>
    <form-property name="description"
        type="java.lang.String"
        width="600" spanX="4" y="+1"/>
    <form-property-group name="operationalAtts"
        y="+1" spanX="4"
        groupRenderer="groupWithLabel"/>
    <form-property name="owner"
        type="java.lang.String[]"
        fieldRenderer="userLinks"
        width="100%" y="+1"/>
    <form-property name="dxrVersion"
        type="java.util.Date"
        label="ldap.attribute.dxrStartDate"
        width="180" y="+1"/>
</form-bean>

Configuring Access Policies

Creating contracts is subject to access control. As a result, you need to configure access policies that allows the appropriate users (for example, members of group “ContractAdmins”) to create, read and modify contracts.

The name of the object description of contracts (in our sample ‘Contract’) has to be used as object type in the access policies.