OpenWGA 7.5 - OpenWGA Concepts and Features

Design and development » TMLScript

Items, metadata and variables in TMLScript

Retrieving items, metadata and variables

The methods this.item() and this.meta() (or this.itemList() und this.metaList() for list items) are methods in TMLScript used to retrieve items, metadata fields and WebTML variables, just like <tml:item> and <tml:metadata> in WebTML:

this.item("body");
this.meta("title");


There are shortcut syntaxes available for retrieving item and metadata fields, which work by just retrieving the item or metadata name as a property of the TMLContext object. Spell the name in complete lowercase to retrieve an item/variable. Spell it in complete uppercase to retrieve a metadata field of that name:

this.body;
this.TITLE;


As the qualifier "this" is optional in TMLScript it actually is also ok to just use the item/var/metadata field name without it, so item and metadata fields may be retrieved like normal JavaScript variables.:

body;
TITLE;


There are a few restrictions on what items may be retrieved using the short form:

  • The item name must be suitable to be used as an object property / variable in JavaScript. For example it may not contain any characters not allowed there, like spaces.
  • The name must not be already used for a predefined method/property of TMLContext

Retrieving multivalue items and variables

There is a special behavour with retrieving items, metadatas and WebTML variables set by WebTML functionalities (like attribute var) if they contain multiple values.  In that case this.item() and this.meta() will only return the first value. This also applies to the short forms of these methods discussed before. The reason for this is that WebTML tags and items on some content platforms (Lotus Domino) always store values in the form of multivalue lists, so OpenWGA itself cannot determine if it should return a list or not.

If you need to retrieve all values of these fields you need to use this.itemList() and this.metaList() instead. These methods always return lists, even if the retrieved field has only one value (which then is the only value in the list). Even if a field is empty or not defined it will return an empty list.

This special behaviour does not apply to WebTML variables set by TMLScript. When storing a List into a WebTML variable here then it will also be retrieved as List by this.item(), so the behaviour is straight-forward here.

Setting WebTML variables

WebTML variables can also be set using TMLScript, which is - for normal variables - done via method this.setVar():

this.setVar("thevar", 1);


There is also a shortcut syntax here which sets the variable just as a property of the TMLContext object:

this.thevar = 1;


Qualifier "this" is also optional here, so setting a WebTML variable can also be done by simply setting a value to a yet undefined variable name:

thevar = 1;

Note the difference to the definition of a JavaScript variable:

var theScriptVar = 1;

This shortcut syntaxes can also be used to update existing WebTML variables of any type, like session and portlet variables.

To initially define session and portlet variables however other methods are used which to do not feature a shortcut syntax:

this.setSessionVar("theSessionVar", 1);

portlet.setVar("thePortletVar", 1);

portlet.setSessionVar("thePortletSessionVar", 1);

Scope of TML variables

Up to verion 7.1 of OpenWGA TML variables had global scope. Once defined those vars could be accessed from any TML.

Starting with OpenWGA 7.2 (that meens version compliance 7.2) TML variables have local scope. They can be accessed inside the TML where the var is definied but not outside this TML.

There is however a way to define globals vars as well. Global vars have to be definied using WGA.TMLPage.setVar(<name>,<value>). Such vars can either been accessed via WGA.TMLPage.getVar(<name>) or directly like any other var/item.

Item Expressions

In OpenWGA before 7.2 when using <tml:item name="someName"/> OpenWGA tried to retrieve the item value as follows:

  • Values of WebTML variables (local vars, session vars, portlet vars) by variable name

  • Values of mapped item values

  • Values of Content Items

In OpenWGA 7.2 (with designs of version compliance 7.2 or higher or if publisher option "Enable enhanced item expressions(WebTML.EnhancedItemExpressions)" is specified as true) items are treated as "item expressions":

  • String literals surrounded by ' : 'some text'
  • Number literals by simply specifying the number: 1, 1.5, -1
  • Boolean literals: true, false
  • Other literals: null, undefined
  • if item name begins with $:
  • Values of WebTML variables by variable name
  • Values of mapped item values
  • Values of Content Items

Samples:

<tml:item name="$mc.someMethod"/>

<tml:item name="$option_customer"/>

<tml:item name="$urlParam_search"/>

<tml:item name="$field_customer"/>

In addition for each non-literal you can append "call chains" to the name, i.e. retrieve properties or call methods on the returned value object using the dot "." as divider. For example:

<tml:item name="$mc.someMethod.someFieldOnReturnValue"/>

<tml:script>
  // if you still use script inside TML ...
  _contact = { name: "walter", lastname: "matthau"};

</tml:script>

<tml:item name="_contact.lastname"/>

JavaScript variables

Of course TMLScript is also capable of creating and handling normal JavaScript variables whose declaration is introduced by the "var" statement:

var jsvar = 1;

JavaScript variables differ from WebTML variables in their scope, which is limited to the current script only. They therefor are suitable to store temporary values of calculations which should be gone once the script is finished.

Priorities of variable types

As Items, JavaScript variables and WebTML variables are sometimes retrieved using the same functionality an order of priority must exist to answer the question which type is retrieved when there are multiple equally named variables of different types.

TMLScript follows this rule of thumb: The smaller the scope, the higher the priority

Variables of lower scope are normally more specific to the current code than those with a bigger scope. So it is more likely that they are meant when their name is used.

For the known variable types this means the following priority list:

Priority Type Scope
1. JavaScript variables The current script
2. Portlet variables In the current portlet and request
3. Portlet session variables In the current portlet for the browser session
4. Normal WebTML vaiables The current request
5. WebTML session variables The browser session
6. Items- and metadata Persistent