Manual

Full source code online documentation HERE.

1. Installation

Download the figdice sources.
Unzip to a folder accessible to your PHP application.

When unzipping, you should keep the containing folder 'figdice-'.

1-1. Getting started

  1. Add the full path to 'figdice-' to your include path (using either set_include_path, or the include_path directive in php.ini).
  2. In your PHP script, include the \figdice\View class:
    require_once('figdice/\figdice\View.php');
  3. Create a View object:
    $view = new \figdice\View();
  4. Load a template file:
    $view->loadFile('my_figs/hello-world.html');
  5. Display the result:
    echo( $view->render() );

If your template contains calls to fig:feeds you must instanciate one ore more Feed Factory beforehand.
You should also set up the Logging Delegate, and temp folder for Internationalization cache, if you use them.

More resources can be found in the Tutorials section.

2. The FigDice XML markup

A FigDice template is primarily an XML file, which contains a piece of HTML or an entire HTML document, with some restrictions such as the need to comply to well-formed XHTML.
FigDice defines a namespace called fig: by default, which can be renamed by declaring it in the root node of the XML document:

xmlns:fig="http://www.figdice.org/"

The tags and attributes of FigDice make it possible to control the behavior of the template rendering engine to generate the resulting output according to your logics and data.

Tags and attributes

In the following:

  • static means that the value is passed as is.
  • evaluated means that the value is a FigDice expression which is evaluated before being passed.
  • ad hoc means that the value is static, but can also contain evaluated sub-expressions, in {curly braces} (see The ad hoc evaluation).

NB : In FigDice, the plain HTML attributes are always ad hoc.

  • fig:attr tag

    This tag positions as the child of any HTML tag. Its role is to declare an additional attribute to the parent tag, possibly conditionally (see fig:cond and fig:case), and whose value will be dynamic.

    An HTML tag can contain several fig:attr children, but they all must declare unique attribute names, or be mutually exclusive through FigDice conditions.

    An attribute that was defined inline in the parent tag cannot be redefined using a fig:attr child.

    Attributes :
    name required static
    The name of the attribute that the run-time must add to the parent tag.
    value optional evaluated
    A FigDice expression which provides the resulting value for the attribute in the parent tag.
    If omitted, the output of contents of the fig:attr tag is used.
    Example :
    FigDice template: 
    
  <fig:attr name="class" value="'Line_' + color" />
  Hello
    Output:
    (assuming that the variable color contains 'red' in the current context) 
    class="Line_red" >
  Hello
  • fig:auto attribute

    Whenever you need to have complex attributes on a tag, or conditional attributes, you must use a fig:attr children.
    But, despite they do not produce output, they are considered as children of your parent tag, thus becoming a container. Therefore, it will be rendered with an opening and closing tags.

    Yet, some XHTML elements must always be empty, self-contained nodes, immediately closed with / in the end of the tag: for example
    , ,

    .

    To tell FigDice the tag is self-closing, despite children tags in the template, use the attribute fig:auto.

    See also: fig:void.

    Value:
    Evaluated to true: indicates that the tag is self-closing.
    Note: The tag will be rendered self-closing only if its contents after rendering, is effectively empty, regardless of the value of fig:auto.
    Example :
    FigDice template: 
    fig:auto="true">
  <fig:attr name="class" value="'Line_' + color" />
    Result:
    (assuming that color contains 'red' in the current context) 
     />
  • fig:call attribute
  • fig:case attribute

    This attributes operates in a similar way to fig:cond, but additionally it enables to build a group of mutually exclusive conditions among sibling tags, much like the switch / case construct of the C language.

    A group of mutually exclusive conditions is automatically made up, as soon as several sibling tags (i.e. immediate children of the same parent) bear the fig:case attribute. The remaining siblings, which do not bear this attribute, are not part of the group.

    The engine renders only the first tag whose condition is satisfied, within the group. All other members of the group are discarded.
    All other siblings which are not part of the group (i.e. without the fig:case attribute) are rendered regularly.

    The default construct of the C language can be achieved by adding to the group a final tag with condition fig:case="true". Then, if no previous condition was satisfied, this last member will be.

    It is possible to nest several groups, at different levels of depth in the XML tree. Each group operates independently, within the node space of its parent tag.

    Note that each condition can test anything. Unlinke the switch/case construct, where one single expression is tested against several values, here each fig:case attribute can use a different condition. The only rule is that, as soon as one is satisfied, in the order of the DOM, then the group finishes.

    Value:
    Evaluated to true: indicates that the tag should be rendered with all its contents. The other members of the group are then short-circuited.
    If false, the engine skips the tag and all its contents, including active directives such as fig:feed or fig:include.
    Example :
    
	Only one situation below will appear:
	fig:case="price == 20"> Cheap 
	fig:case="count(items) == 0"> Empty 
	fig:case="true"> Default case 

	 And this one always shows!
  • fig:cdata tag

    This tag imports arbitrary unparsed contents from an external file.
    The specified file is integrated as is at the position of the current tag in the template. It can be of any type, text or binary. In particular, it does not have to be an XML file.

    Attributes :
    file required static
    The name of the file to load. The path must be relative to the current FigDice file.
  • fig:cond attribute

    This attribute tells the engine if the tag must be processed (rendered) or skipped.
    You use fig:cond to allow for application logic, to decide when a tag and its descendents should be treated. The value of fig:cond is an expression that must evaluate to true or false.

    It is possible to apply fig:cond to a fig:attr tag: in this case, if the condition evaluates to false, the dynamic attribute is omitted.

    When applied to a tag which also has the fig:walk attribute, then the condition is tested on each iteration, rather than on the outer loop tag. In this case, the expression of the condition must be formulated relative to the current context of the iteration element.

    Value:
    Evaluated to true: indicates that the tag should be rendered, along with all its descendents.
    If false, the engine bypasses the tag and all its contents, including any active tags such as fig:feed or fig:include.
    Example :
    FigDice template: 
    <div id="div1">
  <fig:attr fig:cond="/some/data == 2" name="class">Line_Double</fig:attr>
  <span fig:cond="/some/data == 3">Hello</span>
</div>

    Output:
    (assuming /some/data is 2) 
    <div id="div1" class="Line_Double">
</div>
    		Output:
    (assuming /some/data is 3) 
    <div id="div1" >
  <span>Hello</span>
