The documentation

Installation and parameter setting
To use the class ModeliXe, it must be included in your php script.
If you use ModeliXe frequently, modify the directive auto_prepend_file of your PHP.ini so as to include it automatically in all of your scripts.

After that it is used in the classic way:
  • Including the files ModeliXe, Mxconf and ErrorManager in your script.
  • The configuration file.
  • Instantiation of the class.
  • Instantiation methods.
  • Possible declaration of " plug-ins ".
  • Parsing of the templates (call of the method SetModeliXe ()).
  • Declaration of ModeliXe elements.
  • Call the of the class exit method.

Include files ModeliXe, Mxconf and ErrorManager in your scripts

To be able to use ModeliXe you must call it in the header of your files. You do this by including the file ModeliXe.php. ModeliXe will then include its own dependencies, configuration file Mxconf.php and error manager class ErrorManager.php.
The method that allows you to locate these files according to your own requirements was updated following the beta release of version 7.0 ( 0.7.0 ).
If files Mxconf and ErrorManager aren't situated in the same directory as ModeliXe, you must specify two constants, MX_GENERAL_PATH and MX_ERROR_PATH, before the include of ModeliXe itself. These two constants will contain the path (relative or absolute) of the files Mxconf and ErrorManager. Note that if you specify relative paths, they must be specified in relation to the path of your file, that includes ModeliXe, and not in relation to the file ModeliXe.php.
Here is an example for a file system tree of the type:
This would require the following include statements
		define('MX_GENERAL_PATH', '../../config/project1');
		define('MX_ERROR_PATH', '../lib/');

The configuration file

After beta version 4.0, ModeliXe integrated a configuration file which had to be named Mxconf.php (since beta version 6.1, the name changed from ModeliXe.conf to Mxconf.php).
In versions after 6.5 ( 0.6.5 ), the configuration was further modified due to the externalization of error management in ErrorManager.
In versions after 7.0 ( 0.7.0 ), the configuration file integrated an new value MX_OUTPUT_TYPE which allows the specification of the general tag type generated on exit by ModeliXe. 15 constants are declared in this file. They permit the modification of the default behaviour of ModeliXe and its error handling. These constants are as follows:
  • MX_FLAGS_TYPE, takes the value " xml ", " classical " or " pear ". It specifies the type of tag syntax used. At the moment " classical " and " pear " are equivalent. If this constant isn't assigned, the tag syntax used by default is " xml ".
  • MX_OUTPUT_TYPE, takes the value "xhtml", "xml" or "html". It specifies the type of tag generated on exit by ModeliXe. If this constant isn't assigned, the tag syntax used by default is " xhtml ".
  • MX_TEMPLATE_PATH, defines the directory in which the templates will be situated. It's possible to specify a path in the template declaration, but if this constant is assigned, the template declaration path will be relative to the MX_TEMPLATE_PATH directory.
  • MX_DEFAULT_PARAMETER, definition of the path to the default configuration file, common for the whole site. If you specify a special parameter setting file during the instantiation of the class, it will override this default.
  • MX_CACHE_PATH, specifies a directory to store cached pages.
  • MX_CACHE_DELAY, sets a maximum time to live for pages in cache.
  • MX_SIGNATURE, activates ("on") or deactivates ("off") ModeliXe signature writing within the generated HTML file. This allows an easier debugging when you are integrating foreign blocks or managing the cache. I suggest you set it to " off " when you move into production, it will save a little time on the server.
  • MX_COMPRESS, activates the compression of pages if the browser supports it (on or off).
  • MX_REWRITE_URL, uses mode_rewrite to create urls (on or off).
  • MX_PERFORMANCE_TRACER, activates performance timing (on or off).
  • ERROR_MANAGER_SYSTEM, if set to "on", errors are raised, errors are ignored if set to "off".
  • ERROR_MANAGER_LEVEL, defines the tolerated error level, the lower it's set, the less errors are tolerated.
  • ERROR_MANAGER_ESCAPE, allows you to specify a substitute local url to use in case of errors.
  • ERROR_MANAGER_LOG, allows you to define a log file.
  • ERROR_MANAGER_ALARME, specifies a comma separated series of email addresses to which alerts will be will be sent.


$page = new ModeliXe(string $templateFile, [string $sessionParameter], [string $parameterFile], [integer $cacheDelay]);

Since ModeliXe version 0.7.0, the parameter setting described in the following paragraph can advantageously be replaced by the ModeliXe's instantiation methods.

During the instantiation of the class, you can specify a series of key-value pairs (such as a session identifier) in the form of a querystring, which will automatically be integrated during the creation of hidden tags and links.
The series is optional and is composed like a querystring as it would appear on an url, for example as this sid=edfrg45ASlkkO&lang=fr
There's a ModeliXe method which allows you to easily generate a querystring, you can find it here.

During the instantiation of the class, you can specify a file of template parameters as the third argument.
This file allows the customisation of an HTML page during an initial global parsing of the template. This option allows you to adapt a generic template to a particular visual style, without having to manage this modification in the code.
This transformation is automatic and affects the whole template without respect for block division.
The syntax of this file will be shown later in this document.

