WebTML Variables store a custom value in WebTML processing that needs to be reused at a later point in time. WebTML variables may take values of any type.
There are different types of WebTML variables, differing in scope and types of persistence:
- Normal WebTML Variables are available to the rest of the OpenWGA page from their definition on. They are gone at the end of the request.
- Session Variables are persisted at the users browser session and available to all WebTML code that is executed on the same session from their definition on. So they are usable to store settings that need to persist requests.
- Portlet variables are normal WebTML variables that are only visible inside the WebTML portlet that they were defined in. They increase the modularity of WebTML programming since they do not influence code outside the portlet.
- Session portlet variables are a combination of portlet and session variables, i.e. variables with the scope of portlet variables that are valid for the rest of the user session
There are many possible ways to define WebTML Variables:
1. Via WebTML attributes var, sessionvar, pvar and psessionvar available on all WebTML tags.These attributes redirect the tags result into a WebTML variable of the given name, suppressing the output to the actual page. The following example loads the contents of an item "id" on the current context document into a normal WebTML variable of name "issueid":
The value stored in the variable is the raw value of the data that the tag retrieved or generated. So if "issueid" is a number then the variable will also be stored as number. This gives you the opportunity to do further work on this raw data before you put out somewhere. Therefor other WebTML attributes influencing the output as text, like encode or format, are not effective when the tag result goes into a variable.
2. Via TMLScript methods this.setVar(), this.setSessionVar(), portlet.setVar() and portlet.setSessionVar() and the corresponding short forms. The following script code examples do the same as the previous one, in varying forms of abbreviation:
this.setVar("id", item("issueid")); // The full form
this.id = this.item("issueid"); // Writing a WebTML variable simply as property of "this"
id = item("issueid"); // Leaving out optional "this"
id = issueid; // Reading item "issueid" simply as property of implicit "this"
3. As variable parameters on URLs generated by <tml:url>. These are specified by using <tml:param> inside that tag which will generate an URL parameter that will set the WebTML variables for the request that uses this URL. This is especially useful if you want to define a normal WebTML variable that can survive page reloads, as the URL parameter will stay and still be effective then. The following example again reads item "id" and sets it parameter to the URL:
<tml:url type="layout" name="main">
<tml:param name="issueId"><tml:item name="id"></tml:param>
See URL parameters for more details of this usage form.
WebTML variables can be read via tag <tml:item> in WebTML or methods this.item() and this.itemList() in TMLScript. So WebTML variables are read via the same functionalities that read content items from the context document. Their retrieval however is not dependent on the current context document and they have a higher priority than items. So a WebTML variable will "hide"" an equally named item that would be available on the context document.
Current issue id is <tml:item name="issueid"/>