| Xaraya | M. Vance |
| Request for Comments: 0010 | P. Rosania |
| Category: Standards Track | M. Canini |
| M.R. van der Boom | |
| J. Dalle Nogare | |
| Xaraya Development Group | |
| November 2002 |
RFC-0010: Block Layout (Xaraya Theme System)
This document specifies an Xaraya standards track protocol for the Xaraya community, and requests discussion and suggestions for improvements. Please refer to the current edition of the “Xaraya Official Standards” (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.
Copyright © The Digital Development Foundation (2002). All Rights Reserved.
1 The contents of this RFC describes the blocklayout templating system for xaraya.
2 Blocklayout is intended to give theme developers a maximum of control over the appearance and functionality of their Xaraya website. This file documents the structure and syntax of blocklayout, and details required changes to themes and the core.
3 Blocklayout is potentially a very powerful tool. However, modules and blocks need to be modified somewhat in order to take advantage of Blocklayout's flexibility. The conversion process is not complicated.
4 Dynamic data properties, like modules and blocks, can also provide a flexible templated output after a conversion process.
5 In addition, certain changes to the Xaraya directory structure are necessary to accomodate templates and their defaults. Those structural changes are illustrated below.
html/
|-- modules/
| |-- <module name>/
| |-- xartemplates/
| | <user|admin>-<module function>[-<template>].xd
| |-- blocks/
| | <block name>-<template name>.xd
| |-- includes/
| | <file>.xd
| |-- objects/
| | show<display|form|list|view>[-<objectname>].xd
| |-- properties/
| <showinput|showoutput|showlabel|showvalidation|showdisplay|showhidden|_showPreset>[-<propertyname>].xd
|-- includes/
| |-- xarTemplate.php
| |-- xarBLCompiler.php
| |-- blnodes/
| |-- entities
| |-- instructions
| |-- tags
|-- themes/
|-- <theme name>/
|-- theme.php
|-- pages/
| <master templates>.xt
|-- modules/
| |-- <module name>/
| | <user|admin>-<module function>[-<template name>].xt
| |-- blocks/
| | <block name>-<template name>.xt
| |-- includes/
| | <file>.xt
| |-- objects/
| | show<display|form|list|view>[-<objectname>].xt
| |-- properties/
| <showinput|showoutput|showlabel|showvalidation|showdisplay|showhidden|_showPreset>[-<propertyname>].xt
|-- includes/
<file>.xt
6 html/themes/<theme name>/xartheme.php contains metadata about the theme; no actual markup can reside there. Such metadata includes:
18 The following is a list of CSS classes which may be referenced by module and block developers with assurance that their output will integrate well with any Blocklayout theme. Blocklayout themes must define all of these classes.
19 The first group is standard classes. Selectors here will be applied to every instance of a tag, unless overridden by a more specific class.
51 Next are individual classes, mostly related to tables. Unlike previous versions, Blocklayout 1.1 relies on CSS inheritance to style individual tags; this makes many inidividual rules unnecessary.
54 Finally are anonymous classes. Selectors here can be applied to any tag.
81 Rules with partially bracketed names are optional. Rules applied to individual blocks are left up to the theme author. Additional menu item rules may be devised as necessary to satisfy the depth of the menu.
82 Theme developers may introduce their own classes in their templates. This practice should be avoided by module and block developers. Extensions of the required classes list will not be supported by other themes or modules, and are not endorsed by Xaraya.
83 These classes allow each block or group of blocks to have a different appearance than modules (normal).
84 It is suggested that the classes be defined in the given order, to avoid odd results in different browsers.
85 Each page in Blocklayout is assembled from a collection of templates and fitted with the necessary data. A "Master" template is loaded first. This template defines the basic layout of the page and what information will be presented. Each module function or block called from the Master template has a child template associated with it. The data it handles is parsed through this template before being inserted into the Master. In this manner, templates can be nested any number of levels deep.
86 Internal Templates (.xd) provide default output formatting for Xaraya modules. Themes cannot alter these templates, but may contain their own version of them. Be careful! Editing Internal Templates may cause Xaraya to behave unexpectedly or not at all.
87 The first time a template is called, it is compiled into PHP code. It will not be compiled again unless the original copy is updated. This procedure allows a maximum of template flexibility without slowdown in page generation time.
88 Tags in Blocklayout adhere to XML syntax. The standard Blocklayout namespace is "xar" and at this time that may not be changed. There is one root tag:
88 The following tags can be used in any context:
88 The following tags have a specific context:
111 Blocklayout variables are delimited by # ... #. For example, the variable $foo is accessed by the #$foo# directive.
112 String keys in arrays should be single quoted (#$foo['bar']#) rather than double (#$foo["bar"]#). The preferred syntax for keys uses a 'dot' to specify the keys. #$foo.bar# is equivalent to #$foo['bar']#. These can go down to any level and can include numbers, for example, $foo.bar.dee.2
113 Similarly, referencing object members (properties and methods) can be done using the 'colon' notation. #$foo:bar# is equivalent to $foo->bar. This is the only way to refer to object members, as the '>' characters would have to be escaped.
114 The 'dot' and 'colon' notation can also be combined if needed. For example: #$foo:bar.test# is equivalent too $foo->bar['test']. For array key, numeric and variable keys are also recognized ( #$foo.$bar# equals $foo[$bar] and #$foo.4# equals $foo[4] )
115 In addition to template variables, Blocklayout also allows direct access to a limited set of xarAPI functions (list to be determined). Function calls are represented as #xarAPIFunc($arg1, 'arg2')#. Function arguments should also be single quoted (as necessary). In general this is discouraged though.
116 Placing comments in Blocklayout templates is done by surrounding the content in question with <xar:comment> .... </xar:comment> Content within these tags will be stripped from the final output stream. Standard two-hyphen comments (<!-- -->) will be passed on to the output stream.
117 We used to have the <--- ---> construct, but this is invalid XML, do NOT USE this anymore. Note that inside <xar:comment/> tags, things will still have to be valid XML. If you want complete freedom on what to put inside your comments, you'll have to experiment with CDATA sections and <-- style comments inside the <xar:comment> tag.
118 A note on logic tags: The condition attribute present on most logic tags will frequently call for the use of <, >, and & characters. These characters are restricted in XML documents and may not be used in this context. Therefore, to present an easy, readable alternative to PHP comparison operators, Blocklayout uses Perl-like string operators within templates. Assignment operators are not affected. See below:
BL operator PHP operator English
eq == equal to
id === identical to
lt < less than
gt > greater than
le <= less or equal to
ge >= greater or equal to
ne != not equal to
nd !== not identical to
and and and
or or or
xor xor exclusive or
not not not
119 For the description of the tag attributes the following conventions are used:
124 The 'context' section for each tag description describes to which 'parent' tag the described tag belongs, in the sense of required structure, and the child tags which are expected before the closing tag, again in terms of required structure.
125 The <xar:blocklayout /> tag is the root-tag of a blocklayout complete template. With a complete template we mean the assembly of the page level template, the relevant module templates and all other template snippets necessary to construct the complete template for a particular request.
126 Note that this complete template does not (yet) exist in one piece anywhere, it is assembled from the several templates applicable for a certain request.
127 A root tag is required in each valid XML document and can occur only once. For Xaraya this means the <xar:blocklayout /> tag occurs in a page template only; once as opening tag at or near the beginning of the template and once as closing tag at the end of the page template.
128 This tag only has an open form
129
131 required attribute. At the moment of writing blocklayout is at version 1.0 or below, since we are still in beta. When new versions of the blocklayout language are released this attribute is used for compatability issues. The version number indicates what version of the blocklayout syntax to expect in the templates.
133 The content attribute denotes the type of content the page template describes. The value of this attribute is a legal string according to the IETF RFC describing mime-types. The default content type is "text/html"
134 The complete MIME type functionality is described in several IETF RFCs. The most relevant one for this RFC is: http://www.ietf.org/rfc/rfc2046.txt There are a large number of content types which can be specified. The most relevant ones for blocklayout are in the 'text' type of content. Examples:
139 In theory, blocklayout could support any mimetype, but the text and application types will be the two types, with their respective subtypes which will be used most frequently
141 declaration of the xar namespace. As we currently hardcode the namespace this attribute can only have the value:
xmlns:xar="http://xaraya.com/2004/blocklayout"
143 The dtd attribute tells BlockLayout what type of document it should produce. Your BL template as such should NOT contain a DOCTYPE tag for reproduction in the output (although it will copy it to the output unmodified). The doctype of the (page-)template should be before the root tag and it should be:
<!DOCTYPE blocklayout PUBLIC "-//XAR//DTD BL 1.0 Strict//EN" "http://xaraya.com/bl1/DTD/bl1-strict.dtd">
144 The possible values for the dtd attribute are the valid document types listed at w3.org. The corresponding values and what will be produced in the output document are as follows:
'html2' : '<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">',
'html32' : '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">',
'html401-strict' : '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">',
'html401-transitional' : '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">',
'html401-frameset' : '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">',
'xhtml1-strict' : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
'xhtml1-transitional' : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
'xhtml1-frameset' : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
'xhtml11' : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
'mathml101' : '<!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd">',
'mathml2' : '<!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/TR/MathML2/dtd/mathml2.dtd">',
'svg10' : '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">',
'svg11' : '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">',
'svg11-basic' : '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd">',
'svg11-tiny' : '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd">',
'xhtml-math-svg' : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">',
'svg-xhtml-math' : '<!DOCTYPE svg:svg PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">'
145 At this point, there is no flexible mechanism to add other (valid) DTD specifiers, but to add them in the code.
146
<?xml version="1.0" encoding="utf-8"?>
<xar:blocklayout version="1.0" content="text/html" xmlns:xar="http://www.xaraya.com/2004/blocklayout" dtd="xhtml1-strict">
<!-- Rest of the page level template goes here -->
</xar:blocklayout>
147 This tag is the root tage of the blocklayout language, it has no parent tags and all other tags are children of this tag.
148 The xar:block tag places a "block" of content into the output. A block is always owned by a module, which is responsible for feeding the block with the appropriate information to produce its output. There are a number of flexible ways to control what a block contains and how it will appear in the output.
149 The block tag is one of the most flexible constructs in blocklayout (how surprising). We haven't even touched at all the possibilities ourselves yet. Unfortunately this makes it also the most untested area in blocklayout and vulnerable for surprises.
150 There are two approaches to content that blocks take. They are:
153 Static content blocks are defined completely within their template file, and are not dependent on any other information. A block containing a piece of html to render is an example of such a block. Dynamic blocks however, have dynamic contents. This means that their content depends on a certain state of the site at a certain moment in time. Examples of this type are: "Last 5 items posted on site", "Currently logged on users" etcetera. Each block consist of a title and content. The title may be an empty string.
154 In essense though, there is no difference in the way that blocks with static or dynamic content are managed.
155 Empty form:
156 Since a block accepts structured data in its overriding parameters, this tag only supports the empty form at present.
157
158 A block is identified by its instance or by the module and type. A block identified by its instance, will have been created through the blocks administration screens, and will have custom content set. A block identified by its module/type does not need to created first through the blocks admin screens, and will initially contain default content for that block type.
160 an identifier for the tag
162 If instance is specified, it's value is used to look up the the specific block in the database. The instance can take the form of a block ID or a block name.
164 Name of the module which owns the block. In the administration part of Xaraya this is visible when looking at the block types. This attribute must be used in conjunction with the [type] attribute.
166 Name of the block to display. The name is the value of the field filled in by the site manager in the administration part of Xaraya. This attibute must be used in conjunction with the [module] attribute.
168 The name of the block to display. The name is used only for security checks, to determine whether the block should be loaded at run-time.
170 The title to use for the block.
172 The state of the block (0 is hidden, 3 is maximized).
174 Name of a template to use for the block. The template attribute can define two templates: the box template and the block template. Essentially the block template defines the layout within a block and the box template defines a wrapper to go around the block. The format of this attribute is: box-template;block-template - both of which are optional. Default templates will be used if none are specified with this attribute.
176 All other attributes are passed to the block as overriding parameters. The attribute names are specific to each block. A system for allowing a block to declare which attributes are available, and what kind of validation will be performed on them, will also be in place. Blocks not declaring allowed attributes will not have any restrictions placed on the overriding parameters passed in to them, so be aware that without validation, rendering results can be undefined.
177
178 This renders block instance number 2, or the block instance named 'block_x', directly. The 'module' and 'type' attributes are ignored, since we are using the instance attribute to identify a block that has been pre-defined though the admin screens.
<xar:block instance="2" module="base" />
<xar:block instance="block_x" type="random" />
179 Look for block 'goodie' owned by module 'base' (this provides the implicit content) and try to render it with box template 'block_2'. The block will execute with it's default parameters.
<xar:block module="base" name="goodie" template="block_2" />
180 This block has explicit contents specified directly in the block tag. That content will be rendered by applying the default block template from the 'base' module and block 'goodie' (which may still be overridden by the theme). It will also be enclosed in the default box template from the current theme (usually blocks/default.xt).
<xar:block module="base" name="goodie" />
181 This example will render the articles/topitems block, displaying just two items, with a static (i.e. non-dynamic) title 'Standalone Topitems', and a default state of 3 (maximised). The block will be named 'standalone_topitems', and that name can be used to hide that block from some users through the permissions system. The box (outer) template will be 'right' (in {current-theme}/blocks/right.xt, falling back to default.xt if that template cannot be found). The block (inner) template is specified as 'mytop'. The customised block template will be {current-theme}/modules/articles/blocks/topitems-mytop.xt, falling back to topitems.xt and then modules/articles/xartemplates/xarblocks/topitems.xd. This block has not been pre-defined through the block admin screens.
<xar:block module="articles" type="topitems" title="Standalone Topitems"
state="3" numitems="2" dynamictitle="false" name="standalone_topitems"
template="right;mytop" />
182 Parent tag: <xar:blockgroup> when that tag is used in block form.
183 Child tags: none
184 The Blockgroup tag is responsible for rendering a group of blocks. If empty, it renders the named group from the database. Otherwise, it can specify the box template to use on all <xar:block/> tags within it.
185 Empty form
186 The group of blocks is determined at runtime based on the value of the name attribute. The name references a value entered in the blocks adminstration indicating which block group to render.
187 Block form
188 When specified as a block tag all the block tags specified within the blockgroup are rendered.
189
191 an identifier for the tag.
193 The name of the block group to render. When the tag is used in its empty form this attribute is required. The attribute is ignored when the tag is used in its block form.
195 Name of the box template to use by default on all blocks within the blockgroup tag. In its empty form, the template will be used to wrap all blocks within it. In its non-empty form, each block may individually override the box template, but otherwise will share the template defined by this attribute. This attribute is optional.
196
Renders the blockgroup 'left'. The template attribute is ignored or,
when in strict rendering creates an exception:
<xar:blockgroup name="left" template="SeaBreeze_left"/>
Renders the block 'login' in a blockgroup using the template
'SeaBreeze_center' for the blockgroup. The login block uses the block
(inner) template 'simple_login' and is wrapped in the box (outer)
template 'SeaBreeze_center':
<xar:blockgroup template="SeaBreeze_center">
<xar:block type="login" module="users" template=";simple_login"/>
</xar:blockgroup>
197 Parent tag: none.
198 Child tags: in block form at least one <xar:block> tag.
199 Escapes the closest <xar:for />, <xar:foreach />, <xar:loop />, or <xar:while />. The depth attribute, if present and an integer greater than 1, an equal number of enclosing loops are broken out of.
200 Only in empty form
201
203 an identifier for the tag (optional)
205 how many levels of enclosing loops to be broken out of.
206
<xar:for start="$i = 0" test="$i lt 10" iter="$i++">
<xar:if condition="$i eq 5">
<xar:break/>
</xar:if>
#$i#
</xar:for>
207 The above will generate:
01234
208 Parent tags: <xar:for />, <xar:loop />, or <xar:while />.
209 Child tags: none
210 Marks a block of a template as being a comment, which will not result in any output. The tag is primarly used to supply templates with comments for developers and theme designers. Anything inside the xar:comment block will be ignored.
211 Only to be used in open form
212 none
213
<xar:comment>
The contents of the comment tag will be ignored completely
</xar:comment>
214 Parent tags: none
215 Child tags: none
216 Ends the current iteration of a <xar:for />, <xar:foreach />, <xar:loop />, or <xar:while />, and begins the next iteration. If the depth attribute is present and an integer greater than 1, an equal number of enclosing loops are skipped to the end of their current iteration.
217 Only to be used in empty form
218
220 an identifier for the tag (optional)
222 how many levels of enclosing loops to skip to the end of (optional)
223
<xar:for start="$i = 0" test="$i lt 10" iter="$i++">
<xar:if condition="$i eq 5">
<xar:continue/>
</xar:if>
#$i#
</xar:for>
224 The above will generate:
012346789
225 Parent tags:
226 <xar:for /> <xar:loop />, or <xar:while />.
227 Child tags: none
228 Separates template code within an <xar:if /> tag. When the condition of the <xar:if /> tag is true, the template content preceeding <xar:else /> is executed. Otherwise, the template content after <xar:if /> is executed. When <xar:elseif />is used within an <xar:if /> block, <xar:else /> must appear last.
229 This tag has only an empty form
230
232 an identifier for the tag (optional)
233 See <xar:if /> for syntax.
234 Parent tag: <xar:if />
235 Child tags: none
236 Contains template code to be executed if all related preceeding <xar:if /> and <xar:elseif /> tag conditions evaluate to false. All instances of <xar:elseif /> attached to <xar:if />must appear before <xar:else />
237 This tag has only the empty form
238
240 an identifier for the tag (optional)
242 The condition attribute is specified as a PHP expression which should evaluate to false or true. Within the condition attribute, normal php expressions can be used with one exception. When comparing values, the < and > would conflict with XML syntax. See the note on logic tags above for the details.
243 See <xar:if /> for syntax.
244 Parent tag: <xar:if />
245 Child tags: none
246 The <xar:for> tag is a control structure which emulates a for loop, like encountered in most programming languages. Based on a 'start', 'test' and 'iter' attribute, the child tags of the tag are processed zero or more times.
247 Only allowed in block form.
248
250 an identifier for the tag
252 An expression which should evaluate to a value, which is taken as the initial value of the loop variable to iterate over.
254 The condition to test the iterated value against. This attribute is a php expression which should evaluate to false or true on each iteration. The for loop stops iterating when the value of the 'test' attributes is false. Again, when using comparison operators refer to the note on logictags
256 The action to perform at the end of each pass through the loop. The blocklayout for construct is just as susceptible to infinite looping as any for construct in another language. In fact, the 'for' tag is almost literally translated into a for construct in php. Anything which can go wrong with a php for loop, also holds for the blocklayout variety of it.
257
<xar:for start="$i = 0" test="$i le 10" iter="$i++">
// stuff which gets processed while $i less than or equal to 10
</xar:for>
258 Parent tag: none.
259 Child tags: none
260 Iterates over an array, assigning each element in in to value using key. Note that the order in which the elements are processed is NOT GUARANTEED to be the same order as the elements of the 'in' attribute. If you absolutely want to make sure the elements are processed in the order in which they are stored in the array you should use the xar:loop element.
261 The foreach construct operates on copies of the variables specified in its attributes. A 'save scope' is created for them. This means, that whatever the value was for a variable before the foreach construct, it's guaranteed to have the same value after the foreach construct.
262 Only allowed in block form
263
265 an identifier for the tag
267 An expression which evaluates to the name of an array containing the elements to process. Normally this will just be the array variable itself ($varname)
269 Variable to assign the key of the array to. This attribute is optional. If it is not specified, no key is used in the foreach loop. If it is not specified, the 'value' attribute is required.
271 variable to assign value to. If this attribute is not specified the 'key' attribute is required and the key is used to loop over the elements.
272
<xar:foreach in="$hooks" key="$hookmodule" value="$hookoutput">
// stuff to process
</xar:foreach>
273 Parent tag: none.
274 Child tags: none
275 Contains template code processed if the condition evaluates to true. The value of Condition is a php expression.
276 Only allowed in block form
277
279 an identifier for the tag
281 A php an expression evaluating to false or true. When it evaluates to true, the children of this element are processed. For comparison operators refer to the note on logic tags
283 Defaulting to false, this attribute specifies whether the condition should be in assignable (inline) form. This correspond to the php expression : (condition ? truepart:falsepart)
284 Note: this attribute is not implemented yet
285
<xar:if condition="$func eq 'editStory'">
// stuff
<xar:elseif condition="$func eq 'saveStory'" />
//more stuff
<xar:elseif condition="$func eq 'viewStory'" />
//still more stuff
<xar:else />
//even more stuff
</xar:if>
286 Parent tag: none.
287 Child tags:
288 <xar:else />
289 <xar:elseif />
290 Loop allows theme authors to execute snippets of a template multiple times based on a condition.
291 Only allowed in block form
292
294 an identifier for the tag
296 The name of an array variable over which the loop executes. The elements are guaranteed to be processed in the same order as they are stored in this array.
298 In the body of the loop, a number of special variables are accessible to access the loop variables:
#$loop:[id:]item['var']# ; or
#$loop:[id:]item.var# : if you created the $module_data array and put in a
variable call 'var' the value of this variable is
displayed. Optionally you can specify id: to reference
other loop constructs.
#$loop:[id:]index# : the numeric loop index (of loop with id 'id')
#$loop:[id:]number# : the loop number in the current context. This can also be
interpreted as the current loop nesting level
#$loop:[id:]key# : the key of the item being referenced
299 The 'id' part in these variables refers to other loops. When nesting loops, the right variables from the right loops can be accessed this way. As for the foreach construct the loops are executed in a 'save scope'; the values outside the loops are not affected by the loops.
300
<xar:loop name="$module_data">
// stuff
<p>#$loop:item.title#</p>
</xar:loop>
301 Parent tag: none.
302 Child tags: none
303 The <xar:ml> tag is a wrapper for <xar:mlkey /> and <xar:mlstring /> when their values contain placeholders. These placeholders are replaced by the variable in the <xar:mlvar /> tags in the order they appear in the template.
304 The enclosing <xar:mlstring> or <xar:mlkey> should have placeholders in its definition of the form #(1)..#(n) if there are 'n' variables to be replaced. The contents of the first <xar:mlvar> tag is put in the place of #(1), the second in the location of #(2) etcetera.
305 Only allowed in block form
306
308 an identifier for the tag
309
<xar:ml>
<xar:mlkey>USERSONLINE</xar:mlkey>
<xar:mlvar>78</xar:mlvar>
<xar:mlvar>120</xar:mlvar>
</xar:ml>
The values of $var1 and $var2 are put in the place of
#(1) and #(2) in the definition of the key 'USERSONLINE'.
Note that these aren't visible in the template itself.
<xar:ml>
<xar:mlstring>There are #(1) members and #(2) guests online.</xar:mlstring>
<xar:mlvar>#$members#</xar:mlvar>
<xar:mlvar>#$guests#</xar:mlvar>
</xar:ml>
Same as first example, but with the <xar:mlstring> form.
310 Parent tag: none.
311 Child tags:
312 <xar:mlkey />,
313 <xar:mlstring />,
314 <xar:mlvar />, (optional)
315 <xar:mlkey> retrieves a multilanguage string based on the database key contained in the tag. If the resulting string does not use placeholders, mlkey may be used alone. Otherwise, mlkey must have <xar:ml /> as a parent tag, with <xar:mlvar /> tags as siblings. See <xar:ml /> for syntax examples using placeholders.
316 Only block form is allowed
317
319 an identifier for the tag
320
<xar:mlkey>LOGIN</xar:mlkey>
Retrieves the 'LOGIN' key in the appropriate language and puts its
contents in the current context.
321 Parent tag:
322 <xar:ml /> (optional).
323 Child tags: none
324 <xar:mlstring> processes a multilanguage string. It first finds the string in the db and, based on the string's key, returns the corresponding string in the current locale. If the resulting string does not use placeholders, mlstring may be used alone. Otherwise, mlstring must have <xar:ml /> as a parent tag, with <xar:mlvar /> tags as siblings. See <xar:ml /> for syntax examples using placeholders.
325 Only block form is allowed
326
328 an identifier for the tag (optional)
329
<xar:mlstring>Remember Me</xar:mlstring>
The string 'Remember Me' is looked up and translated
into the appropriate language.
330 Parent tag:
331 <xar:ml /> (optional).
332 Child tags: none
333 Contains a string passed to an accompanying <xar:mlkey /> or <xar:mlstring /> to occupy a place holder.
334 Only block form is allowed
335
337 an identifier for the tag
338 See <xar:ml /> for syntax examples using placeholders.
339 Parent tag:
340 <xar:ml />
341 Child tags: none
342 The module tag produces output generated by a module. When the 'main' attribute is true, this tag acts as a placeholder for the output of the main module function, and the module gets all variables needed directly from the core. The main module function itself is at this moment executed by the core *before* template loading.
343 On the other hand, if a module and optional other attributes are specified, this tag will call the corresponding module function during the template loading, and insert its output here.
344 Only empty form is allowed
345
347 an identifier for the tag
349 Boolean specifying whether this is for the main module output or not. The attribute is required, but the actual value isn't used. See below.
350 Note: this attribute is likely to be deprecated, because it is redundant, the presence / absence of the module attribute is enough to decided whether the default module should be used or not. At this point, the 'main' attribute is required, but the code actually checks the presence of the 'module' attribute to decide what to do. If this attribute is not specified the rest of the attributes is ignored, and the main module output is used.
352 Name of the module to call, if it is not the main module.
354 The type of function to call, if this attribute isn't specified the value defaults to 'user'
356 Name of the function to call. The value defaults to 'main' if not specified.
358 array of arguments to pass to the function, or
360 Individual arguments to pass to the function. This means if you specify param="4", test="yes", the attributes are translated by blocklayout into an argument array and passed to the function. In this example:
array('param' => '4', 'test' => 'yes)
would be passed to the function 361
<xar:module main="true" />
Main module output will be used (not because main="true" but because module isn't specified.
<xar:module main="false" module="polls" />
The 'main' function from the 'polls' module will be called from the 'user' part of the module
<xar:module main="false" module="$mymodule" type="user" func="$func" args="$args" />
The value of $func, $mymodule and $args will be used to determine the module to use, which
function to call and which arguments to pass. The function is looked up in the 'user' section
of the module. Note that the 'type' attribute in this case is redundant.
<xar:module main="false" module="articles" type="user" func="view" ptid="1" numitems="10" startnum="$startnum" />
From the 'articles' module, the 'user' 'view' function is called, with parameters ptid,numitems and startnum
362 Parent tag: none.
363 Child tags: none
364 <xar:sec> translates directly to a call to xarSecurityCheck(), and is treated like an 'if' clause. <xar:else /> and <xar:elseif /> tags may be attached as for an <xar:if />.
365 Only block form is allowed
366
368 an identifier for the tag
370 The mask for which to check the privileges. This is a required attribute. Refer to RFC-0030 for the full details on the security system.
372 Sometimes it may be necessary to check for a certain security privilege, but not raise an exception if the privileg check fails. In those cases, specify catch="false" and no exception will be raised. By default, if a security check fails, an exception will be raised.
374 For which component will the security check be done? Defaults to empty.
376 For which instance will this check be made? Defaults to empty
377
<xar:sec id="unique1" mask="EditCategories" catch="false" component="mycomponent" >
<p>You are granted access</p>
<xar:else/>
<p>Sorry, no can do </p>
</xar:sec>
Checks for the 'EditCategories' mask on 'mycomponent'. If the check fails (no privilege)
no exception is raised but the text 'Sorry, no can do' is added to the output.
378 Parent tag: none.
379 Child tags:
380 <xar:else />
381 <xar:elseif />
382 Sets the variable identified by the 'name' attribute to the value generated of the tag's body. The variable must be available in the scope of the tag. Values set this way do not persist beyond the current page load.
383 Note: <xar:set> is a bit of a problem child. It is the most vulnerable tag we have, security wise. As the base compilation translates this tag into something like: " echo .....", with some work it's easily abused as a php-scripter tag in our current setup.
384 Only block form is allowed
385
387 An identifier for the tag
389 The name of the variable to be set
391 Note: this attribute is not implemented
392
<xar:set name="$foo">'bar'</xar:set>
Sets the value of variable $foo to 'bar'
393 Parent tag: none.
394 Child tags: none
395 Opens the file specified by the 'file' attribute and processes it within the context of the calling template. Included templates are stored in:
399 The 'file' attribute determines the basename of the file to be included, the extension will be filled in by xaraya whether the template is included from an internal source or an overridden location in the theme.
400 The 'module' attribute defines which module the template file is located in, in conjunction with the 'type' attribute as described below. If this attribute is omitted the module where the tag resides is assumed.
401 The 'type' attribute tells the compiler where to look for the file. If the value is 'module', the template to be included belongs to the module and Xaraya looks in (in this order):
404 If the value is 'theme', Xaraya uses the following locations:
406 If the value is 'system', the file attribute is interpreted as a relative location to the containing filename. These so called 'system' includes are formally not part of the 'module-space' or 'theme-space' and as such cannot be overridden. This tag is used to guarantee that the template contents is used regardless of the theme being used, unless the theme overrides the container template which does away with the xar:template tag in the overridden template.
407 Only the empty form is allowed
408
410 An identifier for the tag
412 the basename of the file to include.
414 module where the file resides.
416 A string which tells Xaraya what kind of template to include. If mainly affects the locations where Xaraya looks for the file.
418 This allows to pass in an array with data which should be known in the included template. When this attribut is not specified the included template will inherit the data known to the parent template.
419 When the subdata attribute is specified, only the data in the array designated by subdata will be known by the included template. This is the only way to shield data from an included template (to prevent variable collisions for example). If you want the included template to know about the parent template variables, use xar:set of pass them in from the code.
420
<xar:template file="top_links" type="theme"/>
Looks for file /theme/[themename]/includes/top_links.xt and includes
it in the current template.
<xar:template file="top_links" />
Looks for file /themes/[themename]/modules/[module name]/includes/top_links.xt
and, when found, uses it. If not found it looks for
/modules/[module name]/xartemplates/includes/top_links.xd and uses that file
<xar:template file="top_links" module="categories" type="module" />
Looks for file /modules/categories/xartemplates/includes/top_links.xd.
<xar:template file="signals/alert.xml" type="system" />
Looks for a file 'alert.xml' in the directory 'signals' below the location
of the containing template.
421 Parent tag: none.
422 Child tags: none
423 <xar:var> deals with variables in different scopes. If no scope is specified, Blocklayout returns the contents of the local variable.
424 Variables are referenced by name, without the preceeding "$". Arrays can be indexed via dot notation, i.e.:
<xar:var name="preformat.catandtitle" /> ( meaning: $preformat['catandtitle'] )
objects can be specifiek using colon notation, i.e:
<xar:var name="preformat:catandtitle" /> ( meaning: $preformat->catandtitle )
425 The 'scope' attribute value has the following effect:
434 The value of the 'scope' attribute does reasonably straighforward determine the function which Xaraya uses to get the right variable
435 Only empty form is allowed
436
438 An identifier for the tag
440 What kind of variable should we retrieve
442 If the prep attribute has the value 'true' the contents of the variable are prepared for displaying. Normally it is the responsibility of the developer to supply reasonable values to a template and preparing them if necessary. This attribute gives the theme designer an option to use this tag to explicitly prepare values for displaying. The attribute is optional and defaults to false.
444 String specifying the name of the variable to retrieve within the given scope
446 String specifying the modulename to get the variable from; this is only applicable when scope is module. Otherwise the value is ignored. the given scope
447
<xar:var name="preformat.catandtitle" />
Retrieves the local variable $preformat['catandtitle']
448 Parent tag: none.
449 Child tags: none
450 Contains template data evaluated while the expression specified in the 'condition' attribute is true.
451 Only block form is allowed
452
454 An identifier for the tag
456 PHP expression evaluating to true or false. During the while loop this expression is evaluated each time at the start of the loop and while the value is true, the child tags are added to the output repeatedly. For comparison operators see the Note on logic tags
457
<xar:while condition="list($uid, $uname) = each($user_result)">
// stuff executing as long a the expression is true
</xar:while>
458 Parent tag: none.
459 Child tags:
460 <xar:break> (optional)
461 <xar:continue> (optional).
462 Logical Tags:
468 Value Returning Tags (isAssignable()):
479 Child only tags:
485 Variable Value Setting (needParameter()):
487 To specify dynamic content, under normal circumstances (i.e. in so-called text nodes) tags like the <xar:var /> tag can be used. However, you cannot use this syntax inside attribute values as that would lead to invalid XML. For this, blocklayout offers 2 mechanisms:
490 The second part is often a source for confusion. Entities are not very well understood in general, and the fact that Xaraya's source templates (*.xd and *.xt) in theory have no knowledge on the final output format, makes it even harder.
491 Blocklayout supports the following entities:
493 Retrieve the value of the base url of the site.
495 Retrieve the value of the current url on the site.
497 Retrieve the value of the local variable $varname. This is effectively the same as : <xar:var name="varname"/>
499 Retrieve the value of the config variable $varname. This is effectively the same as: <xar:var scope="config" name="varname"/>
501 Retrieve the value of the session variable $varname. This is effectively the same as: <xar:var scope="session" name="varname"/>
503 Retrieve the value of the module variable $name from the module 'modname'. This is effectively the same as: <xar:var scope="module" module="modname" name="name"/>
505 Retrieve the value of a module URL. (typically something like: http://site.com/index.php?module=modname&type=type&func=func )
506 Dynamic Data Properties can also provide templated output. It is a simple process to make the required changes to the data property itself, and supply appropriately named templates.
507 The showInput() and showOutput() functions of each dynamic property return data to a corresponding template in the respective modules/[modulename]/xartemplate/properties directory. Previously the showInput() and showOutput() functions of each dynamic property returned data to a corresponding template in the modules/dynamicdata/xartemplate directory. These are slowly being moved to the new location in the properties' respective modules.
508 The directory structure and changes required for dynamic data property templates are illustrated below. The propertyname used for the specific template name is taken from the corresponding property array in the getBasePropertyInfo() function in the dynamic property itself at modules/[modulename]/xarproperties/Dynamic_[propertydescription]_property.php.
html/
|-- modules/
| |-- <module name>/
| |-- xarproperties/
| | Dynamic_<propertydescription>_property.php
| |-- xartemplates/
| |-- properties/
| <showinput|showoutput>[-<propertyname>].xd
|-- themes/
|-- <theme name>/
|-- modules/
|-- <module name>/
|-- properties/
<showinput|showoutput>[-<propertyname>].xt
509 The dynamic data properties are in the process of being moved from an old structure illustrated below, to the new directory structure illustrated above. The following diagram is left for the purpose of reference where dynamic data properties are still to be moved to the new structure. It should be used only in those specific cases until those properties are relocated to their respective module under the new structure. Note in particular the [admin|user] part of the template names are only used in the older structure illustrated below.
html/
|-- modules/
| |-- dynamicdata/
| |-- xartemplates/
| <admin-showinput|user-showoutput>[-<propertyname>].xd
|
|-- includes/
| |-- properties/
| Dynamic_<propertydescription>_property.php
|
|-- themes/
|-- <theme name>/
|-- modules/
|-- dynamicdata/
<admin-showinput|user-showoutput>[-<propertyname>].xt
510 Details of specific tags used to retrieve and display dynamic property data within module templates is documented in RFC0007 Modularized Data. Further details on retrieval and display of dynamic property data can be found in the overview and templates (as comments) of the Dyn_Example module.
511 Blocklayout output is not restricted to HTML. Potential output formats include HTML, RSS, and RDF.
512 Each module may expand the list of available tags as necessary. For example, the Reviews module may define <xar:reviews-review />. Modules must register their tags with the system in order for the compiler to recognize them. Tag registration is best handled by a module's init() function. Removing tags from the system (unregistration) is best performed in the module's remove() function.
xarTplRegisterTag('module_name', 'tag_name', tag_object, 'handler_func_name');
xarTplUnregisterTag('tag_name');
513 Non-core tags must adhere to some simple naming conventions. This is to prevent conflicts between modules that implement different tags with the same name. A non-core tag must be prefixed by a module identifier (the name of the module, or another string assigned during the module certification process), a hyphen, and a string which loosely described the tags purpose. Tag names must begin with a letter.
514 Example:
xarTplRegisterTag('reviews', 'reviews-review', ...);
515 This would register the tag:
<xar:reviews-review/>
516 Remember, "xar" is the namespace, and is not part of the tag name, even though blocklayout requires the namespace identifier to be present in every tag.
517 Widgets: This feature will abstract common User Interface components into templatable tags. The goal of such a feature is to give common components a consistent look and feel and cut down on code duplication while also making these features easy to use.
518 Because widgets are meant for common usage, it is good practice for their output to take on a consistent appearance. This makes for an easier and more pleasant user experience, and assures some level of consistency within a theme.
519 Widgets will have certain constraints on their design, such as:
525 Dynamic Style Sheets: This feature would use server-side browser sniffing to identify what CSS classes & attributes a given module can render (reasonably) correctly. Based on the result, either a <style> or <link> tag to the css would be output. The tag would reference a php script (css.php) which would actually generate the style sheet from database records.
526 Theme Management: Blocklayout will necessitate the creation of administration tools to manage themes. These would include a template manager, theme variable manager, and possibly a theme installer/uninstaller (similar to what modules have).
527 Multi-module layouts: This feature would allow Xaraya to display output from more than one module during a page request. Major core changes are required; hooks may provide some insight into how to implement this feature. At the moment, simple multi-module layouts are possible via the xar:module tag.
528 The help system will add a new widget:
<xar:help /> (scheduled beyond 1.0)
The DDF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the DDF's procedures with respect to rights in standards-track and standards-related documentation can be found in RFC-0.
The DDF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the DDF Board of Directors.
Funding for the RFC Editor function is provided by the DDF