Finally, it's possible to specify a cache duration for the page being generated which differs from default cache duration parameter, by assigning the argument cacheDelay. This argument must be integer and represents a cache duration in seconds. You'll find fuller information about the use and management of the ModeliXe cache here.

Instantiation Methods

Since ModeliXe version 0.7.0 (beta 7.0), you can use a set of methods to dynamically modify the configuration of ModeliXe.
These methods are divided into two groups, those whose effect can be realized at any time during the use of the class, and those which must be called before the class instancisation by SetModelixe().

Here is the list of the methods of the first group, the call anytime group:
  • $page -> SetMxCompress(boolean); activates (on) or deactives (off) compression in the outgoing HTML stream.
  • $page -> SetMxModRewrite(boolean); activates (on) or deactivates (off) rewriting of urls by mod_rewrite.
  • $page -> SetMxSignature(boolean); activates (on) or deactivates (off) the ModeliXe signature in the generated HTML file, useful for debugging blocks.
  • $page -> SetMxSession(string); specifies session parameters which will not be parsed during the use of the cache.
  • $page -> SetMxFileParameter(filePath); specifies a (pre-parsing) parameter file for the current page.

Here is the list of the methods of the second group, the call before SetModelixe() group:
  • $page -> SetMxTemplatePath(directoryPath); specification of the template directory for the current page.
  • $page -> SetMxFlagsType(string); Specification of the template tag syntax to be used (xml or classic/PEAR).
  • $page -> SetMxOutputType(string); specification of the tag type generated by ModeliXe (xhtml or html).
  • $page -> SetMxCachePath(directoryPath); Specification of the cache directory for the current page.
  • $page -> SetMxCacheDelay(integer); Specifies the time in cache value for the current page.

The return value of these methods is the value which they've modified (or not modified). They can also work as get-methods.

Declaration of "plug-ins"

$page -> AddMxPlugin(string $name, string $type, string $fonction);

This feature allows you to declare particular tags associated with external managers. This allows the flexible reuse of ModeliXe and supports additional dynamic tags in your pages managed by separate , reusable modules.
This feature has been available since version beta 4.0.
It was temporarily discontinued in the beta 6.5, and restored in the beta 6.7 reimplemented to be more performant.

Parsing of the template

$page -> SetModeliXe();

The invocation of this method is compulsory and has to be made after the declaration of "plug-ins" and before all the other call to instance methods the class ModeliXe.
It initiates the analysis of the template, its segmentation, and the address generation of the various blocks which constitutes it, and the list of tags and attributes with in it.
It's this step that allows the addition of new tags under the management of "plug-ins".

Declaration all ModeliXe elements

$page -> MxText(string $path, string $value);
$page -> MxImage(string $path, string $imageFile, [string $title], [string $imageAttribut], [string $getSize]);
$page -> MxUrl(string $path, string $url, string $queryString);
$page -> MxAttribut(string $path, string $value);
$page -> MxFormField(string $path, string $fieldName, string $value, [string $attribut]);
$page -> MxCheckerField(string $path, string $type, string $name, string $value, [string $checked], [string $attribut]);
$page -> MxSelect(string $path, string $name, string | array $selectedValue, array $Value, [string $defaultValue], [int $multipleSize], [string $javascriptAttribut]);
$page -> MxHidden(string $path, queryString $value);
$page -> MxBloc(string $path, string $operator, [string $option]);

This is the collection of methods and dynamic element declarations what we are going to look at in the following chapter.
All the methods have for their first argument a variable titled "path", which uniquely addresses a ModeliXe element in the document tree. The origin of the path is the name of the template file.
We'll get into the details shortly.

Final method

$page -> MxWrite([string $out]);

It accepts an optional argument $out, if one is supplied MxWrite doesn't write page generated to client, but returns the contents of the page, to generate files, for example. This method allows you to display the finale state of the page which you built with ModeliXe.

The Preformatting of the template
In addtion to the simple, dynamic management of a HTML document through PHP code, ModeliXe allows the generation of a prototype-document from a configuration file which is associated with it.

To clarify, this will be an intermediate step after the original template, which will be used during the final transformation by ModeliXe.
For example, this step allows the application of a visual style, simply defined by the configuration file.
When you are not manipulating dynamic information originating from a data base, or information given by the user, or from other files, etc. I recommend you to use this method to modify the form and the contents of your templates.

The parameter file setting ends with a .mxp extension. Its consists of key-value pairs, one per line, separated by an equal sign. Only the first encountered equal sign acts as separator between the key and its value.
There are two types of parameter tags, one refers to the contents of the document, the other to the attributes and tags of the document. They are distinguished by a label which must appear at least once, prior to the series of values of its type:
#flag or #attribut

This file will be read and substitute the preformating tags effective from the call to SetModeliXe() and prior to any addressing of the ModeliXe blocks within the template. It is therefore simple substitution and the only method to modifying the values contained in the preformatting tags is to modify the configuration file.

Here, to finish, is a small example of such a file.
Values for the same keys can span several lines. In that case it's necessary to frame the declaration of this value by three quotes.
			title = Welcome to my site
			sub-title = J'adore les smileys =o)
			image = <img src="ma_photo.gif">
			text = """This is a text that spans many lines.
			        Its encompassed at the beginning and end by three quotes.
			        You can declare fields of big values in this way.
			        This option exists since release beta 4.0.0 """
			backgroundColor = bgcolor="#FFFFFF"
			my style sheet = href="monStyle.css"
			email =	

