OpenWGA 7.9 - WebTML reference

WebTML tags

<tml:form>

Description :
Generates a form to let OpenWGA users input data.

 A WebTML form is the container for input fields, denoted by <tml:input>, where the user can input data. Upon any WebTML action call the form data will be transferred to the OpenWGA Server and can be processed there, for example in the form of TMLScript object TMLForm.

This is the WebTML pendant of the HTML tag <form> which will actually create an HTML form on the page output.. The form and its input fields provide many additional functionalities above normal HTML forms like  automatic data binding, optional session persistence and validation.

Derived from: Attributes:
show inherited attributes ...
Name Value(s) Purpose
contentclass content-class Defines the content class of content documents to be created with this form data
cssclass css-class Determines the CSS class that controls the rendering of the HTML form in the browser. The content of this attribute is copied directly to the "class" attribute of the HTML form tag.
cssstyle css-style Equivalent to the HTML attribute style.
defaultaction action-id Defines a WebTML action which is  invoked when the WebTML form is submitted per normal browser submit.
editable false | true Determines if form data is only displayed or if it can be edited.
html_attribute html-value Defines a custom HTML attribute that will be added to the generated HTML tag <form>
htmlinput true | false | ignore Specifies if a WebTML form should accept a normal HTML input field.
id form-id ID of the form. Mandatory attribute at tml:form.
maxuploadsize megabytes Limits the maximum size of uploaded files
mode edit | readonly | view defines the display mode of the WebTML form
onsubmit JavaScript-code Inserts the given JavaScript code to the event "onsubmit" of the HTML form. This will get executed before sending the form, for example to perform input validations.
persist true | false Marks a form as "persistent"
source content | newcontent | profile | portlet | portletsessionvars | none data source of form data
trim true | false Enables the trim feature on every contained <tml:input>

Details:
<tml:form> generates HTML code in form of :

<form methode=post" id="myform" action="URL of current page">... </form>


In the body of <tml:form> you can define <tml:input> tags to define input fields.  These fields get automatically filled by the data of the data source of the form, depending on the attribute "source" . Or they are initialized empty and get their data from the OpenWGA user.

Different from HTML forms, WebTML forms will not always be saved if they were sent per submit to the server. Instead each submit, for example by a <tml:button>, may trigger a WebTML action that can do different things to the form, including - but not bound to - saving its data.

The form data is represented by the TMLScript object TMLForm on the server side. The data contained on this object can be saved to the forms source document by using WebTML default action $store or the TMLScript method store().

A form is uniquely identified on the users session by its ID. As your form data gets posted across the requests you may use differing form definitions with differing fields to display it (even undisplayed fields will be conserved on the form) as long as you use the same ID on the form tag.

You may also have multiple forms on the same page with differing IDs but note that HTTP is only capable of posting the data of one form at a time and that the data of non-persistent forms will get lost if it is not posted.
Examples:

The following WebTML form contains one input field "name". Because of the "source" attribute the content of the form gets saved in the user profile when the default action "$store" gets triggered.

<tml:form source="profile" id="myform">
    Name: <tml:input name="name"/>
    <a href="<tml:url action="$store">">speichern</a>
</tml:form>

A bigger example where the inputs also have validations, whose messages are displayed via a <tml:formmessages> tag. The methods of TMLScript object WGA.Validate are used to specify the validation rules.

<tml:action id="storeUserData">

  if (!tmlform.validate()) { // Will test the validations and return true if any fails

    return;

  }


  // Some code to store the user data to some arbitrary database target  


</tml:action>


<tml:form id="userdata" source="none">


  <tml:formmessages/>


  Your name:

  <tml:input name="username" validation="WGA.Validate.isFilled()" message="Please input your username!"/>


  <br><br>


  Your date of birth:

  <tml:input name="birthdate"

    validation="WGA.Validate.isFilled() ~ WGA.Validate.isDateInPast()"

    message="Please enter your date of birth ~ Your date of birth is most likely in the past!"

    validationdivider="~"/>



  <tml:button clickaction="storeUserData">Store data</tml:button>


</tml:form>