OpenWGA 7.10 - TMLScript reference



Description The TMLContext is the base object of the TMLScript runtime. It combines two purposes:
  • It represents the document context for which the TMLScript is called, mostly the context of the WebTML tag that executes the script. That is it points to a special content document and offers it's item and metadata fields, just like <tml:item> and <tml:meta> do in WebTML.
  • It offers the most frequently used TMLScript functionalities as methods, like for example many condition tests, context changes, and access to WGAPI objects

All methods of this object are case insensitive and can be used in any case variants, although we encourage you to use the case that is documented here.

The base TMLContext object of a script is reachable as "this" in all TMLScript code that does not belong to a TMLScript custom object (in which the "this" object is of course the TMLScript object itself).  Specifying "this" is optional. You can also just use all methods and properties of the base TMLContext without "this." as if they were global functions and variables, if their names do not collide with other variables and functions.

The TMLContext object offers a shortcut syntax for direct access to items, WebTML variables and metadata fields of the current context document.  This syntax lets you read those fields by just using their names as object properties. Specify the name in lowercase to read an item or WebTML variable, specify it in uppercase to read a metadata field. These are actually shortcuts to the methods this.item and this.meta of this object. See the examples how this is used.

You can also write to WebTML variables with this shortcut syntax when setting values to these "virtual" object properties. If there is an existing WebTML session variable of the property name it is updated. Otherwise this creates a new or updates an existing normal WebTML variable.
Retrieval As "this" object in all scripts. The "this" qualifier is optional and can be omitted, so you may also directly use TMLContext methods and properties like global functions or fields.
Allowed in script types
  • WebTML pages and normal WebTML actions
  • Master actions
  • TMLScript tasks in jobs
  • Content type events
  • Content type events
Properties and methods
Name Purpose
addWarning(message[, severe]) Adds a custom WebTML warning
appendVar(name, value) Appends a value to a WebTML variable as list element
attachScaledImage(doc, scaler [, targetFileName)) Stores the image data on an ImageScaler object as attachment on a document
content() Providfes the WGAPI object "WGContent" which represents the current content document in context
contentURL([mediakey, layoutkey [, ignoreVirtualLink]]) Returns a URL to the content document in context
context(contextExpression [, returnContextOnError])
Creates a TMLContext object for a different content document
cookies Represents the browser cookies of the current user
createEvent(name) Creates a new PortletEvent object
db() Returns a WGAPI database object for the database of the current context
document Returns the WGAPI document object in context
fileurl([[dbkey,] containername,] filename) Creates a URL pointing to a file attachment on a content document or file container
getFileData(filename[, derivate]) Returns an input stream containing the requested file data.
getFileNames() Returns a list of all file names of the current content
getPrimaryFileName() Returns the name of the primary attachment or null if there is none.
getSessionVar(varname) Retrieves a WebTML session variable
getVar(varname) Retrieves a normal WebTML variable
hasChildren() Returns if the current context document has child documents
hasGroup(group) Tests if the user is member of the specified group
hasLabel([container], [file], key) Tests if a label is available for the given key that can be served to the user
hasOption(optionName) Tests if an WebTML option of the given name is defined
hasProfile() Returns if the user currently has a user profile
hasRelation(relationname) Returns true, if the current content has the specified relation. False otherwise.
hasRole(role) Tests if the user has the given user role
hasSiblings() Returns if the current context document has sibling documents
hdb() Returns a  WGAPI HDB object for the application in context
httpsession Returns the JavaEE object representing the current HTTP browser session
isAnonymous() Tests if the current user is anonymous
isBrowserInterface() Returns true if the WebTML page is rendered in some kind of OpenWGA authoring client like the OpenWGA Content Manager
isdefined(name) Tests if a name is defined as WebTML variable or item on the context document
isEmpty(item) Returns if the given WebTML variable or item is regarded "empty"
isEmptyValue(value) Returns if the given value is regarded "empty"
isFilled(item) Returns if the contents of an item or WebTML variable is regarded as "filled"
isFirstLoop([Tag-ID]) Tests if a tag <tml:foreach> is in its first iteration
isLastLoop([Tag-ID]) Tests if a <tml:foreach> tag is in its last iteration
isMainDocument() Returns if the document in context is the main document of the request
isNewSession() Returns if the current request is the first request in a new browser session
isRoot() Returns if the current context document is a root document
isselected() Returns if the current document is the main document of the current request or an ancestor document of it
istagidvalid(tagid) Tests if a WebTML tag with the given id is available
isTrue(name) Returns if the contents of an item or WebTML variable is regarded "true"
isWebEnvironment() Returns if the current TMLScript code is executed in the context of a WebTML request
item(itemname) Returns the value of an item or a WebTML variable
itemIterable(itemname) Returns the value of an item or WebTML variable as an iterable
itemList(itemname) Returns the value of an item or WebTML variable as list
label([[container, ] file, ] key [, params])
label(database, container, file, key , params [, returnPlaceholder])
Returns a WebTML label in a language that the user should understand
lastError Returns the error message of the last failed context expression that was done from this context object
log Provides an object for logging output to the application log
maincontext Returns the main context of the request
meta([type,] name) Returns the value of a metadata field
metaList([type,] metaname) Returns the value of a metadata field as list
now() Returns the current date and time
option(name [, defaultValue]) Retrieves the value of a WebTML option
path Returns an absolute context path to the current context document
portlet Returns a portlet object for the current WebTML portlet
portletByPath(pathExpression) Retrieves a portlet by a portlet path expression
profile Returns the users personalisation profile as profile object
removeSessionVar(varname) Removes a WebTML session variable
removeTMLForm(formid) Removes the form of the given ID from form registry
removeVar(varname) Removes a (normal) WebTML variable
request Returns the JavaEE object representing the current HTTP browser request
response Returns the JavaEE object representing the current HTTP server response
setOption(name, value [, scope]) Sets a WebTML option
setSessionVar(varname, value [, allowSerialisation]) Sets or updates a WebTML session variable
setVar(varname, wert) Creates or updates a (normal) WebTML variable
tag([tagid]) Retrieves a WebTML tag information object
tagInfo(tagid, infoname) Retrieves a WebTML tag information
tmlform Returns the TMLForm object representing the current WebTML form
tmlformbyid(id) Returns a TMLForm object representing the WebTML form of the given ID
Examples Reading an item "body" in three different ways. First in full syntax using the method "item". Then in shortcut syntax using the item name as object property in lowercase. Then even shorter, leaving out the optional "this" reference:

return this.item("Body");
return this.body;
return body;

Using the full method "meta" you can also retrieve non-content metadata, like the database key in this example:

return this.meta("db", "dbkey");

Retrieving a different context. This is again a full TMLContext object which points to a different document, in that case the root document of the base TMLContext's document:

var rootContext = this.context("root");

Using the shortcut syntax to set WebTML variables: When you omit the "var" operator when setting a variable you effectively create or update a WebTML variable, which then can also be retrieved via <tml:item/>

  aList = createList();

<tml:item name="aList"/>

If there is an existing WebTML session variable of the used name then this syntax updates it. Therefor the line "sessionvar++" effectively modifies the session variable set before:

  setSessionVar("sessionvar", 1);