The details of the tags
ModeliXe uses additional tags to the tags in HTML 4.0, consisting of normal XML tags and sublementary attribute tags.
As part of the delivery of version 1.0, I undertake to deliver a XHTML 1.0 based DTD for this tagging. At present the ModeliXe tagging consists of five types of "markers".

From the beta version 4.0, ModeliXe integrates two tag syntaxes: either normalized xml, or classic, that is close to the recommendations issued by the body PEAR (within the limits of the specification of ModeliXe, which has a functionality very different from that conceived by PEAR), and similar to that used by other template systems. I shall present this tagging with examples with a green background colour.
  • Dynamic element tags.
  • Dynamic block tags.
  • Dynamic attribute tags.
  • Tags for parameter settings.
  • The attributes of parameter settings
We'll look at each of them in turn.

Dynamic element tags

There are six of these tags, and they represent the HTML elements most commonly managed by ModeliXe. We shall see later how to define new tags to manage other situations.
These tags are constructed similarly, and respect the following syntax:

XML : <mx:tagtype(image | text | hidden | select | formField | checker) [ref="tagReference"] id="id" attributHTML/>
classic : {tagtype(image | text | hidden | select | formField | checker) [ref="tagReference"] id="id" htmlAtt[attributHTML]}

  • mx, defines the namespace of the ModeliXe tags.
  • tagtype, contains the name of the tag, it can have six values, image, text, hidden, select, formField or checker.
  • ref, the reference of the tag. This attribute is optional and serves only to facilitating reading of the template, it can contain any character except double quotes.
  • id, is the unique reference of the tag, this attribute is compulsory, and can contain any character except dot and double quotes, we advise you to make ids short so as not to create too complex an address scheme.(cf. the following paragraph).
  • New!
    attributHTML, contains all the static attributes of the HTML tag which will be generated from this ModeliXe tag. This feature exists since beta 6.1. Note that for the PEAR syntax tags, the tagging of these attributes is included in the declaration of htmlAtt[]
Tags are known as orphan tags when they have no closing elements. So like standard XML, orphan tags must be ended by a "slash".

Dynamic block tags

There is a single tag type to declare a block.
A block is a section of HTML embedded in a document, which can contain all or part of a template. Blocks can contain other blocks but cannot be split. The beginning and the end of one block can be embedded within the main document or entirely embedded within another block, but cannot be astride the boundaries of a containing block. (The same rules which apply to HTML tags).
The declaration of a block follows the following syntax:

XML : <mx:bloc [ref="externalReference"] id="id"> [HTML document] </mx:bloc id="id">
classic : {start [ref="externalReference"] id="id"} [HTML document] {end id="id"}
  • The attribute "ref" of the bloc tag has the a different semantic to that of the defined tags. It allows a block to reference the contents of an external template.
  • Id, is the attribute containing the unique reference for the tag, this attribute is compulsory, and can contain any character except dot and double quotes. We suggest you make the value short. Note, the opening and closing tags must have the same value for the id attribute.

Dynamic attribute tags

There is only a single type of ModeliXe attribute "tag", but its form allows it to manage any HTML (or more generally xml) attribute.

If the same HTML tag includes several dynamic attributes these attributes can be declared one after the other in the same mXattribut tag. In classic syntax tagging, the name of the attribute and its value are separated by one equal sign =, while in XML syntax they're separated by a colon : .
In both cases, the attributes name-value pairs are separated from one another by one semi-colon ; .

These attributes take the form of a classic HTML attribute, which allows them to be placed among the other attributes of the tag:

XML : mXattribut ="HtmlAttributName1:AttributReference1"
XML multiple declaration : mXattribut =" HtmlAttributName1:AttributReference1; HtmlAttributName2:AttributReference2; ..."
Classic : {string typeAttribut HtmlAttributName1=AttributReference1 }
Classic multiple declaration : {attribut HtmlAttributName1=AttributReference1; HtmlAttributName2=AttributReference2; }

  • The type of the attribute can be any standard HTML or XML tag attribute. But one of those values, the URL, will be the object of special treatment by ModeliXe's methods.
  • Id of the attribute plays the same role as other ModeliXe tags. It allows a unique reference to attribute within the template. Note the id of an attribute cannot contain commas, nor spaces, dots characters, double quotes, or simple quotes.

Parameter setting tags

These tags allow zones to be specified in the document, the contents of which will automatically be substituted by values read from a parameter file.
They are the complement of parameter attributes which we'll look at a little farther on.
These tags are all constructed in the same way, and respect the following syntax:

XML : <mx:preformatting id="id"/>
Classic : {preformatting id="id"}

  • mx, the namespace of the ModeliXe tags.
  • id, is the unique reference of the tag. This attribute is compulsory and can contain any character except dot and double quotes. The tag won't be added to the address scheme during the parsing of the template because it is only present during the pre-formatting step of template generation.
Tags are known as orphan tags when they have no closing elements. So like standard XML, orphan tags must be ended by a "slash".

