Presets and Inherited Macros
Smartsite iXperion comes with a complete list of macros. Each of these macros has its own parameters. While developing you'll probably find out that some of the parameters will have the same value over and over again. Using presets, you can create macros with parameters set to predefined values.
Besides presetting variables, you'll probably like to create different predefinied implementations of the same macro. Using inheritance enables you to create macros that execute in a predefiined way. it is even possible to create inherited macros with a complete new name and their own virtual parameters.
The <modules> section of the Smartsite.config declares the modules to be loaded, the macros that will be available at runtime and settings to be used by them. The modules section can best be read as a set of methods sequentially applied to the runtime: there are Add, Set and Remove statements that will be applied in the given order.
Loading assemblies
First, modules are loaded from the given assembly locations:
| XML |
Copy Code
|
|---|---|
<add path="/bin/" /> |
|
Shared presets
Then, shared presets are declared:
| XML |
Copy Code
|
|---|---|
<presets>
<preset name="coollinks">
<set parameter="resultformat">
<![CDATA[<ul class="cool">{this.result()}</ul>]]>
</set>
<set parameter="rowformat">
<![CDATA[
<li>
<a href="{this.location()}">{this.title()}</a>
</li>
]]>
</set>
</preset>
</presets>
|
|
These shared presets can be applied to a list of macros:
| XML |
Copy Code
|
|---|---|
<add macro="xlinks"> <apply preset="coollinks"/> </add> |
|
Dedicated presets
If a preset applies to only one macro, it can be declared directly when adding/updating a macro.
| XML |
Copy Code
|
|---|---|
<add macro="xlinks">
<set parameter="resultformat">
<![CDATA[<ul class="cool">{this.result()}</ul>]]>
</set>
<set parameter="rowformat">
<![CDATA[
<li>
<a href="{this.location()}">{this.title()}</a>
</li>
]]>
</set>
</add>
|
|
Both in the apply and in the set methods, an overridable attribute can be used to specify whether the property/preset will be user-settable. When overridable is set to "false", the property will be fixed. Otherwise, it will merely be a default setting.
Inherited macros
You can add new macros declaratively by using the inherit attribute. Thus you can create multiple preformatted versions of the XLinks macro for example:
| Smartsite SXML |
Copy Code
|
|---|---|
<add macro="XLinks.DefintionList" inherit="XLinks">
<set parameter="format"><![CDATA[
<se:rowformat>
<dt><a href="{this.location()}">{this.field(title)}</a></dt>
<dd>{this.field(description)}</dd>
</se:rowformat>
]]></set>
<set parameter="resultformat"><![CDATA[
<dl>
{this.result()}
</dl>
]]></set>
</add>
|
|
This virtual macro XLinks.DefinitionList generates automatically a definitionlist of items based on the parent parameter. If the developer decides to overrule the rowformatting or resultformat he is free to do so. To avoid this overriding, these properties can be hidden using the overridable attribute and to prevent any formatting this attribute is added to the parameters RowDelimiter and RowFormat as well:
| Smartsite SXML |
Copy Code
|
|---|---|
<add macro="XLinks.DefintionList" inherit="XLinks">
<set parameter="format" overridable="false"><![CDATA[
<se:rowformat>
<dt><a href="{this.location()}">{this.field(title)}</a></dt>
<dd>{this.field(description)}</dd>
</se:rowformat>
]]></set>
<set parameter="resultformat" overridable="false"><![CDATA[
<dl>
{this.result()}
</dl>
]]></set>
<set parameter="rowdelimiter" overridable="false" />
<set parameter="rowformat" overridable="false" />
</add>
|
|
However, you like to set a class attribute to the dl tag in some cases to slightly change the display of the list based on CSS. This can be facilitated by adding a virtual property class to the macro. The value of this property can be read by the this.getparameter() viper.
| Smartsite SXML |
Copy Code
|
|---|---|
<add macro="XLinks.DefintionList" inherit="XLinks"
description="XLinks macro >
<set parameter="format" overridable="false"><![CDATA[
<se:rowformat>
<dt><a href="{this.location()}">{this.field(title)}</a></dt>
<dd>{this.field(description)}</dd>
</se:rowformat>
]]></set>
<set parameter="resultformat" overridable="false"><![CDATA[
<dl class="{this.getparameter(class)}">
{this.result()}
</dl>
]]></set>
<set parameter="rowdelimiter" overridable="false" />
<set parameter="rowformat" overridable="false" />
<set parameter="class" type="string"
description="Sets the class attribute of the definintion list">descriptive_list</set>
</add>
|
|
Thus, a new inherited macro is created which acts like an XLinks macro, has predefined non-overridable formatting which has a new virtual property for setting the class-attribute of the list.
Another example of a specialized macros is this copyright macro, created using the text macro and declaring some virtual properties:
| XML |
Copy Code
|
|---|---|
<add macro="copyright" inherit="text" description="Represents a customizable Copyright notice." >
<set parameter="author" description="Sets the author for the copyright notice">Somebody</set>
<set parameter="email" description="Sets the e-mail address for the copyright notice">somebody@somecompany.com</set>
<set parameter="year" description="Sets the year for the copyright notice" />
<set parameter="value">
<![CDATA[
<div class="copyright">© {this.getparameter('year', default=datetime.getyear(datetime.now()))}
<a href="mailto:{this.getparameter(email)}">{this.getparameter(author)}</a>
</div>
]]>
</set>
</add>
|
|
Removing macros
After customizing and inheriting, you can remove macros explicitly so they cannot be used at runtime (but macros that inherited from them can!):
| XML |
Copy Code
|
|---|---|
<remove macro="xlinks"/> |
|