OpenWGA 7.6 - OpenWGA Concepts and Features
Design and development » WebTML » FeaturesScriptlets
WebTML scriptlets are dynamic parts in an otherwise static text that are resolved to actual values when this text is put out via WebTML.
Scriptlets therefor can be used inside the text of content items to put out dynamic information.
For example:
This is a link to the <a href="/doc-wga76/html/default/home">home document</a>.
Resulting in the following output:
This is a link to the <a href="/myapp/html/default/home.en.html">home document</a>.
On every output of this text this scriplet will be recalculated in relation to the current WebTML document context. Their usage scheme resembles the one of normal WebTML tags in WebTML modules, only that they can be embedded to any static text. As stated they are mostly used inside the text of content items, which are parts of the OpenWGA content store and not the design.
The base syntax of WebTML scriptlets is:
{@function@}
The rendering of scriplets is not automatically enabled for every put out text. Instead certain output functionalities need to be used for scriplets to be resolved, which also decide which scriptlet level is available. The scriptlet level decides the range of functions that is available, where a higher scriptlet level means more functionality but also more a higher potential to for abuse these functions for malicious causes . As scriptlets in most situations are not only available to designers but also for authors it should be carefully decided which level should be available.
See the following chapters on scriptlet levels for information how to enable scriptlet resolving.
Scriptlet level 1
Scriptlet level 1 allows basic functionality quite frequently needed in authoring, like requesting data of the context document and the execution of "scriptlet macros", which offer a range of functionality predefined either by OpenWGA or an OpenWGA design.
The resolving of scriptlets of this level is active on:
- The output of an item, edited with the rich text editor, via <tml:item editor="rtf">. So scriptlet level 1 is automatically activated for items edited with the rich text editor (that internally uses scriptlets for some functions itself)
- The output of any other text with the WebTML encoder "rtf" via <tml:item encode="rtf"/>
Requesting values of content items:
{@#itemname@}
Requesting values of metadata fields of type "content" (like known from <tml:metadata>):
{@$metaname@}
Calling "Scriptlet macros":
{@!macroname [:parameter, parameter, ...]@}
The scriplet macros that are available are documented in the WebTML reference under WebTML scriptlets.
The scriptlet level 1 only allows operations that should be generally safe to use by authors. This however may depend on the custom scriptlets that are available via OpenWGA design. The scriptlets predefined by OpenWGA are all provide read-only operations that only involve the current context document.
If a scriptlet is the only content on a text row and is immediately preceded or followed by a HTML carriage return tag <br>, then these carriage returns are removed from output. This happens to remove those carriage returns that are only added to the text to highlight the usage of the scriptlet and should not influence the layout.
Scriptlet level 2
Scriptlet level 2 contains all functionality of level 1 plus the ability to run arbitrary TMLScript code.
As TMLScript code has the ability to workaround all security barriers (for example via master functions) enabling scriptlet level 2 may be a major security risk! It should only be enabled if the potential authors of the text to process may have complete control and access over the OpenWGA platform.
The resolving of scriplets of this level is only activated when putting out text via tag <tml:item> with attribute scriptlets set to "true".
The following syntaxes are available:
{@= TMLScript expression @}
Execution of a custom TMLScript expression and embedding its result into the text.
{@ TMLScript code @}
Execution of custom TMLScript code, including control statements. If a result is returned via "return" statement it is embedded to the text.
Custom scriptlet macros
The available scriptlet macros can be extended by defining additional macros in OpenWGA design.
A custom scriptlet macro is defined as TMLScript module in the design of an application. It must match the following conditions:
- It must be stored in a system resources subfolder of folder "tmlscript" with name "wga/scriptlets"
- The name of the file may not match the name of any other predefined scriplet macro
The code contained in the module is executed when the scriptlet is resolved. Whatever is returned via "return" statement will be embedded to the code at the position of the macro.
For example, imagine the following code stored in a file "scripts/tmlscript/wga/scriptlets/home.tmlscript" of your design:
return '<a href="' + context("name:home").contenturl() + '">Homepage</a>';
Once stored this macro is available to apps that use the design containing the module. Use it by specifying the name of the module (without prefix "scriptlets:") as macro name. So regarding the example the following may be used in the rich text editor:
This is a link to the homepage of this site: {@!home@}
The custom macro can also receive parameters, just like is possible for the predefined portlets. These are passed to the macro as WebTML variables "tmlparam1" to "tmlparam5" for parameters 1 to 5.
The following example macro creates a link to a file attachment to displayed in a separate browser window. The data about document, file name and title of the link are passed as parameters:
return '<a target="_blank" href="' + fileurl(tmlparam1, tmlparam2) + '">' + tmlparam3 + '</a>'
If this code is stored into a module "newwinlink.tmlscript" usage may look like this:
Link to {@!newwinlink: instructions, install.pdf, Installations Instructions@}
Since custom scriptlets have access to the full TMLScript language potential it is theoretically possible to offer dangerous functionalities to the author that way, which may endanger integrity of the data and runtime of OpenWGA. As all authors of any rich text fields have access to these macros the functionality offered here should be carefully chosen. Any data-modifying functionality should be avoided.