Parameter setting attributes

These attributes complement the parameter setting tags and allow the definition of HTML or ModeliXe attributes, the contents of which will be automatically replaced by the values read from the parameter file.
These attributes are all constructed in the same way, and respect the following syntax:

XML : mXpreformatting="id"
classic : {preformattingAtt id="id"}

  • id, is the unique reference of the tag, this attribute is compulsory, and can contain any character except dot and double quotes. The tag won't be added to the address scheme during parsing of the template because it is only present during the pre-formatting step of template generation.

The details of addressing
ModeliXe uses addressing rules to reference its components. These rules can be divided in two sets:
  • The addressing of ModeliXe elements within the template.
  • The addressing of ModeliXe elements within the php script.

Addressing within the template

Every ModeliXe tag or ModeliXe attribute possesses an "id". This attribute serves as unique identifier of the tag within a block.
The main document itself constitutes the outermost block, but is independent of the addressing of the tags which it contains and the other blocks which it may contain.
So one can envisage that ModeliXe can have two tags with the same id, but if one belongs to the main document, and the other one is located inside a block within the document, their actual addressing by the class ModeliXe won't be the same, and we shall thus have two valid tags with different content.

ModeliXe tags possess an attribute " ref " which allows comments to be assigned to the tag, and so by describing its role, make template simpler to read and understand.
But please note, the meaning of the attribute " ref " within a block tag is completely different. It allows you to link a block to an external template..

Addressing within the php script

Once the template file is parsed, ModeliXe creates an address for each of the ModeliXe components. This address system is inspired by the XML document object model (DOM) address system.

In absolute addressing, the root address of all components is the name of the template file itself.

Since the beta version 6.0 of ModeliXe this root must be mentioned only in absolute addresses. The address system is relative by default and contains the reference to the most recent block referenced with WithMxPath. This will, by default, be a reference to the document root if no call to WithMxPath was yet made.

Every ModeliXe element in the template continues to identified by its id.

So, a tag ModeliXe <mx:text id="texte"> in the template "test" will have the address "texte" and not "test.texte" .
A ModeliXe tag <mx:image id="image"> within the block "bloc" within template "test" will have the absolute address "test.bloc.image" and a default relative address "bloc.image" or, after a call to WithMxPath("bloc"), "image". br> This access path to a template element must be declared during the call of the method which assigns it a value.

One, call any time, method allows us to know the original path of the current element, it's $page -> GetMxPath([string $id])
This method returns the original path if one calls it without an argument. In the case where there are several elements with the same id, it returns an associative array with, as key, the type of the tag plus a serial number and, as value, the absolute path of the tag.
Full details of using the method are here.

Since the beta version 3.1 of ModeliXe, a new method simplifies the addressing of components within the template. It does this by making an addresses relative to a specific assigned root, in this way $page -> WithMxPath([string $absolutePath])

Declaration of a text field
The declaration of a text element is made with a text-type ModeliXe tag within the template (cf. above).
The method of declaring a text tag as follows:
$page -> MxText(string $path, string $value);
  • The path parameter specifies the block address of a text-type ModeliXe tag within the template, it contains the relative or absolute path (relative by default) up to the enclosing block, then id of the tag.
  • The value parameter contains the text to be displayed.

Declaration of an image
The declaration of an image is made with a by image-type ModeliXe tag within the template (cf. above).
The declaration of an image-type tag is as follows:
$page -> MxImage(string $path, string $imageFile, [string $title], [string $imageAttribut], [string $getSize]);
  • The path parameter specifies the block address of the ModeliXe image-type tag within the template, it contains the relative or absolute path (relative by default) to the containing block, then id of the tag.
  • The image parameter contains the path from the php script, to the image file.
  • The title parameter contains the title of the image, otherwise a default title will be created from the name of the image.
  • The imageAttribute parameter contains all attributes of the image tag, not managed by ModeliXe, they'll be copied out verbatim when the tag is created. Note that size attributes aren't necessary because they are directly generated by ModeliXe.
  • GetSize is an optional parameter, if its assigned ModeliXe won't generate default image size attributes allowing you to manage them your own way via imageAttribut.

Declaration of a hidden field
The declaration of a hidden field is made by means of a hidden-type ModeliXe tag within the template (cf. above).
Unlike other methods, the declaration of a ModeliXe hidden tag generates several actual HTML tags one for each key-value pair passed to the method.
In the same way, the session parameters declared during the instantiation of the class ModeliXe will automatically be passed on, without the developer having to re-declare them, (a feature that largely facilitates session management).

The declaration of a hidden field tag is made as follows:
$page -> MxHidden(string $path, queryString $value);
  • The path parameter specifies the block address of the hidden-type ModeliXe tag within the template, it contains the relative or absolute road (relative by default) to the enclosing block, then id of the tag.
  • The value parameter contains the key-value pairs to be contained in the generated hidden tags. They must be declared like a "query-string", following this pattern: key1=value1&key2=value2&key3=value3 etc....
    If session parameters were declared during the instantiation of the class ModeliXe, they'll automatically be added.

Construction of a querystring

