OpenWGA 7.10 - OpenWGA Concepts and Features

WebTML options are another way of storing values on a WebTML page for later usage, just like WebTML variables. However other than on WebTML variabies the visibility scope of WebTML options is dependent on the hierarchy of WebTML tags.

The main purpose of WebTML options is to pass parameters to included WebTML modules or elements so they influence only the included functionality, not the rest of the page.

WebTML options are created using the tag <tml:option> in WebTML or via method this.setOption() in TMLScript:

They can be read using the <tml:option> in read mode, with method this.option() in TMLScript or with dynamic attribute syntax "{option:optionname}".

Just like WebTML variables WebTML options also can be used to store any data of any type, although the default <tml:option> usage scheme only allows setting string values. You need to use attribute expression to let <tml:option> store non-string values.

 WebTML options are mostly defined via WebTML tag <tml:option> which is in the body of either a <tml:include|portlet> or an <tml:element>. These tags are called option receivers.

It does not matter how deep inside <tml:include|portlet|element> the <tml:option> is cascaded in other WebTML tags, they will always receive the option. So this is also possible:

The option receivers pass on the option to the functionality they include, so an included WebTML module/portlet or an WebTML element.

Inside a WebTML module <tml:option> or this.option() can be used to read the option values where they are needed.

The attribute scope on <tml:option> can be used to reduce the scope of WebTML options when they are used inside <tml:include|portlet>. Normally the scope of an option is not limited on the way down the tag and module hierarchy. An included WebTML module may include other modules which each still include even more modules. A WebTML option would be passed down eternally to these includes. This behaviour equals the default "scope" setting of "global".

Alternatively the scope attribute can be set to "local". This means that the option will only be available to the directly included web module. This keeps the option from influencing modules deeper down the inclusion hierarchy and is also relevant for performance when using AJAX portlets, as the following chapter shows.

Another feature of WebTML options is their behaviour regarding AJAX in WebTML portlets. If a portlet gets reloaded via AJAX then the WebTML options that were available on the initial portlet rendering are recovered. They are then again available to the re-rendered portlet code. So regarding WebTML options the environment of an WebTML portlet remains constant accross AJAX requests.

This differs options from WebTML variables. If a WebTML portlet is dependent on a WebTML variable that was set outside the portlet then this variable will not be available if the portlet is reloaded via AJAX.

Options can be passed to WebTML portlets like they are to Includes, as <tml:portlet> is derived from <tml:include>:

Regarding this functionality the option feature of "local" scope gains importance. To be recovered these available WebTML options need to be sent across the network in case of an AJAX-reload. This means more traffic the more options need to be transported. Setting options to "local" scope may keep them from being transported in all AJAX request of included portlets, thus helping to reduce traffic.

A special option type is called "inline option" and can be created via tag <tml:inline>, which is a descendant of <tml:option>. It however is used the same way:

An inline option differs from regular options by the fact, that its option value is not determined on option definition. Instead the WebTML code that the <tml:inline> tag defines is stored internally and executed when the option is retrieved. That way the option value is determined, which may be an individual value every time the option is retrieved. Retrieval is again done with a regular <tml:option> tag in "get" mode:

This has some advantages over regular options in some situations:

• The WebTML generating the option value is executed under the context of the <tml:option> tag which retrieves it (rather than the one which defines it). When you retrieve the option in the context of three different contents you may get three different option values which reflect the current content. That way the example above lets inline option "body" generate individual HTML links for individual contents
• The option value is internally only a pointer to the stored WebTML contents of the tag and is very small. This is of advantage when the option is used in an AJAX-enabled WebTML portlet, which transports the value all its active options along every single AJAX request.

There are however also some downsides when using inline options, described in more detail on the <tml:inline> tag documentation:

• It is not cascadeable inside the same WebTML. When you want to use an <tml:inside> inside the contents of another <tml:inside> these must go into different WebTML modules.
• Its value cannot be retrieved via TMLScript, only via WebTML tag <tml:option>
• It defaults to scope "local" and should in most situations be used like that to keep it from retrieving itself again and producing a stack overlow