Design Considerations for Form Fields

Design Questions

How should field values be obtained?

When designing form fields ask yourself these questions when deciding how to obtain values:

• Can the values be retrieved using a select expression applied to the current business object or relationship?

  If yes, this is the preferred mechanism. Use the Expression and Applies To parameters for the field.

• Is the value an image file?

  If yes, then use the Field Type=image and Image=FILENAME settings.

• Can the values be obtained using a JPO?

  If the values cannot be obtained using an expression or image file, then a JPO can be used. Use the Field Type=program or Field Type=programHTMLOutput setting and the program and function settings to specify the program and function names.

Who should have access to the field?

Define the users, groups, and roles who can access the field. Form fields have the same access checks as the other UI components.

Does the field need to be translated?

If so, the labels should be translated in the StringResource.properties file for the application as described in Internationalizing Dynamic UI Components. If the field's value is the name of an administrative object, policy state names, vault name, or ranges for an attribute, use the Admin Type setting.

When the Allow Manual Edit setting is true, the Admin Type is ignored.

How should the field be displayed on a View mode form?

• Should it be hyperlinked?

  If yes, then enter the URL to call when the field value is clicked in the href parameter. By default, the system passes the object ID for the current object to the called page.

  
  
  • Should the hyperlink pass the object ID for an alternate object?

    If yes, use the Alternate OID expression setting to specify the expression that gets the object(s) to pass.

  • Where should the href page be displayed?

    Use the Target Location setting to specify whether the page displays in a popup window, a slide-in frame, or in a specific frame of the current window. Use Popup Modal to control the modality of the popup window.

• Should it have a type icon next to it?

  If yes and the icon should reflect the current business object's type, use the Show Type Icon=true setting.

  If yes and the icon should reflect the type for an alternate business object, use the Show Alternate Icon=true and Alternate Type expression=EXPRESSION settings.

Should the field be editable?

If yes, add the Editable=true setting or do not specify the setting (it defaults to true). Then see the options listed below for editable fields.

If no, add the Editable=false setting.

If editable, what characteristics should the field have?

• What type of control should be displayed so users can enter or choose a value?

  Use the Input Type setting to specify the type of control, such as textbox, combobox, radiobuttons, etc. The default is textbox.

• If the control is a text box, should it have a Browse (...) button that calls a range helper window?

  If yes, use the RangeHref parameter to specify the page to appear in the window. This page can be a common chooser page included with the framework or a custom page. To define the height and width of the window, use the Popup Size setting.

• Should the editable field be required?

  If yes, add the Required=true setting. The field's label will be red and italic.

• Should the field values be validated?

  If yes and you want to use standard Javascript validation, use the format setting and specify the type of data, such as date, real, integer, text.

  If yes and you want to use a custom function to validate the data, use the OnChange setting.

• Is the field value an attribute or basic?

  If yes, use the Field Type=attribute or Field Type=basic setting so the system updates the database according to the type of value.

Entering Field Values Using Type Ahead

The Type Ahead feature stores text values entered in form text fields, then displays the most recent entries the next time that the user enters that field. They can then select from the list rather than needing to type the complete value or use a chooser.

Type ahead can be achieved using any of these methods:

• Custom JPO that retrieve the list of possible values for a field (described in this section).
• Advanced Search that uses emxFullSearch.jsp to retrieve possible values for a field. See Advanced Search Used for Type Ahead.
• Pre-defined Choosers for Person, Organization, or Type fields. See Pre-Defined Type Ahead Choosers.

If a field is defined with both a custom JPO and advanced search for Type Ahead, then the custom JPO is used.

When defining a field, you can:

• Enable or disable type ahead
• Override the number of values to save per context user, per field
• Define a JPO and method to retrieve values from the database (not those previously typed by the user) based on what the user starts typing
• If a JPO is used, override the number of characters a user must type before the JPO is triggered

The number of values stored for each user per field depends on the value for the emxFramework.TypeAhead.SavedValuesLimit property in the emxSystem.properties file. The default is 10 unique values and can be overridden at the field level using the TypeAhead Saved Values Limit setting. Duplicate values are discarded so that each of the values is unique. The values are stored in the order they are submitted so that the oldest item is removed when the list is full. Although stored in submitted order, the values are displayed in alphabetic order.

Set the emxFrameworkTypeAhead property in the emxSystem.properties file to true to enable Type Ahead for all fields on all forms. You can explicitly disable field settings by using the TypeAhead=false setting. List box, date, and multiline fields are not supported. If the system property is set to false, Type Ahead is disabled even if the field setting enables it.