</div>
  • fig:dictionary tag

    Imports a Language File in the current template.
    See 5. Internationalization.

    Attributes :
    file required static
    The name of the language file, relative to the Translation Path and Language folders specified to the View through its methods setTranslationPath and setLanguage.
    name required static
    The alias you assign to the language file within the template, for future reference in fig:trans tags.
    source optional static
    This attribute specifies the language code for which you wish to avoid the loading of the dictionary file.
    If the View's language is set to this language code, the dictionary won't load and all the fig:trans tags in your template, which use this dictionary (by its alias) will skip the look-up phase, and render their inner content directly.
  • fig:feed tag

    It is with this tag that the template invokes a Data Provider (Feed).
    The system instanciates the Feed object given its class name, specified in attribute class.
    For more information on loading and instanciation of the provider, see classes: \figdice\Feed and \figdice\FeedFactory.

    The result of the call to the provider object is added to the Universe of data, as a root branch with name specified in attribute spécifié dans l'attribut target.

    All other attributes of tag fig:feed are passed as parameters to the Feed object.

    Attributes :
    class required static
    The name of the class to invoke. FigDice queries the chain of registered \figdice\FeedFactory objects, for handler of this particular class.
    target optional static
    The root name by which the loaded data become accesible to the template. The data remain available in the rest of the template execution, immédiately after the fig:feed tag.
    If the root name already exists in the Universe, its contents is replaced.
    If the target attribute is omitted, the result of the feed is not captured, but the instance is still executed.
    (any other attribute) optional evaluated
    All other attributes are evaluated and then passed as parameters to the \figdice\Feed object. See the corresponding section for more details on how to retrieve the parameters.
    Attention: these additional attributes are evaluated, which means that they are expressions. Therefore, although you can pass numeric literals directly, you should be advised that if you wish to pass string literals they should be wrapped up in single-quotes.
    Example :
    
	
	<fig:feed class="UserFeed" target="user" userID="12" />

	Your email is: fig:text="/user/email" />
  • fig:filter attribute
  • fig:include tag

    Includes another template file.
    The included file must be a valid FigDice template, which can itself include other files.

    This is an auto-closed tag. It cannot have inner contents.

    The inclusion is realized at execution-time. The included file is parsed and rendered as the fig:include tag is encountered, as if the file contents were pasted inline in place of the tag.
    Consequently, the Context (Universe, Iterations, Macros etc.) is continued in the included file.

    In the current version, there is no run-time check to avoid infinite inclusion loops.

    Attributes :
    file required static
    The file to include. It must be a relative path from the caller template.
    Example :
    
	<fig:include file="../header-menu.html.xml" />
	<fig:include file="reporting/macros.html.xml" />
  • fig:macro attribute

    A macro is very similar to a subroutine in any programming language: it is a block identified by a name, which you invoke with parameters, in order to produce output.

    Quite naturally, a FigDice macro is a piece of XML tree.

    It is defined by its name: 

    	
    fig:macro="MyMacro"> ...

    In this statement, the FigDice engine defines the macro called MyMacro. It does not render this div tree in place: rather, the definition itself produces no output, but the macro can be called from any place in the view, by invoking:

    	
    fig:call="MyMacro" />

    The effect of this call, is that FigDice then behaves as if you had pasted inline the piece of tree defined by the macro.

    Unlike the plug/slot mechanism, the macro call must be already defined by the time of the call instruction -- potentially in an included file.

    Unlike the plug/slot mechanism, where the plug is rendered using the global data universe available at the end of rendering, a macro call is executed with the current data context.
    In particular, a relative path in a FigDice expression inside a macro, refers to the local context of data of the fig:call instruction.
    This makes it possible to call a macro from within a fig:walk, for example.

    Besides, a macro accepts calling arguments: every non-fig attributes specified at the fig:call tag level, are passed as arguments to the macro. They are added to the local context, and can be used in the macro as relative names in FigDice expressions.

    Example:
    	
    fig:call="MyMacro" myparam=" /myVariable " />

    will invoke the rendering of the macro MyMacro, by pushing on the stack of available data the relative symbol "myparam".

    You can pass any number of named arguments. Keep in mind that their values are FigDice evaluated expressions. In particular, arguments can even be complex data structures or objects, as received from a Feed.

    Additionally, you can pass more complex variables to a macro call, by using the special child tag: fig:param.

  • fig:mount tag

    Makes an alias to a location in the Universe, or assigns an arbitrary computed value to a variable.
    The alias is added to the root of the Universe.

    Attributes :
    target required static
    The name of the alias. If it already exists, it is replaced.
    value optional evaluated
    The expression to calculate and to place in the alias.
    If this attribute is omitted, the contents of the tag is calculated, then the result is assigned as text value to the variable.
    Example :
    
<fig:mount target="shortcut" 
	value="/long/path/2/symbol" />

<fig:mount target="i" value="/i + 1" />

<fig:mount target="myString">
	any piece of template here, 
	including HTML and FigDice tags fig:text=" /shortcut " />
fig:mount>
  • fig:mute attribute

    This attribute lets you specify whether the envelope of the bearing tag must be rendered or ignored.
    The inner contents of the tag are always rendered: only the rendering of the tag itself, with all its attributes, is controlled by fig:mute. The value of fig:mute is an expression evaluating to true or false.

    Value:
    Evaluated to true: the engine will only produce the inner contents of the tag, omitting the tag itself and its attributes. If false, the outer tag is output, with all its attributes.
    Example :
    FigDice Template: 
    fig:mute="true" id="div1" >
  Hello

    


    fig:mute="2 * 0" id="div2" > World
    Result :
      Hello


     World
  • fig:param tag

    In addition to passing plain named attribute-like arguments to a macro when invoking fig:call, you can pass more complex variables to a fig:macro, by using the special child tag: fig:param of parent fig:call, as in: 

    	
    fig:call="MyMacro">
	  <fig:param name="country" value=" 'FR' " />

    The same syntax is used to pass complex parameters to the fig:trans tag.

    You can pass any number of fig:param tags, with any name. You can put conditions fig:cond and fig:case on the fig:param tags in order to pass arguments conditionnally.

    Just as for fig:attr attributes, the value of a fig:param can be specified inline with the "value" attribute , or you can give inner XML FigDice content to the associated argument. The content is evaluated in place and its result is passed to the macro.
    Keep in mind that the "value" attribute of fig:param is a FigDice evaluated expression, just as that of the fig:attr tag.

    You can mix inline parameters and fig:param children.

  • fig:plug attribute

    You use fig:plug in order to inject contents into a fig:slot defined elsewhere.

    The rendered contents of the fig:plug replace the fig:slot tag of corresponding name. It is not rendered in the current location of fig:plug.

    You can provide content to a slot before defining it. It can even be defined in a sub-template which you will include later in the document.

    If you have injected some contents into a slot that cannot be found in the end of the rendering, your injected contents are discarded.

    Important note: the Plug/Slot matching is made in the end of the rendering.
    In particular, be careful of the state of the Universe when writing your plugs: the available data may not be those that were available in the initial location of the plug in your document.

    Value:
    Static: the name of the fig:slot placeholder into which to inject your contents.
    fig:append
    Evaluated: An additional attribute can be declared along with the fig:plug attribute.
    It indicates whether the previous contents must be retained or replaced, in case of multiple injections into the same placeholder.
    If true, the plugged contents are appended to whatever already injected contents in the slot.
    Note that in any case, the plug replaces the slot tag, rather than fill it up. The outer slot tag is not rendered.
    Example :
    	
    fig:plug="docTitle">
		
		fig:mute=" true  " fig:text=" /article/title " />
  • fig:slot attribute

    This attribute declares a named placeholder at the current position in the XML document.

    Anywhere in the document or its parent template or included sub-templates, you can provide replacement for the placeholder, by calling the fig:plug attribute. Then, all the rendered contents of the tag with fig:plug will be injected at the fig:slot location in the resulting document. The slog tag itself is removed from the document. That is, plugs bring replacemement for the slot tag, rather than actual content.

    The definition of the slot can occur later than the plug providing contents for it.

    Plug/Slot matching is made in the end of the rendering.

    If no plug brings contents to a slot, the slot tag itself is rendered, then acting as default content. If you do not wish to have default content, mute the tag and leave it empty.

    Value:
    Static: the name of the placeholder, for future reference by fig:plug.
    Example :
    	
		
		fig:slot</span>="<span class="CodeStatic">docTitle</span>" />
	</head>
			</pre></code>
		</div>
	</div>

