OpenWGA 7.6 - OpenWGA Concepts and Features

Design and development » WebTML » Features

Scoping

WebTML scoping is a new to WebTML since OpenWGA 5.3. It is a lightweight feature which allows to assign a "scope" to certain WebTML ranges or includes which then can be used by WebTML functionality inside these codes.

A WebTML scope is defined as a String which uniquely identifies the code part that it is assigned. It allows this code part to qualify certain resources with the scope to:

  • Prevent name collision with other, equally named resources on the same WebTML page that use a different scope
  • Uniquely identify a resource to belong to the scoped code part

WebTML scoping is not meant for a special resource type exclusively but may be used for any resource for which its semantics are matching. However the scoping functionality was designed with the following resources in mind:

  • Item names: If the scoped region displays or even edits certain items then the item names may be scoped so the code part can be sure to use unique item names that are used nowhere else on the WebTML page
  • IDs of WebTML or HTML tags: Ids of both tag types need to be unique among the whole WebTML/HTML page. Scoping the ID will ensure that used IDs cannot be used anywhere else

Defining WebTML scopes

WebTML scopes may either be defined for a <tml:range>, which lets all contained code use the scope (including WebTML modules that are included in this code) or a <tml:include> which gives the scope to the included WebTML module and all deeper included modules.

Both WebTML tags feature an attribute tmlscope to define scope. It simply takes a string that should be the scope for the code part:

<tml:range tmlscope="privateaddress">


   ... further WebTML code


</tml:range>

Using WebTML scopes

WebTML scopes do not automatically effect the scoped code part. Instead you need to use scoping functions at those places where you wish to use the scope. There are two functions for doing that:

1. The dynamic attribute function "scoped" available for all WebTML tag attributes: It lets you define a text that is automatically scoped

<tml:item name="{scoped:street}" editor="text"/>

2. The TMLScript method WGA.scoped() which you can use to create more dynamic scoped texts:

<tml:script expression="WGA.scoped(theScopedItemName)"/>

In both bases the defined scope will be appended to the given text after a delimiting undercase letter "_". So the item name in the first example would be "street_privateaddress" if it were contained in the range/include of the previous chapter.

The scope is appended to allow itemnames that are scoped with some dynamic scope string to still be referenced in the configuration of the OpenWGA lucene fulltext index. A fulltext rule could still use the item name "street_*" to be effective for all "street" items that are possibly created by example 1.

Cascaded WebTML scopes

WebTML scopes are not cascaded implicitly! If you define a WebTML scope for some <tml:range> then a WebTML scope that is in effect for the <tml:range> itself would be gone for the code inside the range.

However you can easily enable the usage of cascaded scopes by simply using the "scoped" methods when defining the new scope:

<tml:range tmlscope="{scoped:innerscope}">

This will add the "outer" scope to the "innerscope" effectively providing a cascaded scope. So using this inside the range from chapter "Defining WebTML scopes" would produce the effective scope "innerscope_privateaddress".

Be careful however when cascading scopes because this of course introduces a dependency on outer scopes. If for some reason an outer scope changes (maybe if the module that is scoped is moved along the page) then also the inner scope is changed and will use entirely different item names/id/whatever. In that case it may be better to use some unique IDs for scopes that are not cascaded.