To avoid conflicts with the browser's built-in auto-complete capability, the JPO must set the HTML autocomplete attribute to false.

Field values are stored in the Revision field of a workspace Cue object in an XML document. The naming format used for the Cue object is emx_form_formname. One cue object stores all values for the relevant fields on the specified form for the context user.

Cues apply to the current context, so a user only sees the values they enter. The cues are created in the inactive state.

Note: Cues are used by the ENOVIA Matrix Navigator and PowerWeb to provide visual signals for specific objects. If a type ahead cue is made active, it will have no affect. See the MQL Guide for complete details about cues.

When the user starts typing or double-clicks in the field, the page pops up the list of stored values. The user can:

• Continue to type to shorten the list until 1 remains.
• Use the cursor to click on the needed value.
• Use the up/down arrow keys to highlight a value, then press Tab or Enter, or click on the value.
• Press the Escape key to close the popup.

If the user types a value that does not match anything in the list, the popup closes.

If the field uses a JPO:method, the functionality is slightly different. The field pops up the list of recently-entered values as described above. When the user types something that does not match any of those values and exceeds the character count setting, the JPO is triggered to return the list of matching values. This process results in the list first showing several values, the number of values gets shorter as the user types, and then the list may get longer when the JPO method returns matching values.

To implement type ahead functionality, you need to define these settings on the field:

• TypeAhead=true|false. Enables type ahead. If not provided, automatically set to true. Typically used to disable type ahead for a field.
• TypeAhead Program. Name of the JPO called to retrieve a list of possible values. This JPO is called after the user types the specified number of characters. A JPO is typically used by fields that are normally populated using choosers.
• TypeAhead Function. The name of the JPO method used in conjunction with the TypeAhead Program setting.
• TypeAhead Character Count. Overrides the emxFramework.TypeAhead.RunProgram.CharacterCount system property. This setting may be useful for fields whose values may all contain the same prefix.
• TypeAhead Saved Values Limit. Overrides the emxFramework.TypeAhead.SavedValuesLimit system property.

You must also create the JPO and method called by the TypeAhead Program and TypeAhead Function settings.

Using Type Ahead in Custom Forms

If you want to implement the Type Ahead feature in a custom form, you can use the framework's tag library.

Use the typeahead:saveFieldValues tag in a processing page to save the field values. Use the typeahead:displayFieldValues tag to show the auto-complete behavior as described in Entering Field Values Using Type Ahead. You must also create the JPO and method that the tag calls. The format for the save tag is:

<emxUtil:saveTypeAheadValues

    context="<%= context %>"

    form="form1"

    field="field1"

    displayFieldValue="<%= tagDisplayValue %>"

    hiddenFieldValue="<%= tagHiddenValue %>"

    count="50"/>

<emxUtil:commitTypeAheadValues context="<%= context %>" />

Replace the italic text with the values for your custom form.The result of the display tag is a javascript array of the field values. It will also generate the javascript code that calls back to the server to execute the JPO if there is one. The format for the display tag is:

<emxUtil:displayTypeAheadValues

    context="<%= context %>"

    form="form1"

    field="field1"

    displayField="field1Display"

    hiddenField="field1"

    program="emxTypeField"

    function="genValues"/>

Units of Measure in Custom Forms

If you want to implement the units of measure (dimension) in a custom form, you can use the framework's tag library. See Units of Measure for Columns for details on using the UOMAttribute tag.

Entering URLs and mxLinks in Form Fields

When a field has the Dynamic URL setting set to enable, users can enter URLs or mxLinks in a create or edit form, and the system displays those values as hyperlinks in the view form. The valid URL formats are defined by the emxFramework.DynamicURL.Keywords parameter in the emxSystem.properties file.

The emxFramework.DynamicURLEnabled system parameter controls this feature. If enabled at the system level (in the emxSystem.properties file), it can be disabled for specific text fields by passing the Dynamic URL = disable setting (the default value is enable).

Dynamic URLs can be entered in any free-form text fields. Dynamic URLs cannot be entered in a field if:

• The Dynamic URL setting is set to disable (entered URL value will display as text)
• The Field Type setting is set to programHTMLOutput
• The Format setting is set to date or numeric
• Configured with businessobject or relationship expressions as attributes with datatypes Boolean, date/time, real, integer or associated with a dimension
• Configured with businessobject or relationship expressions as attributes with predefined fixed range values
• Configured with businessobject basic expressions as attributes (such as Type, Name, Rev, Vault, Owner) except Description