</li>
			<li>
	<div class="figxml"><a name="figtext" href="#xml"><span class="FigAttr">fig:text</span></a> attribute</div>
	<p>
		This attributes provides dynamic contents to the bearing tag.
	</p>
	<p>
		Its value is an expression whose result 
		is used as the contents of the tag, in place of all its children.<br />
		All the children are removed, including active tags such as 
		<a href="#figinclude"><span class="FigTag">fig:include</span></a> or 
		<a href="#figfeed"><span class="FigTag">fig:feed</span></a>.
	</p>
	<div class="FigTagAttributes">Value:</div>
	<div class="FigTagAttributeDesc">
		Expression evaluated and output as the contents of the tag.
		The outer envelope itself, is preserved.
	</div>

	<div class="FigExample"><div class="ExampleSection">Example :</div>
		Template:
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
<div>
	<span class="myclass" <span class="FigAttr">fig:text</span>="<span class="CodeEval">/user/email</span>">
		Placeholder text <i>here</i>, 
		will be removed and replaced by the fig:text value.
	</span>
</div>
			</pre></code>
		</div>

		Output:
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
<div>
	<span class="myclass" >
		user@domain.com
	</span>
</div>
			</pre></code>
		</div>

	</div>

</li>
			<li>
	<div class="figxml"><a name="figtrans" href="#xml"><span class="FigTag">fig:trans</span></a> tag</div>

	<p>
		This tag inserts a translatable string, given the specified key and dictionary.
	</p>
	<p>
		You can pass parameters by either extented attributes, or <a href="#figparam" class="FigTag">fig:param</a> children.
	</p>
	<p>
		You can specify an optional <i>source</i> language attribute, which will save the engine from attempting to translate if you specified
		inner content to <span class="FigTag">fig:trans</span> in this language (but will still perform the parameter substitution).
	</p>

	<div class="FigTagAttributes">Attributes :</div>
	<div><span class="FigTagAttributeName">source</span> <i>optional static</i></div>
	<div class="FigTagAttributeDesc">
		The language of the inline content.
	</div>
	<div><span class="FigTagAttributeName">dict</span> <i>required static</i></div>
	<div class="FigTagAttributeDesc">
		The alias of the dictionary, loaded by <a href="#figdictionary" class="FigTag">fig:dictionary</a> in which to look for the key.
	</div>
	<div><span class="FigTagAttributeName">key</span> <i>required static</i></div>
	<div class="FigTagAttributeDesc">
		The key for which to search internationalized version in the <a href="#views" class="renvoi">View</a>'s target language.
	</div>

</li>
			<li>
	<div class="figxml"><a name="figwalk" href="#xml"><span class="FigAttr">fig:walk</span></a> attribute</div>

	<p>
		This attribute iterates on a collection (indexed or associative array).
	</p>
	<p>
		The carrier tag, and all its descendents, is repeated at run-time as many times
		as there are elements in the array.<br />
		Each <a href="#iterations" class="renvoi">iteration</a> runs in the context of the current element, whose properties (keys) 
		thus become directly accessible by their relative name.
	</p>
	<p>
		A number of <a href="#functions" class="renvoi">built-in functions</a> allow you to locate within an iteration:
		odd(), even(), first(), last(), position(), key().
	</p>
	<p>
		The data context is restored at the end of iteration.<br />
		During an iteration, the current element itself (scalar or collection)
		is accessible by using the special <a href="#paths" class="renvoi">path</a>: "." (dot).
	</p>
	<p>
		You can nest as many <span class="FigAttr">fig:walk</span> as necessary: each time,
		the context will switch to the current element of the running walk.
		You can use the "../" notation in your <a href="#paths" class="renvoi">Path</a> in order to 
		refer to the context of the parent loop.
	</p>
	<p>
		If the tag also has a condition <a href="#figcond" class="FigAttr">fig:cond</a>, 
		the <span class="FigAttr">fig:walk</span> prevails on it. The condition is evaluated inside the loop,
		at each iteration, in the context of the current iteration item.
		To achieve a global condition on a tag which also have a Walk loop, you must enclose it in a parent tag 
		and place the condition on it.
		If you do not wish to show this wrapping tag, mute it with <a href="#figmute" class="FigAttr">fig:mute</a>.
	</p>
	<p>
		<a href="#adhoc" class="renvoi">Ad-hoc evaluations</a> are also computed on each iteration.
	</p>

	<div class="FigTagAttributes">Value:</div>
	<div class="FigTagAttributeDesc">
		Evaluated : Path expressing the array on which to iterate.
	</div>


	<div class="FigExample"><div class="ExampleSection">Example :</div>
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>

<span class="xmlComment"><!-- Load a collection of products 
	Each item has two properties: number, and price. --></span>
<<a href="#figfeed" class="FigTag">fig:feed</a> <span class="FigAttr">class</span>="<span class="CodeStatic">ProductsFeed</span>" <span class="FigAttr">target</span>="<span class="CodeStatic">products</span>" category=" <span class="CodeEval">'Garden'</span> " />

<table>
	<thead>
		<tr>
			<th>Product number</th>
			<th>Price with tax</th>
		</tr>
	</thead>
	<tbody>
		<span class="xmlComment"><!-- Iterate on each item in the products array 
			and repeat the <tr> tag and its descendents: --></span>
		<tr <span class="FigAttr">fig:walk</span>="<span class="CodeEval">/products</span>">
			<span class="xmlComment"><!-- Local properties of the current item are accessed 
				with relative paths (number, price). --></span>
			<td <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">number</span>"></td>
			<span class="xmlComment"><!-- Properties outside the current item are accessed 
				with absolute paths (/constants). --></span>
			<td <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">price * /constants/taxRate</span>"></td>
		</tr>
	</tbody>
</table>

			</pre></code>
		</div>
	</div>

</li>

		</ul>



		<div><img src="/img/slash.png" width="600" /></div>

		<h2><a name="expressions">3. The expressions</a></h2>

			<p>
				Expressions are what you place in FigDice evaluated <a href="#xml" class="renvoi">attributes</a> 
				and in curly braces { } in <a href="#adhoc" class="renvoi">ad-hoc</a> blocks.<br />
				They are evaluated by the system during the template run-time.
				An expression leads to one single resulting value, which can be of any data type.
			</p>
			<p>
				FigDice implements a powerful expression engine based on the principle that the author
				of a template must not be concerned with the nature of the data,
				nor be bothered with any programming languages syntax.
			</p>
			<p>
				This principle results in a very simple yet robust syntax, which provides a way to 
				use homogeneous data available in the Universe, perform operations with them, 
				control the iterations of loops, etc.
			</p>
			<p>
				An Expression is made of arithmetical, logical and string operations on
				data elements (<a href="#paths" class="renvoi">Paths</a>) present in the <a href="#universe" class="renvoi">Universe</a>,
				and on literal strings, numerical and boolean values, as well as <a href="#functions" class="renvoi">Function calls</a>.
				
			</p>

				<h3><a name="universe">3-1. Universe</a></h3>
				<div>
	<p>
		The Universe is the entire set of data made available to a FigDice template.
	</p>
	<p>
		It is organised in a tree of key-value pairs, where each value can be a dictionary collection on its own.
		FigDice <a href="#expressions" class="renvoi">expressions</a> use the <a href="#paths" class="renvoi">Path</a> notation
		to refer to structured data present at any level in the Universe.
	</p>
	<p>
		The Universe is constructed by:
		<ul>
			<li style="margin-bottom: 1em;">
				Using the <a class="FigTag" href="#figfeed">fig:feed</a> tag inside the template, 
				to bring data from the outside world,
			</li>
			<li style="margin-bottom: 1em;">
				Using the <a class="FigTag" href="#figmount">fig:mount</a> tag inside the template,
				to rearrange data that are already contained in the Universe,
			</li>
			<li style="margin-bottom: 1em;">
				Calling the <a href="#views" class="CodeDocMethod">mount</a> method of the <a href="#views" class="CodeDocMethod">\figdice\View</a> class
				from the outside world to push data into the template.
			</li>
		</ul>
		These three ways lead to the creation of top-level keys in the Universe.
	</p>
	<p>
		The Universe is shared with all the included sub-templates during the rendering cycle.<br />
		An addition to the Universe, by the above "inside" methods, at any inclusion level, becomes
		also available to the parent templates and all subsequently included files.<br />
	</p>