One of ModeliXe's methods allows the automatic construction of querystring from an associative array of key-value pairs to passed as a parameter. The method referred to is GetQueryString, and here is its call syntax: $page -> GetQueryString(associativeArray $value);

One can use it with a array which you should create in this way:
			$parametreSession["sid"] = $sid;
			$parametreSession["lang"] = $lang;

			$queryString = $page -> GetQueryString($parametreSession);
For more information, please read the documentation here.

Declaration of a select
The declaration of a select tag is made with a select-type ModeliXe tag within the template (cf. above).
The MxSelect tag declaration is made as follows:
$page -> MxSelect(string $path, string $name, string | array $selectedValue, array $Value, [string $defaultValue], [int $multipleSize], [string $javascriptAttribut]);
  • The path specifies the block address of the tag ModeliXe of type select within the template, it contains the relative or absolute path (relative by default) to the enclosing block, then id of the tag.
  • The name parameter will be the name given to the select and the name of the variable with which will return the selected value. If it's a multiple select you will get back an array, the method will take care of this.
  • SelectedValue, contains the default selected value or values. It can therefore involve an array or a simple string.
  • Value, contains the array of the key value pairs which comprise the select.
  • defaultValue, contains the null value of the select (for example a string asking the user to select a value), if it is selected it will return #.
  • multipleSize, allows the declaration of a multi-value select and to provide the number of items returned.
  • javaScriptAttribut, makes it possible to add scripts or HTML attributes to the select, they'll be added directly to the tag.

Declaration of an url
The Declaration of an url is achieved by means of a ModeliXe tag of type attribute within the template.
Since the beta version 6.3, its not important which attribute is handled by the method MxUrl, it's enough to give the correct path. However the ModeliXe attribute "url" must be handled with MxUrl. This change was made to be able to generate special urls (internal anchors on the page, javascript, etc.) managed classically by the method MxAttribut and session parameters managed classically by MxUrl. Thus the modelixe attribute " href " can be handled by either method.
The method of declaration a url attribute is as follows:
$page -> MxUrl(string $path, string $url, [(string | associativeArray) $queryString], [boolean $noSid]);
  • The path specifies the block path of the ModeliXe attribute tag within the template, it contains the relative or absolute path (relative by default) to the enclosing block, then id of the tag.
  • The url is the complete url without querystring, to which the link points.
  • querystring is an optional argument, which allows the addition of query elements to the url. The session parameters declared during the instantiation of the class will automatically be integrated into the url.
  • NoSid, is an optional boolean argument which defaults to " false ". If it is set to true, the session parameter is NOT added to the querystring.
There's a ModeliXe method for easily generating a querystring, you can look it up here.

Declaration of the attributes of a form field
The Declaration of name and value attributes of a ModeliXe form tag is achieved with a ModeliXe formField tag within the template (cf. above).
The method of declaring a formField attribute is as follows:
$page -> MxFormField(string $path, string $type, $string name, string $value, [string $attribut]);
  • The path parameter specifies the path to the ModeliXe tag within the template, it contains the relative or absolute path (relative by default) to the enclosing block, then id of the tag.
  • The type parameter specifies if a textarea, or a tag of type text, etc should be generated. It can take the values " textarea ", " password ", " text ", "image", " submit ", "row" and " button ".
  • The value parameter assigns a value to the attribute of the relevant tag.
  • Name assigns a value to the attribute "name" of the relevant tag.
  • The attribute parameter is optional, it allows the specification of further attributes of the tag.

