OpenWGA 7.11 - WebTML reference

WebTML tags

<tml:query>

Description :
<tml:query> allows execution of different queries on content store databases. The query is specified in the body of the tag. Per default the current content database is queried. Another database to query can be specified with the attribute "db".

The query syntax depends on the query type. The different content store implementations support different query types with different features. See the query language reference for more details.

Some query types support query parameters which you can assign actual values using the <tml:param> tag, either inside <tml:query> (will not be part of the query itself) or inside the same <tml:collection> tag.

Derived from: Attributes:
show inherited attributes ...
Name Value(s) Purpose
alllanguages true | false | t | f | 0 | 1 Specifies if the query searches for documents in the current language only 'false' or in all languages 'true'.
cache true | false Specifies if OpenWGA should cache the query result until the database is modified.
db db-key Specifies the databases to search in. If not set the current database will be used.
highlight true | false Only valid for type="lucene". Activates or deactivates the highlighting of query results.
includecurrent true | false | t | f | 1 | 0 Defines if the current document is allowed to be included in the query result if it matches the query criteria.
max 0...n Specifies the maximum number of documents this query can return.
onlypublished true | false Specifies if only published documents should be included in the search result or documents in any state.
onlyvisible true | false Specifies if only visible documents (VALIFFROM>today AND VALODTO<today) should be included in the search result or documents in any state.

This attribute does only have any effect if used together with onlypublished.

options option,option,... Takes a comma separated list of native query options
p_param param-value Shortcut for defining query parameters
return item-name If this attribute is specified the query tag returns the given item from the first result of query.
role none | nav | sitemap | search Specifies the role for this query. Normally queries exclude documents when their "hide when" flags contains "search". If "none" is specified as role the query will affect all documents and ignore the "hide when"  flags.
type hql | lucene | sql ... Specifies the type of this query. For supported query types and their usage see Query languages reference.

Details:
Normally <tml:query> is used in the body of a <tml:collection> tag together with a <tml:foreach> tag. The query result will be redirected to the collection tag and the foreach will iterate over this result. The result of <tml:query> is a list of content documents. <tml:foreach> automatically iterates over these docs and change the context accordingly so that all tags within the foreach body are already executed in the document context of the current query result.

If <tml:query> is used without a <tml:collection> tag the first result of the query can be referenced via the context expression "query:tagid". Futher it is possible to use the attribute "return" to access an item from the first query result directly.

Some query types allow the usage of query parameters. The form of usage is different by query type but in all cases it allows to reference a parameter inside the query either by name or position. The parameter value then is substituted to the query by a <tml:param> tag that is either inside the <tml:query> tag or inside the same <tml:collection> tag as the query using it.

<tml:query> issues some default query parameters to those query types that support named query parameters. You can reference them in your query without injecting them by <tml:param>. These are:
  • :content - The content document in context of the query tag (WGAPI content document). This can be compared against the property "target" of relations or against the "content" object itself.
  • :key - The unique content key (including version number) of the context document (String)
  • :structkey - The page/struct key of the context document (String)
  • :language - The code of the language of the context document (String)
Tag-Infos :

cacheused: Is true if the results were fetched from the query cache (only when attribute cache="true"), false if they came from the database backend

count: Number of results of the query

error: contains a Java exception object or null if no error occurs

fullquery: The effective executed query. Implicit filter additions and modifications of the <tml:query> tag are included.

unspecificquery: (query type "lucene" only). This will be set to 'true' if the query result is regarded "inexact". For e.g. a user searches for "a*". Such queries have to be rewritten to "OR" combinations of all matching index values by Lucene. The maximum number of combinations is per default limited to 1024. A query with "a*" will therefore raise an unspecificquery error if the index contains more than 1024 terms starting with 'a'.

Examples:

Select all documents which author is "smith":

<tml:collection>
    <tml:query type="hql">
        content.author = "smith"
    </tml:query>
    <tml:forach>
         <li><tml:item name="headline"/></li>
    </tml:foreach>
</tml:collection>


An example without <tml:collection>:
<tml:query id="homeDoc" db="website" type="hql">content.uniquename = 'home'</tml:query>
<tml:item context="query:homeDoc" name="body"/>


The same example using the return attribute:
<tml:query id="homeDoc" db="website" type="hql" return="body">content.uniquename = 'home'</tml:query>


An example using default query parameter ":content" to test the target content of a relation. This will select all documents whose relation "parent-project" points to the current context document:

<tml:query type="hql">
  content.relations['parent-project'].target = :content
</tml:query>