</div>


				<h3><a name="paths">3-2. The Path</a></h3>
				<div>
	<p>
		The Universe contains data that the template can use.<br />
		These data are structured in a descending tree of key-value pairs, like a 
		multi-level-depth PHP associative array, very similar to the entries in a filesystem tree.
	</p>
	<p>
		Therefore the Template's expressions interrogate the Universe's data by using a
		filesystem-like, slash-separated notation:
	</p>
	<code style="padding: 20px;">
		/path/to/some/data
	</code>
	<p>
		The keys are case-sensitive.
	</p>
	<p>
		Integer numbers are valid keys, especially when accessing the elements of
		an indexed array:
	</p>
	<code style="padding: 20px;">
		/books/3/title
	</code>
	<p>
		In order to access top-level keys (see <a href="#universe" class="renvoi">Universe</a> ),
		the Path starts with a leading Slash "<b style="background-color: yellow;">/</b>".<br />
		For sub-keys of the current context, in an iteration or in a <a class="FigAttr" href="#figcall">macro call</a>,
		the Path directly starts with the sub-key name.
	</p>
	<code style="padding: 20px;">
		author/firstName
	</code>
	<p>
		If a requested key does not exist, the result is empty.<br />
		There is no error in descending an non-existing path: querying sub-keys
		of a non-existing path returns empty sucessfully.
	</p>
	<p>
		There are two special keys, used to access the current item in an iteration, and the
		parent loops' items in nested <a href="#figwalk" class="FigAttr">fig:walk</a> loops:
		the simple-dot "<b style="background-color: yellow;">.</b>", and the double-dot "<b style="background-color: yellow;">..</b>".
	</p>
	<p>
		The simple-dot, is generally used to express the current iteration when it contains an immediate value ;
		that is, inside a <a href="#figwalk" class="FigAttr">fig:walk</a> where each value is not
		a dictionary on its own, but rather a scalar value which you wish to use in <a href="#figtext" class="FigAttr">fig:text</a> for example.
	</p>
	<code style="padding: 20px;"><pre>
	<span class="xmlComment"><!-- array('red', 'green', 'yellow') --></span>
	<tr <a href="#figwalk" class="FigAttr">fig:walk</a>="<span class="CodeEval">/colors</span>">
	  <td <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">.</span>"></td>
	  <span class="xmlComment"><!-- <td>red</td>
	       <td>green</td>
	       <td>yellow</td> --></span>
	</tr>
	</pre></code>
	<p>
		The double-dot lets you go up one loop's level, and then access the sub-keys of the parent item from here.
	</p>
	<code style="padding: 20px;"><pre>
 <span class="xmlComment"><!-- Outer loop on books --></span>
 <tr <a href="#figwalk" class="FigAttr">fig:walk</a>="<span class="CodeEval">/books</span>">
   <td <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">author/name</span>"></td>
   <td>
     <ul>
       <span class="xmlComment"><!-- inner loop on book's chapters --></span>
       <li <a href="#figwalk" class="FigAttr">fig:walk</a>="<span class="CodeEval">chapters</span>">
         <span class="xmlComment"><!-- Each iteration of the inner loop displays
         a field from the running item (chapter name),
         and a field from the outer loop's current 
         item (book's title). --></span>
         Chapter <span <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">name</span>"/>
         Book <span <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval">../title</span>"/>, 
       </li>
     </ul>
   </td>
 </tr>
	</pre></code>

	<p style="padding-top: 20px;"><b>Path and Objects</b></p>
	<p>
		A <a href="#feeds" class="renvoi">Feed</a> class can also return objects, in addition to
		plain associative arrays. On objects, the Path interprets key names as public getter methods of the object,
		according to the following naming pattern:<br />
		<br />
		For key: <code>keyName</code><br />
		getter method must be:<br />
		<code style="padding-left: 2em;">public function getKeyName()</code> or <br />
		<code style="padding-left: 2em;">public function isKeyName()</code>
	</p>
	<p>
		The Object oriented way has higher priority over the associative array way.
		When both a getter method and a public property exist for the interrogated key,
		the getter method is used. If both <code>get...()</code> and <code>is...()</code>
		are defined on the object, the <code>get</code> method is used by the Path expression.
	</p>
	<p>
		Attention: the Path access only public members on objects. If the object has
		a non public member corresponding to the key name, the Path will return null.
	</p>

	<p style="padding-top: 20px;"><b>Aggregate arrays</b></p>
	<p>
		There is a special case when working with zero-based indexed arrays: when you access the name of an item's key
		directly below the array name, instead of accessing the key relatively in an iteration, or through the item's index number,
		you actually construct an ordered set of all the values contained in that same sub-key of all the items in the array.
	</p>
	<div style="border: dotted 1px black; padding-left: 20px; padding-right: 20px;">
		<p>Example:</p>
		<p>
			In the following JSON-noted indexed array, every item is an object presenting a common member «<span style="color: magenta;">commonProperty</span>».<br />
	<code><pre>
/data = [
	{ <span style="color: magenta;">commonProperty</span>: 3 },
	{ <span style="color: magenta;">commonProperty</span>: 5 },
	{ <span style="color: magenta;">commonProperty</span>: 4 }
]</pre></code>
		</p>
		<p>Then the result of <code> sum( /data/commonProperty )</code> is 12.</p>
	</div>
	<p>
		<br />
		This special usage of the Path makes it possible to work with <a href="#functions-agg" class="renvoi">Aggregate functions</a>, either built-in
		or user-defined.
	</p>
</div>

				<h3><a name="keywords">3-3. Keywords and operators</a></h3>

				<p>
					Below is the list of the keywords and operators supported by the FigDice Expression system.
					Just as in mathematical terms, you can use parentheses <b>( )</b> to group sub-expressions or to control operation priority.

					<table border="0" width="500" align="center" style="font-size: 12px; padding-top: 20px;">
						<tbody>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">+</td>
								<td style="font-size: 12px;">(plus sign) Numerical addition, String concatenation, Unary positive sign.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">-</td>
								<td style="font-size: 12px;">(minus sign) Numerical substraction, Unary negative sign.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">*</td>
								<td style="font-size: 12px;">(star sign) Numerical multiplication.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">div</td>
								<td style="font-size: 12px;">Numerical division (the Slash symbol has a different meaning in FigDice: see <a href="#paths" class="renvoi">Path</a>). Does not raise a Division by Zero error: rather, returns false.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">true</td>
								<td style="font-size: 12px;">The constant True.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">false</td>
								<td style="font-size: 12px;">The constant False.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">==</td>
								<td style="font-size: 12px;">Test of Equality.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">!=</td>
								<td style="font-size: 12px;">Test of Non-equality.</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">lt</td>
								<td style="font-size: 12px;">Less Than (equivalent to < in many programming langages, but the < symbol is not valid in XML attributes.)</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">lte</td>
								<td style="font-size: 12px;">Less Than or Equal (equivalent to <= in many programming langages, but the < symbol is not valid in XML attributes.)</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">gt</td>
								<td style="font-size: 12px;">Greater Than (equivalent to >= in many programming langages, but the > symbol is not valid in XML attributes.)</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">gte</td>
								<td style="font-size: 12px;">Greater Than or Equal (equivalent to >= in many programming langages, but the > symbol is not valid in XML attributes.)</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">and</td>
								<td style="font-size: 12px;">Logical And operator</td>
							</tr>
							<tr>
								<td style="font-weight: bold; text-align: center; vertical-align: top;">or</td>
								<td style="font-size: 12px;">Logical Or operator</td>
							</tr>
						</tbody>
					</table>

				</p>
				<br />


				<h3><a name="iterations">3-4. Iterations, context</a></h3>
				<p>
	
</p>

				<h3><a name="adhoc">3-5. The ad-hoc evaluation</a></h3>
				<p>
					The value of <b><i>static</i></b> attributes is used as is, without modification.
				</p>
				<p>
					The <b><i>evaluated</i></b> attributes are handled by the FigDice
					<a href="#expressions" class="renvoi">Expressions engine</a>,
					and it is the result of the evaluation that is used as the attribute value.
				</p>
				<p>
					The third form of attributes is called <b><i>ad hoc</i></b>:
					it is normally static attributes, but which may contain evaluated parts, which you place between braces <b style="background-color: lime;">{ }</b>.
					The engine evaluates each expression in braces, in order of appearance, and replace the term in the static string with the result of the evaluation,
					to build up the final attribute value.
				</p>
				<div class="FigExample">
					<code><pre>
	<option id="opt_<b style="background-color: lime;">{</b><span class="CodeEval"> position() </span><b style="background-color: lime;">}</b>_country"
		value="<b style="background-color: lime;">{</b><span class="CodeEval">countryCode</span><b style="background-color: lime;">}</b>" fig:text="<span class="CodeEval">countryName</span>" />
					</pre></code>
				</div>
				<p>
					Ad hoc expressions behave exactly the same as standard FigDice expressions. In particular, you can use built-in functions,
					user-defined functions, and any path and operator.
				</p>
				<p>
					The number of evaluated parts in an ad hoc attribute is not limited.
				</p>
				<p>
					The attributes of <span class="FigTag">fig:</span> tags are either static, or evaluated.<br />
					The direct parameters in <a href="#figmacro" class="FigAttr">macro</a> calls, ie the 
					additional attributes of HTML tags that carry the <a href="#figcall" class="FigAttr">fig:call</a> 
					attribute, are evaluated.
					All other attributes of the document (in particular the usual attributes of 
					legitimate HTML tags) are ad hoc.
				</p>
				<br />

				<h3><a name="dynapath">3-6. Dynamic Path Components</a></h3>
				<p>
					When writing a <a href="#paths" class="renvoi">Path</a>, you specify the way to reach the value at
					a particular sub-key in the <a href="#universe" class="renvoi">Universe</a>. Each path component, separated by a
					slash « <b>/</b> » represents one more level in the depth of the data tree. 
				</p>
				<p>
					Yet sometimes you do not know in advance the name of one key, at template-authoring time, but this key
					itself is in fact the result of another expression.
				</p>
				<p>
					For these situations you can use a Dynamic Path Component, by wrapping up the secondary expression in
					square braces « <b>[ ]</b> » in your Path:
				</p>
				<div class="FigExample">
					<code>
		<b>/</b>path<b>/</b>to<b>/<span style="background-color: yellow;">[ </span></b><span class="CodeEval">computed<b>/</b>key</span><b><span style="background-color: yellow;"> ]</span>/</b>data
					</code>
				</div>
				<p>
					This construct is particularly useful when presenting pivot tables, where you need to nest two loops and the keys
					of the inner collection come from values in the outer collection.
				</p>
				<p>
					Dynamic Path Components can contain more dynamic parts themselves.<br />
					The number of Dynamic components within a path is not limited.
				</p>
				<br />

				<h3><a name="functions">3-7. Built-in Functions</a></h3>
				<div>
	<p>
		In the FigDice Expression language you can call functions, using a syntax similar
		to that of the C language.
	</p>
	<p>
		All the arguments are <a href="#expressions" class="renvoi">Expressions</a>. Depending on the function's semantic, they can
		be of various types: strings, numeric, boolean, or even data collections or XML nodes.
	</p>
	<p>
		During a function call, all the arguments are evaluated beforehand, and then 
		passed to the function.
	</p>
	<p>
		Functions names are case-sensitive.
	</p>
	<p>
		In addition to the Built-in Functions, you can develop your own <a href="#userdefinedfunc" class="renvoi">User-defined functions</a>
		using the provided API.
	</p>

	<p><b>Functions operating on collections</b></p>

	<ul class="builtin-funcs">
		<li>
			<div class="figxml builtin-func">count</div>
			<p>
				Syntax: <b>count</b> ( <i><indexed array></i> )
			</p>
			<p>
				Returns the number of items in the specified collection. <br />
			</p>
		</li>
	</ul>

	<p style="padding-top: 30px;"><b>Functions operating on iterations</b></p>
	<p>
		These functions do not have any arguments. They can only be called
		within a <a href="#figwalk" class="FigAttr">fig:walk</a> loop.<br />
		They run on the current item of the iteration, and there is no way to call
		these functions on outer loops' items from within a nested loop.
	</p>
	<p>
		In nested loops, if you need to use iteration functions on outer loop's items,
		you must capture their values using <a href="#figmount" class="FigTag">fig:mount</a>. 
	</p>
	<ul class="builtin-funcs">
		<li>
			<div class="figxml builtin-func">even</div>
			<p>
				Syntax: <b>even</b> ( )
			</p>
			<p>
				Returns true when the 1-based position of the current iteration is
				an even number.<br />
				Returns false otherwise.<br />
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">first</div>
			<p>
				Syntax: <b>first</b> ( )
			</p>
			<p>
				Returns true at the first iteration of a loop.<br />
				Returns false in all other iterations.
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">key</div>
			<p>
				Syntax: <b>key</b> ( )
			</p>
			<p>
				When the loop is running on an associative array, returns the key of the
				current item.
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">last</div>
			<p>
				Syntax: <b>last</b> ( )
			</p>
			<p>
				Returns true at the last iteration of a loop.<br />
				Returns false in all other iterations.<br />
				Equivalent to: not( first() )
			</p>
		</li>
		<li>
			<div class="figxml builtin-func">odd</div>
			<p>
				Syntax: <b>odd</b> ( )
			</p>
			<p>
				Returns true when the 1-based position of the current iteration is
				an odd number.<br />
				Returns false otherwise.<br />
				Equivalent to: not( even() )
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">position</div>
			<p>
				Syntax: <b>position</b> ( )
			</p>
			<p>
				Returns the current 1-based index of the running iteration.<br />
			</p>
		</li>

	</ul>

	<p style="padding-top: 20px;"><b>Functions operating on scalar values</b></p>

	<ul class="builtin-funcs">
		<li>
			<div class="figxml builtin-func">const</div>
			<p>
				Syntax: <b>const</b> ( <i>expression</i> )
			</p>
			<p>
				Looks up the PHP const value defined by the specified name, and returns its value.
			</p>
			<p>The lookup is guarded: a undefined const will not cause failure (but returns false instead).</p>
			<p>Class consts can be looked up with the scope operator '::', as in:</p>
			<div style="font-family: Courier; font-size: 12px;">
				<b>const</b> ( <i>'MyClass::MYCONST'</i> )
			</div>
			<p>The mechanism of evaluation of the litteral outcome of the expression, as the name of a constant, is highly language-dependent.</p>
		</li>

		<li>
			<div class="figxml builtin-func">default</div>
			<p>
				Syntax: <b>default</b> ( <i>tentativeExpression, defaultValue</i> )
			</p>
			<p>
				Use the specified tentativeExpression, unless it evaluates to false, in which case
				use the defaultValue instead.<br />
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">format_number</div>
			<p>
				Syntax:
				<div style="font-family: Courier; font-size: 12px;">
					<b>format_number</b> ( <i>number</i> [, <i>decimals</i> [, <i>decPoint</i> [, <i>thousandSep</i> ]]] )
				</div>
			</p>
			<p>
				Returns a numeric value formatted with the specified number of decimal digits, symbol for decimal point, and
				symbol for thousands separator.<br />
				The first argument is mandatory, the others are optional.
			</p>
			<p>
				<i>decimals</i> defaults to 2.<br />
				<i>decPoint</i> defaults to comma ','.<br />
				<i>thousandSep</i> defaults to space ' '.
			</p>
		</li>

		<li><div class="figxml builtin-func">format_timestamp</div></li>

		<li>
			<div class="figxml builtin-func">GET</div>
			<p>
				Syntax: <b>GET</b> ( <i>string</i> )
			</p>
			<p>
				Returns the value of the specified URL parameter from the HTTP GET request.<br />
				Returns empty if the parameter does not exist.
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">if</div>
			<p>
				Syntax: <b>if</b> ( <i>condition, thenExpression, elseExpression</i> )
			</p>
			<p>
				This function acts as the ternary operator.<br />
				If <i>condition</i> is true, returns <i>thenExpression</i>.<br />
				If false, returns <i>elseExpression</i>.
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">not</div>
			<p>
				Syntax: <b>not</b> ( <i>expression</i> )
			</p>
			<p>
				This function is the logical Not operation.<br />
				It evaluates the logical <i>expression</i> and returns it negation.
			</p>
		</li>

		<li><div class="figxml builtin-func">php</div></li>
		<li><div class="figxml builtin-func">substr</div></li>
		<li><div class="figxml builtin-func">xml</div></li>
		<li><div class="figxml builtin-func">xpath</div></li>
	</ul>


	<p style="padding-top: 20px;"><b><a name="functions-agg">Functions performing aggregations</a></b></p>

	<p>
		Aggregate functions are a particular type of functions. Their argument is
		neither a collection, nor a field: it is a special notation which makes it
		possible for FigDice to aggregate the values of the same sub-key in all the items
		of an indexed array.
	</p>
	<p>
		Example:<br />
		<code><pre>
    <<a href="#figfeed" class="FigTag">fig:feed</a> class="InvoicesFeed" target="invoices" />
    <span class="xmlComment"><!-- /invoices is a 0-based indexed array
        whose every item has an "amount" key. --></span>
    <div <a href="#figtext" class="FigAttr">fig:text</a>="<span class="CodeEval"> sum ( /invoices/amount ) </span>" />
		</pre></code>
	</p>
	<p>
		In order to access a particular item's field by index, you would use:<br />
		<code><pre>    /invoices/5/amount</pre></code><br />
		(for the 6<sup>th</sup> element of the 0-based array /invoices)<br /><br />
		The special notation for aggregate functions skip the index component, and specifies directly
		the field of interest below the array name.
	</p>
	<p>The indexed array must be zero-based.</p>

	<ul class="builtin-funcs">
		<li>
			<div class="figxml builtin-func">average</div>
			<p>
				Syntax: <b>average</b> ( <i><indexed array>/<common key></i> )
			</p>
			<p>
				Returns the average value in the <common key> field of all 
				the items in <indexed array>.
			</p>
		</li>

		<li>
			<div class="figxml builtin-func">sum</div>
			<p>
				Syntax: <b>sum</b> ( <i><indexed array>/<common key></i> )
			</p>
			<p>
				Returns the sum of the values in the <common key> field of all 
				the items in <indexed array>.
			</p>
		</li>
	</ul>

</div>

		<div><img src="/img/slash.png" width="600" /></div>

		<h2><a name="classes">4. Classes and interfaces</a></h2>
				<h3>Public classes and interfaces by name</h3>
				

				<ul class="ClassList">
					<li>See : <a target="reference" href="/reference/namespace-figdice.html">reference/namespace-figdice.html</a></li>
				</ul>

				<h3><a name="views">4-1. Views</a></h3>
				<div>
	<p><b>\figdice\View</b></p>
	<p>
		The View is the entry point of the FigDice rendering engine.
	</p>
	<p>
		The first step consists in creating a \figdice\View object, then you register 
		the Factories for your <a href="#feeds" class="renvoi">Feeds</a>, <a href="#filters" class="renvoi">Filters</a> and <a href="#functions" class="renvoi">Functions</a>.
		Next, you indicate to your \figdice\View instance to load an XML template file.
		Finally, you call the rendering method which returns the output.  
	</p>
	<p>
		<div style="border: dotted 1px black;padding-left: 20px;">
			<code><pre>
$view = new <span class="CodeDocMethod">\figdice\View</span>();
$view-><span class="CodeDocMethod">registerFeedFactory</span>( $feedFactory );
$view-><span class="CodeDocMethod">loadFile</span>( $templateFilename );
echo $view-><span class="CodeDocMethod">render</span>();
			</pre></code>
		</div>
	</p>

	<p>
		The method <span class="CodeDocMethod">render</span> of class \figdice\View
		analyzes the loaded template file, and starts the rendering engine.<br />
		It handles automatically the loading of included sub-templates with <a class="FigTag" href="#figinclude">fig:include</a> tags.
	</p>

	<div class="ClassBlock">
		<p>
			<div class="ClassDef">class <span class="ClassName">\figdice\View</span></div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">loadFile</span> ( string $filename )</div>
			<div class="CodeMethodHint">returns void</div>
			<div class="CodeMethodHint">throws <a href="#exceptions" class="renvoi">\figdice\exceptions\FileNotFoundException</a></div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">mount</span> ( string $mountingName, mixed $data )</div>
			<div class="CodeMethodHint">returns void</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">registerFeedFactory</span> ( <a href="#feeds" class="renvoi">\figdice\FeedFactory</a> $factory )</div>
			<div class="CodeMethodHint">returns void</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">registerFunctionFactory</span> ( <a href="#functions" class="renvoi">\figdice\FunctionFactory</a> $factory )</div>
			<div class="CodeMethodHint">returns void</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">render</span> ( )</div>
			<div class="CodeMethodHint">returns string</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">setFilterFactory</span> ( <a href="#filters" class="renvoi">\figdice\FilterFactory</a> $factory )</div>
			<div class="CodeMethodHint">returns void</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">setLanguage</span> ( string $language )</div>
			<div class="CodeMethodHint">returns void</div>
			Specifies the target language code in which you wish to translate the <a href="#figtrans" class="FigTag">fig:trans</a> tags or your templates.<br />
			This language code must correspond to a subfolder of the Translation Path (See <a href="#dictionaries" class="renvoi">5-1. Dictionaries</a>).
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">setTempPath</span> ( string $path )</div>
			<div class="CodeMethodHint">returns void</div>
			Specifies the folder in which the engine will be able to produce temporary files, for pre-compilation purposes.<br />
			The engine will not attempt to use cache-based optimization features if you leave this property blank.
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">setTranslationPath</span> ( string $path )</div>
			<div class="CodeMethodHint">returns void</div>
			Specifies the folder in which you provide all the <a href="#dictionaries" class="renvoi">Dictionary files</a>, each in its language code's subfolder.<br />
			See <a href="#i18n" class="renvoi">5. Internationalisation</a>.
		</p>
	</div>

</div>

				<h3><a name="feeds">4-2. Data Providers</a></h3>
				<div>
	<p><b>\figdice\Feed</b></p>


	<p>
		The Feed is the data provider for the View. It makes the link
		between the data managed by the application, and the contents to serve to the client.<br />
		The Feed works in the Presentation Layer.
	</p>

	<div class="ClassBlock">
		<p>
			<div class="ClassDef">abstract class <a name="FIG_Feed" class="ClassName">\figdice\Feed</a></div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">protected function</span> <span class="CodeDocMethod">getFigFile</span> ( )</div>
			<div class="CodeMethodHint">returns string</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">protected function</span> <span class="CodeDocMethod">getParameter</span> ( string $name )</div>
			<div class="CodeMethodHint">returns mixed, null if key not found</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">protected function</span> <span class="CodeDocMethod">getParameterBool</span> ( string $name, boolean $default = false )</div>
			<div class="CodeMethodHint">returns boolean</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">protected function</span> <span class="CodeDocMethod">getParameterInt</span> ( string $name, int $default = 0 )</div>
			<div class="CodeMethodHint">returns int</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">protected function</span> <span class="CodeDocMethod">getParameterString</span> ( string $name, string $default = '' )</div>
			<div class="CodeMethodHint">returns string</div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">abstract public function</span> <span class="CodeDocMethod">run</span> ( )</div>
			<div class="CodeMethodHint">returns mixed</div>
		</p>
	</div>


	<p>
		When the view <a href="#views" class="renvoi">\figdice\View</a> encounters a
		<a href="#figfeed" class="FigTag">fig:feed</a> tag, it instanciates an object whose 
		class is specified by the <span class="FigAttr">class</span> attribute. This class must
		inherit from class \figdice\Feed.<br />
		Then the engine passes to the object its calling parameters, and executes its 
		<span class="CodeDocMethod">run</span> method.<br />
		The result of <span class="CodeDocMethod">run</span> is added to the <a href="#universe" class="renvoi">Universe</a>
		of the view, at root level, under the name specified by the <span class="FigAttr">target</span> attribute of <a href="#figfeed" class="FigTag">fig:feed</a>.
	</p>
	<p>
		A new \figdice\Feed object is instanciated at each call to <a href="#figfeed" class="FigTag">fig:feed</a>,
		even if one same class is invoked multiple times in the same View.
	</p>
	<p>
		The Feed instance receives the key/value pairs passed by the Template through the extended
		attributes of the calling <a href="#figfeed" class="FigTag">fig:feed</a> tag.
		Every attribute which is not in the <span class="FigAttr">fig:</span> namespace, and apart from
		<span class="FigAttr">class</span> and <span class="FigAttr">target</span>, bring values
		to the Feed object, which it can query with the <span class="CodeDocMethod">getParameter</span> methods family.<br />
		The String, Int and Bool versions of the method allow a safe typecast while specifying a default value
		in case of absence of the key or if the underlying value is not of the expected type.
	</p>



	<div class="FigExample"><div class="ExampleSection">Example :</div>
		template.xml
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>

<span class="xmlComment"><!-- Load a collection of products in the 
	specified category: 'Garden'. --></span>
<<a href="#figfeed" class="FigTag">fig:feed</a> <span class="FigAttr">class</span>="<span class="CodeStatic">ProductsFeed</span>" <span class="FigAttr">target</span>="<span class="CodeStatic">products</span>" category="<span class="CodeEval">'Garden'</span>" />

			</pre></code>
		</div>
	</div>

	<div class="FigExample">
		ProductsFeed.php
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
class ProductsFeed extends \figdice\Feed {
	...
	public function run() {

		$categoryName = $this->getParameterString('category');
		// Fetch products from DB for category $categoryName
			...
		return ... 
	}
	...
}
			</pre></code>
		</div>
	</div>



	<img src="../img/slash.png" width="300" style="padding-top: 20px;" />



	<p><b>\figdice\FeedFactory</b></p>
	<p>
		When it is time for the system to instanciate on demand a Feed object as per class name specified in <a href="#figfeed" class="FigTag">fig:feed</a> tag,
		the child class of \figdice\Feed is not necessarily already loaded in the Class Space of the program.
		Moreover, in general your Feed classes will have particular features which makes it necessary for them to dialog 
		with the Controller, unique owner of the View. For example this is the case when the Feed must obtain
		from the Controller the database connection string, or some session information.
	</p>


	<div class="ClassBlock">
		<p>
			<div class="ClassDef">interface <a name="FIG_FeedFactory" class="ClassName">\figdice\FeedFactory</a></div>
		</p>
		<p>
			<div class="CodeMethod"><span class="CodeDocKw">public function</span> <span class="CodeDocMethod">create</span> ( string $className, array $attributes )</div>
			<div class="CodeMethodHint">returns \figdice\Feed, null if specified \figdice\Feed subclass is not handled by this factory</div>
		</p>
	</div>

	<p>
		Therefore, the <a href="#views" class="renvoi">View</a> obtains instances of the Feed classes through the use of Factories, implementing the \figdice\FeedFactory interface.<br />
		Each \figdice\FeedFactory instance is responsible with instanciating one set of \figdice\Feed classes, by their names.
	</p>
	<p>
		Before rendering the view, the Controller registers all the \figdice\FeedFactory instances that it may have to use.
		Then, during the processing, when a <a href="#figfeed" class="FigTag">fig:feed</a> tag
		is executed, the View queries every registered \figdice\FeedFactory in turn, until it obtains an instance
		of the child class of \figdice\Feed specified by the <span class="FigAttr">class</span> attribute.
	</p>
	<p>
		You construct instances of \figdice\FeedFactory and you register these instances into the View.
		You can construct your \figdice\FeedFactory objects freely according to your needs, depending on the nature of 
		the \figdice\Feed subclasses that they handle. In particular, they should maintain all the necessary information
		to enable communication between the \figdice\Feed instanciated on demand, and the Controller or any other component
		of the application.
	</p>

</div>

				<h3><a name="xml">4-3. Filters</a></h3>
				<h3><a name="userdefinedfunc">4-4. Functions</a></h3>
				<h3><a name="xml">4-5. Logging</a></h3>

		<div><img src="/img/slash.png" width="600" /></div>

		<h2><a name="i18n">5. Internationalization</a></h2>
		<div>
	<p>
		FigDice provides a mechanism for key-based translation of all the text contained in your templates.
	</p>
	<p>
		All you have to do, is indicate where in your templates the internationalizable messages are located, by enclosing them in <a href="#figtrans" class="FigTag">fig:trans</a> tags.
	</p>
	<p>
		Language files are organized in XML dictionaries of key-value entries.
	</p>
	<p>
		A <a href="#figtrans" class="FigTag">fig:trans</a> tag indicates a dictionary name, the key of the message to translate, and optional named parameters in the shape of inline attributes of <a href="#figparam" class="FigTag">fig:param</a> children tags (same syntax as in <a href="#figcall" class="FigAttr">fig:call</a>).
	</p>

	<div class="FigExample"><div class="ExampleSection">Examples: FigDice Template</div>
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
	<span class="xmlcomment"><!-- Import two dictionaries into my current template: --></span>
	<<a href="#figdictionary" class="FigTag">fig:dictionary</a> name="<span class="CodeStatic">Product</span>" file="<span class="CodeStatic">product.xml</span>" />
	<<a href="#figdictionary" class="FigTag">fig:dictionary</a> name="<span class="CodeStatic">Errors</span>" file="<span class="CodeStatic">common/errors.xml</span>" />

	<span class="xmlcomment"><!-- Display a translated message: --></span>
	<<a href="#figtrans" class="FigTag">fig:trans</a> dict="<span class="CodeStatic">Product</span>" key="<span class="CodeStatic">PRODUCT_DESCRIPTION_COLUMN</span>" />

	<span class="xmlcomment"><!-- Display a translated message with a parameter: --></span>
	<<a href="#figtrans" class="FigTag">fig:trans</a> dict="<span class="CodeStatic">Errors</span>" key="<span class="CodeStatic">MINIMUM_CHARS_EXPECTED</span>" minChars="<span class="CodeEval"> 20 </span>" /></pre>
			</code>
		</div>
	</div>


	<p>
		In the dictionaries, the parameters of an entry are usable by their name, enclosed in curly braces:
	</p>
	<div class="FigExample"><div class="ExampleSection">Example: Dictionary</div>
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
	<entry key="MINIMUM_CHARACTERS_EXPECTED">
		Please enter at least <span style="background-color: yellow;">{minChars}</span> characters.
	</entry></pre>
			</code>
		</div>
	</div>


	<p>
		The entries of a dictionary can contain any HTML parts:
	</p>
	<div class="FigExample">
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
	<entry key="MINIMUM_CHARACTERS_EXPECTED">
		Please enter at least <span style="background-color: yellow;"><b></span>{minChars} characters<span style="background-color: yellow;"></b></span>.
	</entry></pre>
			</code>
		</div>
	</div>

	<p>
		Additionally, a <a href="#figtrans" class="FigTag">fig:trans</a> tag can contain direct contents, for two purposes:<br />
		- avoid to create an explicit dictionary file for your default language,<br />
		- provide default value for a key not found.
	</p>


	<div class="FigExample"><div class="ExampleSection">Example:</div>
		<div style="border: dotted 1px black; font-size: 11px;">
			<code><pre>
	<<a href="#figtrans" class="FigTag">fig:trans</a> dict="<span class="CodeStatic">Errors</span>" key="<span class="CodeStatic">MINIMUM_CHARS_EXPECTED</span>" source="<span class="CodeStatic">en</span>" minChars="<span class="CodeEval"> 20 </span>" >
		Please enter at least <b>{minChars}</b> characters.
	</<a href="#figtrans" class="FigTag">fig:trans</a>></pre>
			</code>
		</div>
	</div>

	<p>
		This example shows the "source" attribute, which tells the language of your direct content.<br />
		This way, if this language is the same as that of the View, the engine will not try to look up the key. Rather, it will immediately use the specified content.
	</p>


				<h3><a name="dictionaries">5-1. Dictionaries</a></h3>

	<p>
		The structure of a Dictionary XML file is:
	</p>
	<div class="ClassBlock">
		<code><pre>
	<fig:dictionary language="<b><i> your language code </i></b>" >

		<entry key="<b><i> a key </i></b>"> <b><i> a translation </i></b> </entry>
		<entry key="<b><i> a key </i></b>"> <b><i> a translation </i></b> </entry>
			...

	</fig:dictionary></pre>
		</code>
	</div>

	<p>
		All the Dictionary files are organized in the following folder structure:
	</p>
	<code><pre>
  <i>lang</i>
    |- <i>languageCode</i>
    |    |- <i>file</i>.xml
    |    |- <i>file</i>.xml
    |    |- <i>file</i>.xml
    |- <i>languageCode</i>
    |    |- ...
    |- <i>languageCode</i>
    |    |- ...
		
	</pre></code>

	<p>
		where <i>lang</i> is the folder you specify in the <a href="#views">\figdice\View</a>'s <a href="#views" class="CodeDocMethod">setTranslationPath</a> method,
		and the various <i>languageCode</i> subfolders are the values you give to <a href="#views" class="CodeDocMethod">setLanguage</a> method before rendering the View.
	</p>



				<h3><a name="transcaching">5-2. Caching</a></h3>

	<p>
		For efficiency purpose, FigDice can compile the XML dictionaries into PHP serialized data.
	</p>
	<p>
		If you specify a Temp Path to the <a href="#views" class="CodeDocMethod">\figdice\View</a> object through its <a href="#views" class="CodeDocMethod">setTempPath</a> method,
		your dictionary files get compiled on the fly the first time they are used, or if the source file has been modified since.
	</p>


</div>

		<div><img src="/img/slash.png" width="600" /></div>

		<h2><a name="errors">6. Error handling</a></h2>


</div>

</div>
						</div>
					</td>
				</tr>
				<tr>
					<td>
						<div id="Footer" style="clear: both; margin: auto; width: 790px; height: 76px; bottom: 0px;">

	<div id="FooterCap" style="background: url(/img/footer-bar-cap.png) no-repeat; width: 790px; height: 6px;"></div>
	<div id="FooterBackground" style="background: url(/img/footer-bar-bg.png) no-repeat; width: 100%; height: 70px;">
		<div id="FooterLinks">
			<span><a href="http://www.figdice.org/">figdice.org</a></span>
			<span><a id="linkEmail" hrf="gabriel=figdice.org">contact us</a></span>
			<span><a href="download.html">download</a></span>
			<span><a href="tutorials.html">tutorials</a></span>
			<span><a href="manual.html">manual</a></span>
			<span><a href="/reference">reference</a></span>
			<span><a href="roadmap.html">roadmap</a></span>
			<span><a href="http://sourceforge.net/p/figdice/code">participate</a></span>
			<span><a href="https://sourceforge.net/p/figdice/tickets/">report a bug</a></span>
			<span><a href="credits.html">acknowledgment</a></span> 
		</div>
	</div>
	<script type="text/javascript">
		if(a = document.getElementById("linkEmail")){a.href = 'mailto:'+a.getAttribute('hrf').replace(/=/, '@')};
	</script>

</div>
					</td>
				</tr>
			</tbody>
		</table>

        <a style="position: fixed; top: 0; right: 0; width: 149px; height: 149px; background: url(/img/forkme.png);" href="https://github.com/figdice/figdice">
        </a>

	</body>
</html>