Universal dialog definition
- <universalDialog></universalDialog>
- Outer element for defining a Universal Dialog. The following tags
are allowed inside:
- resourceBundle
- Required: Specifies which resource bundle is used, it will be loaded at runtime and put under request attribute key ECToolsConstants.EC_UD_NLS, so that it can be accessed by all custom JSP segments. For example, common.sampleNLS
- finishURL
- (Optional. Stand-alone mode only) Specifies which command is to be executed to finish the universal dialog. For example, UDTestCmd
- formName
- Required: Specifies the HTML data input form name, it will be loaded at runtime and put under request attribute key ECToolsConstants.EC_UD_FORM, so that it can be accessed by all custom JSP segments. For example, inputForm
- tableProperty
- Optional: Specifies the HTML property for the page layout outer
table. For example,
border=0 cellpadding=1 cellspacing=0 - pageTitle
- Optional: Specifies the resource bundle key of the page title, using the resource bundle defined above. For example, pageTitle
- pageDescription
- Optional: Specifies the resource bundle key of the page description, using the resource bundle defined above. For example, pageDescription
- panelMode
- Optional: True or false. Specifies whether the Universal Dialog is rendered in panel mode. The default value is false, that is, the default is stand-alone mode.
- includeCalendar
- Optional: True or false. Specifies whether a calendar iframe will be included in the page. If not specified, the JSP will determine the value base on whether any date type element is used in the page or not.
- helpKey
- Optional: Specifies the help key when used in stand-alone mode, the key must be defined in the Tools User Interface Center help map XML file.
- <bean></bean>
- Optional: Specifies a data bean to hold user data and populate
the fields with existing data. If defined, this bean is instantiated
and if it is a smartDatabean, is activated when the universal dialog
loads. The bean instance is then put under a request object, so that
it is accessible by all custom JSP segments, where standard JSP bean
tags can be used, for example, <jsp:getProperty name="bean1"
property="timeStamp" />.
- id
- Required: Specifies the bean id. It must be a valid Java variable name. For example, bean1
- class
- Required: Specifies the bean class, for example, com.ibm.commerce.tools.test.UDBean1
- <include></include>
-
Optional: Specifies a JSP segment to be included in the output HTML page, right after the <BODY> tag. If needed, this is a good place to implement any Java or JavaScript/HTML code.
- page
- Required: Specifies the JSP file path and name, relative to the Web Application root path. For example,
- <jsFile></jsFile>
Optional: Specifies a JavaScript file to be included in the output HTML page. Multiple instances of this tag are allowed.
- src
- Required: Specifies the location of the JavaScript file. For example,
/wcs/javascript/tools/common/validator.js
Note: By default, the following JavaScript files are already included in the page. You do not need to include them explicitly:
- /wcs/javascript/tools/common/ConvertToXML.js
- Used to convert a JavaScript object to an XML string.
- /wcs/javascript/tools/common/validator.js
- Contains default common validators.
- /wcs/javascript/tools/common/DateUtil.js
- Contains calendar utility functions.
- <button></button>
Optional: Specifies an action button at the bottom of the page. Typically, this is only used in stand-alone mode.
- name
- Specifies the resource bundle key of the button display name. For example, ok.
- action
- Specifies the JavaScript method that executes when the button is clicked.
Note:
By default, two common resource bundle keys ("ok", "cancel") and their NL values are predefined for convenience. If you use either one of these, you don't need to specify it in your own resource bundle, although you can do so to overwrite the default values.
By default, two default implementations of the action functions are also predefined, finish() and cancelForm() for convenience. The first one will save the form data, and call the controller command if validation passes. If not, it will display all validation error messages in a popup dialog. The second function will prompt the user with a dialog asking whether s/he wants to continue. If yes, it will call the top.goBack() function to go back to the previous item in the bread crumb trail.
- <validator></validator>
- Optional: Specifies a global, page-level JavaScript validator function. The function is a custom validation function defined in either an included JavaScript file or a JSP custom segment. It is used to validate elements across sections.
- name
- Required: Specifies the JavaScript validation function name. For example, myGlobalValidator1.
- errorCode
- Required: Specifies the error code when validation fails. This value will be returned as part of the ValidationError() class in order to customize the validation handling function. For example, myError1.
- errorMsg
- Required: Specifies the resource bundle key of the error message when validation fails. errorMsg and errorCode can have the same value. For example, myError1.
- <parameters value="value" />
- Specifies any parameters to be used by the validation function. Multiple parameters are allowed, but be aware that the order of the <parameter> elements is important, as they are passed into the validator function in the specified sequence. For example, <parameter value="10" />
Note: All validators, including page-level, section-level and element-level, will be called before the data is submitted to the controller command, to validate the data on the page (and all panels if in panel model). If one or more validators return false, all errors including error source element, error code and error message are saved into a JavaScript array. The default implementation validateForm() will display all messages in a popup dialog. For advanced customization, developers can define their own finish action and get all validation errors from the getValidationErrors() function.
- <section></section>
- Required: Specifies a section, that is, a group of elements. The output page will be rendered based on the order of sections and their elements.
- name
- Required: Specifies the section name. This is also the ID of the section table, which can be used dynamically to hide/display the whole section using DHTML code. For example: sectionName.
- sectionTitle
- Optional: Specifies the resource bundle key of the section title label. In stand-alone mode, the title label is rendered as a heading that expands or collapses a section. If not specified, the section cannot be collapsed. In panel mode, this title label is displayed as the panel title. For example, section1.
- sectionDescription
- Optional: Specifies the resource bundle key of the section description text, displayed on the next line after the section title. For example, desc1.
- enabled
- Optional: Specifies whether this section is enabled. If false, all elements and validators defined inside this section are omitted. The default value is true.
- <validator></validator>
- Optional: Specifies a section-level JavaScript validator function. It acts exactly the same as the page-level validator described above, except that a section-level validator is NOT loaded if the section is marked as disabled (ie. section enabled="false"), while a page-level validator is always loaded
- <element></element>
- The <element></element> tags are used only within the <section></section> tags. Required: Specifies an input element within current section.
- name
- Specifies the element name within the HTML data form, this is also the request parameter name. For example, username.
- type
- Specifies the element type. For example, text.
Supported types are:
- hidden
- label
- text
- password
- button
- textarea
- radio
- checkbox
- checkboxgroup
- select
- date
- custom
- label
- Optional: Specifies the resource bundle key of the label for this element. For example, username.
- value
- Optional: Specifies the bean property to populate the input element. It takes the form of "<beanId>.<beanProperty>", the data bean id should be defined at the page level, as described above. The bean property getter method has to exist. If there is no such bean or method, or a null value is returned, an empty string is used for all text input fields, or the current date in the case of a date input element. Note that the button and custom element types do not need this value tag as they do not require value from the bean. For example, bean1.username.
- property
- Optional: Specifies the input element HTML property, which typically includes width, size and maxLength. For example,
- sameRowSpace
- Optional: Specifies whether the next element will be placed on the same row as the current element, and how much spacing (in pixels) should be used between these two elements. For example, 10. If not specified, all elements are assumed to be placed vertically, that is, the next element on a new row.
- page
- (Optional. Valid for type=custom only) Specifies the custom JSP segment file to be dynamically included. For example, /tools/common/UDSegment1.jsp
- horizontalMaxNumber
- (Optional. Valid for type=checkboxgroup only) Specifies whether check boxes in the group are placed horizontally and how many of them can be placed on the same row in maximum. For example, 3. If not specified, all check boxes in the group will be placed vertically, ie. each check box is on a new row.
- <validator></validator>
- Optional: Specifies an element-level JavaScript validator function.
The difference between this validator compared with page-level, and
section-level validators is that this validator always has the element
HTML value as the first input parameter to the validator function.
For example,
<validator name="validateIntRange" errorCode="invalidAge2" > <parameter value="1" /> <parameter value="100" /> </validator>For the preceding <validator> tags, the following call is made at runtime: validateIntRange(getData("age"),1,100).
Example
The following example defines a universal dialog:
<?xml version="1.0" encoding="UTF-8"?>
<universalDialog resourceBundle="common.sampleNLS"
finishURL="UDTestCmd"
formName="inputForm"
tableProperty="border="0" cellpadding="1" cellspacing="0""
pageTitle="pageTitle"
pageDescription="pageDescription"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../common/UniversalDialog.xsd" >
//The data beans are activated in step 3 of the runtime flow.
<bean id="bean1" class="com.ibm.commerce.tools.test.UDBean1" />
<bean id="bean2" class="com.ibm.commerce.tools.test.UDBean2" />
//defined JavaScript files are included in the output HTML page step 6 of the runtime flow.
<jsFile src="/wcs/javascript/tools/common/myUtil.js"/>
//These JSP pages are included in the output HTML page in step 7 of the runtime flow.
<include page="/tools/common/UDInit.jsp" />
//These sections display in step 8 of the runtime flow.
<section name="section1" sectionTitle="section1" sectionDescription="desc1" enabled="true" expand="true">
<element name="timeStamp"
type="hidden"
value="bean1.timeStamp" />
<element name="name"
type="text"
label="name"
value="bean2.name"
sameRowSpace="50"
property="size="40" maxlength="40"" >
//These validator functions and the others below run in step 10 of the runtime flow.
<validator name="wc_validateName" errorCode="invalidName1" errorMsg="invalidName1" />
<validator name="wc_validateUTF8length" errorCode="invalidName2" errorMsg="invalidName2" > Step 10
<parameter value="10" />
</validator>
</element>
...
</section>
<section name="section2" sectionTitle="section2" sectionDescription="desc2" enabled="true" expand="false">
...
</section>
//These buttons display in step 9 of the runtime flow.
<button name="reload" action="reloadPage()" />
<button name="ok" action="finish()" />
<button name="cancel" action="cancelForm()" />
//These validator functions and the others above run in step 10 of the runtime flow.
<validator name="myGlobalValidator1" errorCode="myError1" errorMsg="myError1" /> Step 10
<validator name="myGlobalValidator2" errorCode="myError2" errorMsg="myError2" />
</universalDialog>