Declaration of a checkBox or radio field
The Declaration of checkBox fields and radio fields is achieved by means of a ModeliXe tag of type " checker " within the template ((cf. above).
The method of declaring a checker tag is as followings:
$page -> MxCheckerField(string $path, string $type, string $name, string $value, [string $checked], [string $attribut]);
  • The path parameter specifies the path to the ModeliXe checker tag within the template, it contains the relative or absolute path (relative by default) to the enclosing block, then id of the tag.
  • The type parameter specifies the type of the checker, it's permitted values are "radio" or " checkbox ".
  • The name parameter provides a name for the CheckBox input tag.
  • The value parameter allows assignment of a value to the input tags "value" attribute.
  • The Checked parameter is optional, if its assigned, the corresponding input tag will be checked.
  • The Attribute parameter is optional. It allows you to specify further attributes of the tag.

Dynamic declaration of an HTML attribute
The dynamic declaration of HTML attributes is achieved by means of the ModeliXe attribute tag within the template (cf. above).
The method of declaring of a dynamic attribute as follows:
$page -> MxAttribut(string $path, string $value);
  • The path allows the specification of the location of the ModeliXe attribute tag within the template, it contains the relative or absolute path (relative by default) up to the enclosing block, then the id of the tag.
  • The value will be assigned to the target attribute of the HTML tag.

Blocks management
In the template philosophy, a block is the document structural entity, it allows flexibility and dynamism in the created HTML page. Here are some important definitions:
  • A block is an entity made of a part of the ModeliXe template, and is delimited by a start and an end tag sharing the same id.
  • A block creates a hierarchy into the ModeliXe addressing space, and each ModeliXe element inside a block is independent of the elements contained in the child blocks (Translator's note: I don't quite understand the meaning of the French sentence).
  • A block and its content may be deleted, replaced or multiplied as many times as you like.
Block declaration
A block is declared with the ModeliXe block tag inside the template. (see above).
$page -> Mxbloc(string $path, string $operator, [string $option]);
  • The $path specifies the tag location inside the template, it contains the absolute or relative (relative is the default) path toward the block containing this block, followed by this block id.

    Warning ! Notice the addressing differences when using WithMxPath in absolute or relative mode. By default, addressing is relative and the main document is the root. So, the address of the block "bloc2" contained inside "bloc1", itself inside the main document, is "bloc1.bloc2". Look into WithMxPath documentation for further explanations.

  • $operator is used to specify the kind of operation used on the block. It can take six different values on which we'll discuss later.
  • $option is a complementary parameter used when some specific value of $operator is used.

Important remarks

It's very important to know how ModeliXe works in order to really understand how blocks behave.
When the template is parsed, ModeliXe divide it into blocks: each block can be reached through its address.
This is the one true ModeliXe womb. ModeliXe builds the page draft from the skeleton given by those blocks, the real page is going to be built only when the final method is called.

Thus, it is always possible rework the draft by calling the initializers or destructors methods brought by ModeliXe, but in the later case, all the components associated with the destroyed block disappear as well.
Pay attention to the fact that the draft dominates the blocks. For instance, when building the draft, if two blocks are merged (one inserted into the other for instance), the relative addressing of each of the ModeliXe elements which are still not instantiated could raise a problem if the id are duplicated, and you won't be able to distinguish between the two.

Added to the draft, ModeliXe uses in the case of a loop additional temporary drafts for managing the block replication. This way it can add the different instances while not loosing the inside components. You can't access those temporary drafts.

Blocks usage
Let's deal with the block functionnalities.
New !
Since version 6.3beta, blocks operators have been improved, and they can be classified in two groups: those which modify definitely the block, and those which don't.
Here they are:
  • Replacement ("remplace" operator). Allows to replace the block content with the third argument of the ModeliXe method. This one may be a template. It's a temporary alteration.
  • Concatenation ("append" operator). Allows to append to the block content the value of the third argument of the ModeliXe method. This one may be a template.
  • Modification ("modify" operator). Allows to replace the block content with the third argument of the ModeliXe method. This one may be a template. It's a permanent alteration.
  • Deletion ("delete" operator). Allows to delete a block and its children. It's a temporary alteration.
  • Destruction ("reset" operator). Allows to delete a block, its children and it's draft. If this draft has already been used for instantiating, it's not destroyed. It's a permanent alteration.
  • Looping ("looping" operator). Allows to concatenate different instances of a block, in a loop for instance. It's a temporary alteration. Only an instance is appended, with no impact on the skeleton.
Loops are easy to set up, as soon as you understand well the block mechanisms. Let's see two test cases.

Simple loop

Goal: create a table with a pupils list, ordered by their rank. The two columns are: rank, name and firstname.
We suppose we've got this information in an array ($eleves), that we have to traverse.
The template is a one-line table declared in the block "bloc", inside template "test". This block contains two ModeliXe tags of "text" type ("numero" and "identite"). The corresponding PHP script is here:
				$test = new ModeliXe( "test" );
				$test -> SetModeliXe();

        for ($i = 0; $i < $eleves; $i ++){
						$test -> MxText( "bloc.numero", $i);
            $test -> MxText( "bloc.identite", $eleves[ $i ]);

            $test -> Mxbloc( "bloc", "loop" );

        $test -> MxWrite();

The only specificity in this code is the use of the "loop" operator. This way every new table line is added without erasing the previous one.

Nested loops

Let's add a new feature, now we'd like to display the pupil's marks: they are in an associative array $notes, with the pupil's name as key.
We want to display that in the second column, inside another table. So we put in the template the block "blocnote", which contains an HTML table. This table contains a ModeliXe "text" tag ("note"), for displaying one pupil's mark.
So we have two nested loops: the first one for pupils (the previous one), second one for marks.

Since ModeliXe 0.5, it is not required to initialize a block before looping.
Here is the PHP script:

            $test = new ModeliXe( "test" );
            $test -> SetModeliXe();

            for ( $i =  0; $i < $eleves; $i ++){

                $test -> MxText( "bloc.numero", $i);
                $test -> MxText( "bloc.identite", $eleves [ $i ]);

                for ($j = 0; $j < count ( $notes [ $eleves [ $i ]]);$j ++){
                    $test -> MxText( "bloc.blocnote.note", $notes [ $eleves [ $i ]][ $j ]);

                    $test -> MxBloc( "bloc.blocnote", "loop" );
                $test -> MxBloc( "bloc", "loop" );

            $test -> MxWrite();

Calling Mxbloc with the "loop" operator in the sub-block allows to insert instances of it in the current block.
This is done as well when MxWrite is called in order to assembly all the blocks, outside a "loop" context.
New !
If you don't want to put child blocks, you must use the "delete" operator, otherwise ModeliXe is going to add it, even if it hasn't received any treatment. Sample #8 illustrates this point.

Warning !In the case of relative addressing, it is not required anymore to put the absolute path, but only the relative path from the current bloc. If the concerned bloc is the current, leave the path empty.

Insertion of an external template
ModeliXe also allows you to integrate external templates, to separate for example a file template managing a generic menu, used by several files.
This allows the implementation of the equivalent of an include

The procedure is simple and transparent, it's enough to specify in the attribute " ref " of a block declaration, the complete path starting from the php script to the template to be integrated.
One can also achieve the same effect with the Mxbloc method, using the operator " modify ", but this method although more flexible, will be a slightly less performant.

Using plug-ins
Plug-ins is a means offered by ModeliXe to integrate new methods of managing certain tags, in the most flexible way possible.
They're will, for example, allow you to easily create your own modules for managing translation, advertising banners, posting information, etc.
The principles of the ModeliXe tag system remain, but the name of the tag, and the way its contents will be managed, will be determined by you.

Declaration of a plug-in

A plug-in is declaired my means of the method AddMxPlugIn().
It's defined by three elements, its name, that is to say the name carried by the new tag or attribute, its type - to clarify if its going to manage tags, or tag attributes; and finally the function which will be called directly by SetMxPlugIn() during the instantiation of a tag managed by the plug-in.

Here is an example of calling the method :
$page -> AddMxPlugIn(String $name, (flag | attribut) $type, string $function)

This call will associate the management of the contents of $type tags with the name $name (for example a tag <mx:myplugin id="ref"/>) with the function $function:

instantiation of a plug-in

A plug-in tag is instantiated by the method SetMxPlugIn() in the same manner as other elements of the template.
instantiation uses three arguments, the name of the plug-in being used in the instantiation, the block path to the instance of the plug-in tag, and an associative array containing the argument to be passed to the function mapped to the plug-in and declared in AddMxPlugIn which will generate the contents of the tag.

Here is an example of calling the method :
$page -> SetMxPlugIn(String $name, string $id, associative array $arguments)

And here is something to show that in the context of a script. The plug-in here returns as content the sum of two numeric arguments. One could imagine a much more complex plug-in, using several arguments, which would generate for example a list of news headlines from an XML file. The principle would be the same.
			function maFonction($argumentsArray){
				$num1 = $argumentsArray["num1"];
				$num2 = $argumentsArray["num2"];

				return ($num1 + $num2)


			$page -> ModeliXe("template.mxt");

			$page -> AddMxPlugIn("MyPlugIn", "flag", "myFunction");

			$page -> SetModeliXe();

			$page -> SetMxPlugIn("MyPlugin", "template.texte1", array("num1" => 1, "num2" => 3));
			$page -> SetMxPlugIn("MyPlugin", "template.bloc1.texte2", array("num1" => 5, "num2" => 6));

			$page -> MxWrite();

Important !
The callback function used by the plug-in must accept a single parameter, an associative array from which it must extract the individual arguements that it needs.
The argument array will be that supplied by the method SetMxPlugIn.

Use of a plug-in

Plug-ins are a means to manage the elements of a page which require special treatment. They help making the code more readable and afford more modularity in your development projects.
If you have developed a module specifically to generate the content of certain types of elements in your pages, you can make it a separate class or script, and you won't have to do more to integrate the result than call the method AddMxPlugIn().
This will be especially the case for elements such as text translations, advertising banners, headlines, etc...
In parallel with the ModeliXe development, extra modules are being created, and will be available from this site shortly.

Cache Management
Since the version beta 5.2, ModeliXe has included a semi-cache system, which allows increased performance, particularly in the case of a site with heavy traffic or of a site including very long, complex pages.
This cache system is parameterized by default in the ModeliXe configuration file. However, you can specify a cache lifetime for a specific page, with the optional fourth argument of the ModeliXe constructor.

Attention !
ModeliXe uses a semi-mask mechanism, which means that session parameters are not influenced by the cache and will be passed on from page to page. This will be done without resorting to cookies, but rather, as normal, via the URL or hidden fields.
You retrieve all these parameters normally for all your pages, the only elements concerned with the cache are those dynamically generated by your PHP scripts (database requests, dates, etc ...). Don't worry, pages are cached individually depending on if they were created by GET or POST.

Example :
If you are displaying a cinema schedule invoked by parameteres of this type :
The page displayed will be generated according to the request will be different from a page taken from cache as a result of the request: cinema.php?sid=ertyuiop123&ville=38&hour=22.
On the other hand it will be identical to the page generated by this request :
session parameters are not stored in the cache.

The ModeliXe toolkit
Here are the ModeliXe utilities methods, the way to have more pleasant coding.
Are addressed:
GetMxPath, Get the path of a ModeliXe element from its id.
Deprecated since version 0.6.5
GetQueryString, query string generation
ModeliXe uses internally query strings for sessions parameters and for hidden tags in forms.
In order to simplify the developer work, you can simply create this string from an associative array.
$page -> GetQueryString(associativeArray $value);

            $parametereSession["sid"] = $sid;
            $parametereSession["lang"] = $lang;

            //Génération de la querystring
            $queryString = $page -> GetQueryString($parametereSession);
WithMxPath, Relative addressing management
Managing the addressing can be cumbersome when there you insert several blocks. In order to ease this task, WithMxPath has been added in version 0.3.1. It allows to manage a relative addressing from a given path.
Synopsis: $page -> WithMxPath([String $path][String ("absolute" | "relative")])

This way, you declare a new root for future relative addressing.

Relative addressing
You can call WithMxPath with a relative (default) or an absolute path. The latter must be used with "absolute" as second parameter of course.
The relative addressing is incremental, thus it takes in account all the previous WithMxPath calls. There are two ways to go back in the hierarchy:

  • Give an empty path: this will reset the addressing from the document root.
  • Use ../ to go up one level: $page -> WithMxPath("../siblingPath");

Absolute addressing
In that case, the path must contain the reference of the document root (that is, the template file name without its extension). This way, the path contains the complete address from the document root. You must specify "relative" if you want to go back to the relative mode of WithMxPath.
In absolute addressing mode, you have nothing to specify to go back one level, because nothing is above the root.

Sample with a "test" template.:
            $page = new ModeliXe("test.mxt");

            //Relative addressing by default, so we are
            //at the document root
            $page -> MxText("texte1", "Bonjour");

            //New addressing, absolute mode
            $page -> WithMxPath("test.bloc", "absolute");

            //Now we are in the "test.bloc" block
            $page -> MxText("texteDuBloc", "je suis dans un bloc");

            //New addressing, relative against "test.bloc"
            $page -> WithMxPath("bloc2", "relative");

            //We are now in "test.bloc.bloc2"
            $page -> MxText("texteDuBloc2", "je suis dans un sous bloc");

            //Moving back
            $page -> WithMxPath("../bloc");

            //Now in  "test.bloc"
            $page -> MxText("texte2DuBloc", "je suis de nouveau dans ce bloc");

            //We're still in relative mode, going again in "bloc2"
            $page -> WithMxPath("bloc2");

            //Back to the root
            $page -> WithMxPath();
Please note !The method can take an empty $path. In that case, whatever the addressing mode, the new path is the document root.
AboutModeliXe, ModeliXe license
This method displays the ModeliXe license and the conditions of use.
$page -> AboutModelixe([String $outputMode])
The parameter $outputMode is optional, if it's present, the method returns the license, otherwise it displays it.
MxErrorManager, error management under ModeliXe.
This method is deprecated since version 0.6.5.
Error handling is now achieved through the ErrorManager class (ModeliXe inherits from this class). Five properties declared in Mxconf.php are used to define the behaviour.

  • ERROR_MANAGER_SYSTEM, errors are reported if set to "on", ignored if "off".
  • ERROR_MANAGER_LEVEL, level of ModeliXe tolerance regarding errors. One of the 5 error levels: Low Warning, Warning, Notification, Error, Emergency break.
  • ERROR_MANAGER_ESCAPE, replacement URL when an error occurs.
  • ERROR_MANAGER_LOG, log filename.
  • ERROR_MANAGER_ALARME, a coma separated email addresses list, where to send error messages.

Error capture
ErrorManager has two methods to manage errors: ErrorTracker() et ErrorChecker().

ErrorTracker() allows to report errors and associate with them specific error level and message. If the error level is below the threshold specified in ERROR_MANAGER_LEVEL, they are simply saved, otherwise they are exported by ErrorChecker().
$page -> ErrorTracker($level, $message, $function, $line, $file);

ErrorChecker(), allows to control that no error of a level above the threshold specified in ERROR_MANAGER_LEVEL has been thrown..
$page -> ErrorChecker(); // Detects error more serious than specified by ERROR_MANAGER_LEVEL.
$page -> ErrorChecker($level); //Detects error even or more serious than $level.
$page -> SetErrorOutput("get"); //returns the current error message it there is one. It there isn't any, returns true.

Dynamic alteration of the behaviour
The default behaviour will be changed through SetErrorLock() and SetErrorOutput().

SetErrorLock( true | false), errors are reported if true (put ERROR_MANAGER_SYSTEM to on).
$page -> SetErrorLock(true); //activation

SetErrorOutput( url), modifies ERROR_MANAGER_ESCAPE, by specifying a new URL.
$page -> SetErrorOutput("excuse.html"); // in case of error, redirect the user toward excuse.html
$page -> SetErrorOutput(""); // in case of error, redirect the user toward an excuse page
$page -> SetErrorOutput("excuse.php?origine=$origine&raison=$raison"); // redirection toward a dynamic excuse page
Get the block content given its absolute path. If the block has been instantiated, returns the instance, otherwise returns its local template declaration:
$page -> MxGetBloc("page.bloc1");

Remove all the files corresponding to the current template from the cache. Thus, all the information is refreshed, especially from a database.
$page -> MxRefresh();

Returns the time spent between ModeliXe instantiation and this call to GetExecutionTime.
You can also use it if MX_PERFORMANCE_TRACER is set to "on" in Mxconf. This way, the execution time between instantiation and output is shown at the location of the tag &ltmx:performanceTracer /&gt.
<mx:performanceTracer />

The timing works both when the cache is activated and not. If cache is used, the timing is displayed followed by the mention [cache].

ModeliXe - PHP Template Engine - © Thierry ANDRE 2001 - Usage under the conditions of the GNU - LGPL - bet 6.7

Powered By ModeliXe
in 0.1422 s.