Smeretags

Lookup fields (or Smereka tags, for short – smeretags) are parts of HTML code. They can be used in any attribute that contain HTML code, for example, HTMLCode attribute.

To make lookup fields "live", one need to insert them into the HTML code of the page, then Smereka, while compiling page, calculate their values and replace smeretags with these values.

So, Smereka offers two main ways to insert smeretags: static, when smeretags placed in page template, and dynamic, when smeretags placed in some text attribute of node (and this attribute itself is inserted into a page using smeretag). Finally, Smereka programmer, developing their own modules can independently perform smeretags calculations if standard procedure of automatic calculation does not fit his intentions.

Rules for writing smeretags

Smeretag is an XML tag. As each XML tag, it can be single:

<Smereka [attrs list] />

or double:

<Smereka [attrs list]>Substitution text</Smereka>

Single tag must necessarily end with a slash and a "more" sign, between which there should be no spaces. As everywhere in XML, tag names and attributes are case-sensitive!

List of attributes conforms to the XML:

Param1="Value1" … ParamN="ValueN"

List items are separated by spaces. Attribute name and value combined with equal sign with no spaces. Attribute values must enclosed in quotes. Quotes in attribute values not allowed, instead of them should take the entity &quot; (escaping with back slash \ does not work).

According to the rules of HTML tags, tags which are unknown to browser are skipped. So, if substitution fields are not compiled, the single Smereka tag remain invisible, and double tag will appear as Substitution text.

Smeretags-attributes

According to the rules of HTML attribute value can not contain tags. To circumvent this limitation, Smereka offers alternative smeretags syntax, where curly brackets using instead of broken:

Using this alternative syntax can build correct structures like:

<img src="" />

Nested smeretags

Smeretags recorded using the syntax

<Smereka [attrs list]>Substitution text</Smereka>

can contain other smeretags in the Substitution text. To correctly specify a sequence of closing tags </Smereka> one must use numeric suffixes:

<Smereka10 [attrs list]>
 Static substitution text
 <Smereka5 [attrs list]> Dynamic substitution
 text </ Smereka5>
 <Smereka5 [attrs list]> Another dynamic
substitution text </ Smereka5>
 <Smereka [attrs list]>
 Deeper nested text
 </ Smereka>
</ Smereka10>

The general rule is that the substitution text must not contain the tag Smereka with the same numeric suffix as covering tag.

The sequence of smeretags calculation

Smeretags calculated as follows:

all tags <Smereka [attrs list]>Substitution
text</ Smereka>
all tags 
all tags 
all tags <Smereka [attrs list] />

Knowledge of this sequence may have some practical benefits. For example complex smeretag

 <Smereka Func="GetDocTitle"
NodeId="{Smereka Func="GetAttr" AttrName="link" /}" />

does exactly what it wanted from: it first extract value of link attribute for the current node and then calculates DocTitle for this (not current!) node.

Required attributes

Method="MethodName". The value of this attribute is the name of the Page object method or its descendant. If this attribute is set, this method will be invoked and the remaining parameters will be passed to it. If the method is not found, smeretag return an empty string.

Func="FuncName". The value of this attribute is a name of Smereka function; the remaining parameters will be passed to it. If the function is not found, smeretag return an empty string.

Module="ModuleName". This attribute acts as a pair of attribute Func. The value of this attribute is the name of the PHP module, which contains the desired function, for example:

 <Smereka Module="aggregators/navigators.php"
Func="NavigatorItem" />

Please be aware that the most popular features are collected in smeretags/substfields.php module and this module is always available during compilation smeretags. Therefore, this value can be omitted (recommended).

If required module cannot be loaded, smeretag return an empty string.

So, only one of the options Func|Method is required. All other parameters are optional and depend on which method (function) is called. Detailed description of possible parameters published in the relevant functions.

Contextual node

Each time the smeretag function / method is invoked Smereka passing to it the parameter BaseNode containing node, which define the context of smeretag calculation. This parameter is added automatically and should not be specified in the smeretag parameter list.

So if other options do not determine another context of calculations, calculations are carried to the BaseNode node.

The function prototype

Any PHP function can be invoked via smeretags, if it comply the following prototype:

 string FuncName (array $Params)

where $Params is hash array of parameters. It always contain at least one element – BaseNode, and other parameters can be provided as needed.

If smeretag contain Substitution text, this text will be passed as SmerekaValue parameter.

The function should return the result as a string or an empty string if error.

Similar rules apply for methods that will be called from smeretags.