The Web Editor Tag Libraries
Reference Documentation
Ontopia 5.1 2010-06-09
Introduction
This tag library is used to produce HTML forms from topic map data and to map the information entered into those forms back into actions that cause the topic map to be modified. The tags fall into three categories: for producing the form, for producing form components, and helper tags for added flexibility.
These tags must always be contained in a tolog:context tag If you are using the old Navigator tag libraries you can also use the old logic:context tag. , while the form component tags must always be contained in a webed:form tag, and the helper tags must always be contained in one of the form component tags.
The tag library is designed as an extension of the Navigator Framework tag libraries, and uses the same variable concept. Many of the attributes in this tag library contain variable names which resolve to Navigator Framework variables.
In addition, some of the attribute values refer to the action configuration file, which is typically located under ${WEB_APP}/WEB-INF/config/actions.xml. This file contains action definitions clumped together in action groups. HTML forms and action groups usually correspond one-to-one.
The form tags
Index
actionid
Generates as output the ID of an action, and will bind the name and any given parameters to that action. Any request with this ID as a request parameter will trigger the action with the given parameters. Useful in cases where more complex action handling is wanted.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | The name of the action which should be executed when the form is submitted. |
| params | No | Variable name(s) or qname(s) or JSP attributes | Additional parameters to the action. |
| value | No | Variable name(s) or JSP attribute | The value of the form control; will be received by the triggered action. If the attribute is not specified the action will be always be invoked when the form is submitted. |
| control | No | ( list | button ) | Name of form control that is being rendered. The default is ‘button’. |
| pattern | No | Variable or JSP attribute | If given, the string value entered in the text field must be match the regular expression. This will be validated both using JavaScript in the HTML page and on receipt of the submitted form on the server. |
| readonly | No | Variable or "false" | If the action is readonly it cannot submit any changes to the topic map. Whether the actionid is readonly depends on the readonly attribute of the actionid and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
button
Renders a button control element (according to the button template) used to submit the form and trigger an action on the server side.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | Sets the name of the action which should be executed when the form is submitted. |
| params | No | Variable name(s) or qname(s) or JSP attributes | Value which should be made available to the action triggered by the button. The names must be separated by whitespace. Note that the order of the parameters matters and is specific to the action. |
| image | No | Image type name | If set the button will be shown as an image. The image name is mapped to the action configuration file. If text is set, that will become the button title (shown as tooltip by most browsers). One of text and image must be specified. |
| text | No | Text value | If set, and image is not set, the value given will be the label on the button. One of text and image must be specified. |
| reset | No | Variable name or (true | false) | Whether this button should be a reset button (which resets the form field values to their original values). The default is “false”. |
| id | No | Unique ID | Specifies a unique id for the tag that will be used as the value of an ID attribute in the generated output. This id value can later be used to look up the content generated by the tag. |
| readonly | No | Variable name or "false" | If the button is readonly, the button will not be displayed at all. Whether the button is readonly depends on the readonly attribute of the button and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
checkbox
Renders a check box element, which the user can check or uncheck. Changing the state of the check box causes the attached action to be triggered.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | The name of the action which should be executed when the form is submitted. |
| params | No | Variable name(s) or qname(s) or JSP attributes | Additional parameters to the action. |
| state | No | Variable name or JSP attribute | The state of the check box. If the variable name is bound to a value that evaluates as true the box is checked, otherwise not. (If the attribute is not given the box is not checked.) |
| id | No | Unique ID | Specifies a unique id for the tag that will be used as the value of an ID attribute in the generated output. This id value can later be used to look up the content generated by the tag. |
| readonly | No | Variable or "false" | If the checkbox is readonly it is disabled in the page. Whether the checkbox is readonly depends on the readonly attribute of the checkbox and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
field
Generate a text input field element (according to the field template) that can be used to edit text strings. This may be one-line or multiline.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | Sets the name of the action which should be executed to reflect the changed value of the field when the form is submitted. |
| type | Yes | Field type name | Retrieves information about the field type (whether it should be a single or multiline input field and the concrete dimension) by the given name from the action configuration file (see element fieldMap). |
| params | No | Variable name(s) or qname(s) or JSP attributes | Values which should be made available to the action handling the field. The names are separated by whitespace. Note that the order of the parameters matters and is specific to the related action. See the action library reference for the parameters used by the different actions. |
| id | No | Unique ID | Specifies a unique id for the tag that will be used as the value of an ID attribute in the generated output. This id value can later be used to look up the content generated by the tag. |
| trim | No | Variable name, JSP attribute, or (true | false) | Leading and trailing whitespace will be removed from the contents of the tag if true, otherwise they will be left in. The default is true. |
| pattern | No | Variable or JSP attribute | If given, the string value entered in the text field must be match the regular expression. This will be validated both using JavaScript in the HTML page and on receipt of the submitted form on the server. |
| readonly | No | Variable or "false" | If the field is readonly, then it cannot submit any changes to the topic map and the field will not be editable. Instead the text contents of the field will be displayed as plain text. Whether the field is readonly depends on the readonly attribute of the field and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
form
Generates a form element (according to the form template) which acts as a container for input fields, selection lists and control buttons. The form is mapped to an action group which handles the form data when the form is submitted.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| actiongroup | Yes | Group name | Sets the name of the action group as specified in the action configuration file. |
| actionURI | No | URI | If a (relative or absolute) action URI is specified this overwrites the default action of the form (which is the process servlet The fully qualified class name is net.ontopia.topicmaps.webed.servlets.ProcessServlet). In most cases it is not necessary to specify something for this value. |
| target | No | Frame target name | If target is given it overwrites the default frame target setting deduced from the action configuration file. |
| lock | No | Variable name or JSP attribute | Name of the navigator variable containing the objects to lock. If one of the objects cannot be locked the request will be forwarded to a special page (as specified in the action configuration file). If no such page is specified, the form becomes readonly (for details, see the readonly attribute). |
| id | No | Unique ID | Specifies a unique id for the tag that will be used as the value of an ID attribute in the generated output. This id value can later be used to look up the content generated by the tag. |
| readonly | No | Variable or "false" | If a form is readonly (as opposed to read/write), then by default, all subelements of the form become readonly, which means they cannot be edited, nor modify the topic map. A form becomes readonly, either by setting the readonly attribute to true or if one of the lock variables (please refer to the lock attribute) cannot be locked. Note that "false" overrides the setting on the form, making the subelement not readonly, even if the form is readonly. If the form is not readonly, then the value of the readonly attribute of each subelement determines whether the element should be readonly (if true) or read/write (if false). The attribute evaluates to false if the variable referenced is empty/undefined, or if the literal string "false" is given. |
invoke
Generates a hidden form field that will cause the connected action to be triggered when the form is submitted. The action will always be triggered, except when the invoke tag is a child of a button tag, in which case it will only be invoked when the button is pressed.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | The name of the action which should be executed when the form is submitted. |
| params | No | Variable name(s) or qname(s) or JSP attributes | Additional parameters to the action. |
| value | No | Variable name(s) | The value of the form control; will be received by the triggered action. |
| runIfNoChanges | No | JSP attribute or (true | false) | If set to false, the action will not run if no other actions run. The default is true. |
| readonly | No | Variable or "false" | If the component is readonly it will be ignored and produce no HTML output at all. Whether the invoke is readonly depends on the readonly attribute of the invoke and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
list
Generates a selection list representation with the help of the list template for choosing one or multiple values. The list may be a drop-down list, single-select list, multi-select list, radio-button list, or checkbox list.
Attributes
| Name | Required | Value | Description |
|---|---|---|---|
| action | Yes | Action name | The name of the action which should be executed when the form is submitted. |
| collection | Yes | Variable name or JSP attribute | The candidates for the object’s values. |
| selected | No | Variable name or JSP attribute | The currently set value. |
| params | No | Variable name(s) or qname(s) or JSP attributes | Additional parameters to the action. |
| type | No | (dropdown | scrolling | multiselect | radio | checkbox) | Sets which type of menu should be used when presenting the selection list. If ‘type’ is not set, “dropdown” will be the default behaviour. |
| id | No | Unique ID | Specifies a unique id for the tag that will be used as the value of an ID attribute in the generated output. This id value can later be used to look up the content generated by the tag. |
| unspecified | No | String | Specifies what the label of the “no choice” element in the list should be. If set to “none” there will be no “no choice” element. If type is multiselect this attribute has no effect. |
| readonly | No | Variable or "false" | If the list is readonly, the selected element in the list will be displayed as plain text, and the list will not be editable. Whether the list is readonly depends on the readonly attribute of the actionid and the readonly state of the form. For details, please read about the readonly attribute of the form tag. |
Templates
Some information about the templates used by the form tag library. To ease understandability each tag maps to exactly one template file (the default name of the template file maps to the name of the tag).
The templates used by the tag library are Velocity More information about the Jakarta Velocity project can be found on the homepage based. This means that the syntax used in the template files must be compliant with the Velocity Template Language (VTL).
If a default installation is used, the templates will reside in the ontopia.jar file, but it is possible to override this and place the templates whereever you like. The following summarizes the configuration trail: First lookup in your web application descriptor file (${WEB_APP}/WEB-INF/web.xml) for the context parameter velocity_properties. The value of this property tells you where the velocity property file is located (default: ${WEB_APP}/WEB-INF/config/velocity.properties). Inside the velocity properties file there has to be property named file.resource.loader.path, this describes relative to the web application context directory in which directory the templates are located.
Note also that there is a very close correspondence between the use of the tags in pages and the action configuration. This file is usually found at ${WEB_APP}/WEB-INF/config/actions.xml, but this may vary with the configuration of the framework.