OpenWGA 7.10 - WebTML reference

WebTML tags

<tml:param>

Description :

This is a generic tag to specify parameters for different WebTML functionalties.

Usage basics:

Every parameter has a name, which will be used to retrieve it, and also a value. There are two ways to specify a value: 

  1. You may simply specify it in the content of the <tml:param> tag. You can use further WebTML to calculate the value dynamically in the tag content but the result will always be (transformed to) a string value.
  2. You may use attribute expression to calculate the parameter value from a TMLScript expression. The resulting parameter value may be of non-string type if the usage type of <tml:param> permits such data types (inside <tml:query> or inside <tml:url> as type="var"). Otherwise it will also be converted to a string.

Usage 1: Specify query parameters inside <tml:query> or <tml:collection>:

You can use <tml:param> inside <tml:query> to define a query parameter. The <tml:param> tag will not be part of the query itself (which is also defined in the content of <tml:query>). However alternatively you can also specify <tml:param> in the same <tml:collection> as the query you want to parametrize in case you prefer this syntax.

Some query languages for example. HQL and SQL can contain parameters. The values for these parameters can be specified by <tml:param>.  The capabilities and exact syntax of these parameters is query language dependent and should be looked up in the query language reference.

An obvious alternative to parametrizing queries with query parameters would be to just dynamically calculate the query text using WebTML/TMLScript. While this may seem easier and more "straight forward" the usage of query parameters has a number of benefits that should be taken into account:

  • Query parameters in most cases make the query more readable as the calculation code of dynamic parts is not part of it
  • On most query backends the usage of query parameters is an effective prevention of SQL injection as it ensures that the parameter value can only replace the intended parameter place
  • Query parameters may increase performance as some database servers are able to precompile parametrized queries and reuse those compilations with different parameters

Usage 2: Specify parameters for generated URLs Inside <tml:url>:

Use <tml:param> inside <tml:url> to add or modify parameters that are to be added to the generated URL. This works with all plain URLs but will not work for some special URLs like AJAX Action URLs which are generated as JavaScript.

There are two types of parameters that you may add, chosen by attribute type:

  • Variable parameters on type="var" (default): A variable parameter is a parameter that will be retrievable as WebTML variable when the generated URL is requested. Variable parameters are more safe than URL parameters as they are transmitted in encrypted form via a single URL parameter "$vars". So it will be impossible for the user to modify the parameter value (he may only remove all parameter values alltogether by removing the "$vars" URL parameter).

    Another benefit of variable parameters against URL parameters is that they can be used to transfer non-string values. They are usable for all values that can be safely serialized, which includes all basic data types like strings, numbers, dates, boolean values etc. and collections holding those values. Use attribute expression to assign the parameter such a value.

    The downside of variable parameters is that because of their encrypted form it will be impossible for browser-side JavaScript to use these parameters.

  • URL parameters on type="url": This adds a simple URL parameter which is capable of transporting string values. It is transmitted in plain text, thus being readable by browser-side JavaScript, but as such has no security features.
Derived from: Only available in the following parent tags: Attributes:
show inherited attributes ...
Name Value(s) Purpose
expression tmlscript-expression Calculates the parameter value from a TMLScript expression
name parameter-name Specifies the name of the parameter
type var | url Determines the type of parameter when using inside <tml:url>

Examples:

Usage type 1. We specify a string parameter for usage inside a HQL query:

<tml:query type="hql" db="website">

    <tml:param name="author">smith</tml:param>
    content.author = :author
</tml:query>

Another example of usage type 1. This time we calculate a non-string parameter with attribute expression which actually holds a content document. This is very handy when the query should select based on content relations:

<tml:query type="hql" db="website">

    <tml:param name="project" expression="context('docid:' + projectKey).content()"/>
    content.relations['parent-project'].target = :project
</tml:query>

Usage type 2. We add a variable parameter to an URL:

<tml:url>

  <tml:param name="mode">display</tml:param>

</tml:url>

In the WebTML code of the page behind the URL we can just retrieve the var parameter as normal WebTML variable:

<tml:case condition="mode == 'display'">

   ...

</tml:case>

Usage type 2 adding a "real" URL parameter. This parameter type can be retrieved using "this.request.getParameter()" in TMLScript or tag <tml:urlparam> in WebTML:

<tml:url>

  <tml:param name="query" type="url"><tml:item type="tmlform" name="phrase"/></tml:param>

</tml:url>