Users enter the URL in straight text, such as "http:\\server.com\abc.jsp?param=value" or www.enovia.com, and then the system converts the text to hyperlinks.

When Dynamic URLs are enabled, mxLink values are also enabled. Users can enter an mxLink value in a text box, and the framework converts that entry into a hyperlink. The user can type in the mxLink keyword and value, or search for the mxlink value. See Links to ENOVIA Objects for details on how a user enters the value.

The format entered in the text field is:

mxlink:<type>|<name>|<revision>|<vault>

For example:

mxLink:Part|Part-5000-01|0|eService Production 

This string is translated to a URL pointing to the default page for the object, such as:

http://server:8080/ematrix/common/
emxNavigator.jsp?objectId=32902.4369.56921.33541

and displays as a hyperlink such as:

Part Part-5000-01 0

When processing the <type> of an mxLink, ENOVIA Business Process Services uses the symbolic name (for example, type_Part), and looks up that symbolic name in the string resources properties file for the language the browser is set to and displays the internationalized name of the type. If the string resources properties file does not contain an entry for the type's symbolic name, then the type displays as entered.

SeeLinks to ENOVIA Objects for variations on this format, such as ommitting vault or revision, and using the latest revision identifier. If a user omits the vault or in the mxLink, the framework automatically adds the vault to the stored hyperlink. If a user omits the revision identifier, the framework automatically adds the latest revision identifier to the stored hyperlink.

On an edit page, if the field containing a dynamic URL or mxLink is defined as non-editable, then the field displays it as a link the same as on the view page.

When the user clicks Done on a page where an mxLink has been entered, the form validates the mxLink entries and displays an error message if any of the values could not be resolved. The user has the option of saving the form anyway, or canceling and fixing the error. If more than 10 errors are found, the message lists up to 10 errors and indicates there are additional errors.

Using Dynamic URL Links in Custom Pages

You can use the FormatURL taglib in any custom page or component. This taglib parses the provided text string and formats it as a hyperlink. This taglib can be used in freeform text fields.

The TagLib uses these parameters to configure the displayed converted data.

www.3ds.com

"http://server40:8080/ ematrix/common/
emxNavigator.jsp?suiteKey=Components& 
objectId=32902.4369.56921.33541"

mxLink:Part|P-5000-01|0

The syntax for this taglib is:

<framework:FormatURL

text="<text to be formatted>"

externalLink="<Yes or No>"

/>

See the following sections for more specific examples of this taglib's usage.

External URLs

When the text provided in the taglib code starts with any of the following strings, it will be formatted as a hyperlink:

• http://
• https://
• www.
• ftp.

The end of the URL is defined by a blank space.

If the URL is enclosed within double quotes, it can contain blank spaces. For example, this text string:

"http://myserver/abc.jsp?param1=value1&parm2=My Value2"

will be interpreted as

"http://myserver/abc.jsp?param1=value1&parm2=My%20Value2"

URLs are not case-sensitive.

URLs in Custom JSP Pages

For custom JSP pages, you can apply the dynamic URL feature to a description field. For example:

<tr><td class="label"><emxUtil:i18n localize="i18nId"> 
emxFramework.Basic.Description</emxUtil:i18n></td>

<td class="field"><framework:FormatURL text="<%=sDescAttr%>"/\></td>

</tr>

If the link opens an ENOVIA product page, the externalLink attribute is optional; if the link opens a page in an external application (such as an email application), then you should set externaLink = Yes.

Object LInks Using mxLink Keyword

The text of the FormatURL taglib can use the mxLink keyword with the name/type/revision information to define the link.

The syntax for this keyword is:

<framework:FormatURL

text=mxLink:<type>|<name>|<revision>

/>

You can use spaces between the colon and pipe characters. The revision is optional. If not provided, the taglib uses the latest revision of the object. If the type/name/revision is not unique because of vaulting setups, the first found object is selected.

For example, this code:

<framework:FormatURL

text=mxLink:Part|P-5000-01|0

externalLink="No"

/>

will show this as the label:

Part P-5001-01 0

with this as the HREF:

"http://server40:8080/ematrix/common/emxNavigator.jsp?suiteKey= 
Components&objectId=32902.4369.56921.33541"

You can also use the ObjectID with the mxLink keyword. This code produces the same results as shown above when providing the type/name/revision:

<framework:FormatURL

text=mxLink:32902.4369.56921.33541

externalLink="No"

/>

If the Type or Name includes the pipe character, you must use a double-pipe as the separator character. For example, mxLink:Part||Mfg Part|001||0 where Mfg Part|001 is the object name. You cannot mix single and double pipes as separators in the same string.