Parameters

Macros have parameters to change their behavior. These parameters can be added as attributes:

Smartsite SXML	Copy Code
<se:xlinks parent="2" />

The parameters can also be added using a parameters node. To avoid collisions with other mark-up languages these parameter blocks use  the se-prefix:

Smartsite SXML	Copy Code
<se:xlinks>   <se:parameters>     <se:parameter name="parent">2</se:parameter>   </se:parameters> </se:xlinks>

The use of a parameters block might look verbose. However, mostly both attribute and parameter notation can be used, and the notation depends on the usage. In the example above. The parent parameter obviously could be easily written as an attribute. But in case of formatting, where more complex node-values are added, the parameter notation is used:

Smartsite SXML	Copy Code
<se:xlinks parent="2">  <se:parameters>   <se:parameter name="rowformat">    <li>{this.field(title)}</li>   </se:parameter>   <se:parameter name="resultformat">    <ul>     {this.result()}    </ul>   </se:parameter>  </se:parameters> </se:xlinks>

Each macro impements its own parameters. Besides these parameters, there are shared parameters as well which apply to all macros.

Parameter Datatypes

Parameters are strongly typed. The value assigned to a parameter should match this datatype. If not, the macro will not execute and an error is raised. For example, the MaxRows parameter of the XLinks macro has datatype Integer. The next example will generate an error:

Smartsite SXML	Copy Code
<se:xlinks parent="2" maxrows="one" />

While this example gives a correct result:

Smartsite SXML	Copy Code
<se:xlinks parent="2" maxrows="1" />

Parameter Properties

Parameters have properties indicating how to use the parameter. For example, some parameters can only be declared as an attribute, while other parameters can be declared within a parameter block as well.

Must be attribute

Some parameters can only be added as an attribute. These parameters are used when an macro is initialized whereas the other parameters are called when the macro is executed. For example, the Condition shared macro parameter holds a condition whether the macro can be executed or not. If this parameter is declared as an Xml node, the macro should be parsed before the parameter can be resolved. Once the condition is not true, futher parsing of the macro is not neccessary anymore. Parsing the macro and finding out the macro should not be executed is an unwanted overhead. Therefore, the Condition parameter is must be an attribute.

Default

Some macro parameters are so-called default parameters. These parameters do not have be declared. The value of these parameters can be written directly in the inner Xml of the macro. The value parameter of the text macro is an example:

Smartsite SXML	Copy Code
<se:text>hello world</se:text>

Required

Some macro parameters are required. If these parameters are onmitted, macro execution cannot take place. In next example, the SearchFor parameter of the Replace macro is required.

Smartsite SXML	Copy Code
<se:replace searchfor="Hello" replacewith="Hi">Hello world</se:replace>

ExpressionSyntax

Parameters should match their datatype. One of these datatype is String. However, sometimes a string isn't a string but an expression which should be evaluated by the Expression evaluator. For example, the Expression parameter of the If macro is handled as an expression, while the Value parameter of the Text macro is handled as a string.

Smartsite SXML	Copy Code
<se:if expression="2 GT 1" then="Aha, two is greater than one" /> <se:text value="2 GT 1" />

RawData

Once a parameter is retrieved by the Xml parser, nested macros and vipers are evaluated directly, thus creating a linear recursive stack based handling of the SXML document. However, in some cases, especially in formatting, the value of the parameter should not be evaluated. In case of formatting, for example, the value of the parameter should be evaluated once the complete macro is parsed.

Have a look at the example below. The shared macro parameter ResultFormat formats the entire result of the macro. The Resultformat parameter has the property RawData. When the macro is executed, the parameters are passed to the Xml parser. The string.toupper() should be evaluated directly when the parameter is read, but the this.result() viper should be evaluated afterwards, when the macro returns a result. Therefore, the Resultformat parameter does have the Rawdata property.

Smartsite SXML	Copy Code
<se:text value="{string.toupper(hello world)}" resultformat="-- {this.result()} --"/>

Encoding your data

When the data within parameter nodes is not well-formed, use CDATA sections:

Smartsite SXML	Copy Code
<se:sqlquery>   <se:parameters>     <se:parameter name="sql"><![CDATA[       select * from vwusers where nr < 1000000     ]]></se:parameter>     <se:parameter name="rowformat">{this.field(fullname)}</se:parameter>     <se:parameter name="rowdelimiter"><br /></se:parameter>   </se:parameters> </se:sqlquery>

... or encode the data:

Smartsite SXML	Copy Code
<se:sqlquery>   <se:parameters>     <se:parameter name="sql">       select * from vwusers where nr {char.lt()} 1000000     </se:parameter>     <se:parameter name="rowformat">{this.field(fullname)}</se:parameter>     <se:parameter name="rowdelimiter"><br /></se:parameter>   </se:parameters> </se:sqlquery>