Loading ...

OpenWGA 7.10 - TMLScript reference

Object:

TMLForm

Description This object represents a WebTML form which either has been created by a <tml:form> tag or in TMLScript via WGA.createForm(). It offers various functionalities to read and modify the data that is stored on the form and transmit it to any data sink.

Use methods tmlform.field() to read and write single field values. As a shortform syntax you can also use the name of a field as property of the TMLForm object to read its value.

As WebTML form fields can also contain multiple values you can use tmlform.fieldList() to read a list of values. Use tmlform.setField() to create new or modify existing fields. Use tmlform.removeField() to remove fields from the form.

WebTML forms can also store uploaded files. Use methods like tmlform.fileNames, tmlform.getFile() or tmlform.getFileText() to read and use uploaded file data.

WebTML forms may take the values of their fields from different sources, depending on tmlform.source(). Use the method tmlform.store() to transfer all field data back to the data source of the form.

There are also various methods to influence the validation functionality of WebTML forms. Use tmlform.validate() to manually trigger a validation. Otherwise validation is executed automatically when using one of the tmlform.storeIn.. methods. Use tmlform.getInvalidFields(), tmlform.getMessage() and tmlform.hasMessage() to read the validation status of the form.

All methods of this object can be called case insensitive though we recommend to use the case that is documented here.
Retrieval Create via WebTML tag <tml:form> or TMLScript method WGA.createForm()
Retrieve via this.tmlform or this.tmlformByID()
Allowed in script types
  • WebTML pages and normal WebTML actions
  • Master actions
    portletevent
Properties and methods
Name Purpose
addFile(file, fileName) Adds a file from the servers file system to the form
addMessage([fieldName,] msg) Adds a new validation message
appendToField(name, value) Appends a value to the value list of a field
attach(document) Attaches all files stored on this form to a document
getFileSize(filename) Returns the size of an uploaded file in bytes
clearMessages() Clears all validation messages on the form
editable Returns if this form is currently in edit mode
enteredValue(fieldname) Returns the unprocessed value of a field like the user entered it
errors Lists data type conversion errors
field(name) Returns the value of a field.
fieldList(name) Returns the values of a multi value field
fieldNames Lists the names of the fields on this form
fileNames Lists the names of files that have been uploaded to this form
filesDropped Indicates if an uploaded file has been dropped because of its size
fileURL(fileName) Returns a URL to the uploaded file of the given name
formID Returns the ID of the form
formInfo Grants access to the FormInfo object of this WebTML form
getCreatedDoc() Retrieves the document that was created by a TMLForm store operation
getFile(filename) Returns a Java file object for an uploaded file
getFileText(filename) Returns the text contents of an uploaded file
invalidFields Lists names of fields with validation errors
getMessage(fieldname) Returns the validation message of a field with failed validation
globalMessages Returns all validation messages that are global, i.e. not bound to a specific field
hasField(name) Tests if the form contains a field of the given name
hasMessage(fieldname) Tests if a field specific validation message exists for the given field
hasMessages() Tests if any validation messages exist
isEmpty(fieldName) Checks if a form field is regarded empty
messages Lists all current validation messages
mode() Returns the display mode of the WebTML form
storeField(fieldName, doc [, storeName]) Stores a single form field to a document
parsedValue(fieldname) Returns the processed value of the field in its target type
persistent Shows if the form is persistent
processContext Provides a ProcessContext to store arbitrary data for the form process
remove() Removes the current form from form registry
removeField(name) Removes a field from the form and its data
removeFile(fileName) Removes a file from the form
reset() Clears all fields and uploaded files from the form, resetting it completely
setField(name, value) Sets the value of a field
setMessage(fieldname, msg) Adds a new validation message related to the specified input field.
source() Returns the source type of the form
store() Stores the form data to the source of the form
storeInContent([content]) Stores the fields of the form to a content document
storeInPortlet([portlet]) Stores the form data into a portlet configuration
storeInProfile() Stores the form data on the users personalisation profile
submitted Shows if the form was submitted from a previous request
targetContext Returns the context for which this form was instantiated
validate() Manually triggers the form validation
Examples Simple read access to a TMLForm field, once in full, once in shortform syntax. Both work the same way:

var x = tmlform.field("username");
var y = tmlform.username;