[Chameleon-dev] MLT user's guide for Chameleon

William Bronsema wbronsema at dmsolutions.ca
Fri Jul 29 14:37:11 EDT 2005


I have written a quick developers guide for the new language handling in
Chameleon and attached it to this e-mail.  It is also available in CVS under
the docs directory.

This is a guide for people creating new widgets and popup windows in
Chameleon and need to add language support.  It also has a couple of tips on
how to speed up chameleon with caching and a default language mode.

Enjoy. ;)



William A. Bronsema, C.E.T.
Software & Applications Development,
DM Solutions Group Inc.

-------------- next part --------------
MLT for Chameleon Developers

MLTPHPInclude Overview
The MLTPHPInlcude class object was created to work with a text file to enumerate resources.  Text file format was chosen to simplify the merging and managing of multiple languages.  Each language is in a separate text file.

The format of the text file is relatively simple.  Any line that does not start with "//" and contains a ")" will be considered a valid resource.    The part of the line preceding the ")" becomes the case-sensitive index portion of the resource and the rest of the line becomes the value portion of the resource.


// this is not a resource
1) This is a resource
2) So is this
i) and this
abcdefghij) This is also a valid resource

The MLTPHPInclude class object creates a single PHP file that gets included in the PHP script using the object.  The include file generates an internal PHP array that is accessed by the get() method.  Multiple text files can be loaded into the class object.  Resources are loaded via the loadResource() method.

The PHP include file can be cached to a temp directory to allow for faster loading next time.

Usage Inside Widgets
The first thing to do to add language support to a widget is create the resource file.  Chameleon has been set up to automatically load resource files for a widget provided the resource file name is of the format <widget name>.<language>.txt.  i.e. ZoomIn.en-ca.txt for the English version of the ZoomIn widget.

To access the resources inside the widget, use the get() method on the "moMLT" member object of the widget.  i.e. $this->moMLT->get( 'ZoomIn', '5', 'This is my text’ ).

The get() method takes the following parameters:

$szID - The resource ID to reference.  In most of the cases, this will always be the widget’s own resources (i.e. ZoomIn resources) but any resource can be referenced here provided that is has been loaded.  In Chameleon there are a set of "core" resources and "common" resources that can be used.  To use them do something like the following:

$this->moMLT->get( 'common', 'ok', 'ok’ )

$szKey - The second parameter is the key to look up.  This is the index in the resource file.

$szDefault - The default value to return if any errors occurred or if the resource was not available.  This parameter is optional.

$aszParams - This is an array of arguments to run through the vsprintf() PHP function (http://ca3.php.net/manual/en/function.vsprintf.php) on the resource requested.  This allows the for more flexible messages to be saved as resources.  This parameter is optional.

$szLanguage - The language to return the resource in.  This parameter is optional.  If not supplied the current language will be returned.  This allows for multiple translations to be displayed in a single page.

Usage Inside Widget Popup Windows
Because popup windows create their own session object, the resource file must be defined in the PHP code of the popup window prior to the session being created.  To do this, you simply set a global variable called "$szLanguageResource" to the path and filename (without extension) of the resource to load.  This is done before the inclusion of the session.inc.php file.

$szLanguageResource = str_replace("\\","/",dirname(__FILE__)).'/ErrorReportPopup';

The session.inc.php file creates it’s own MLT object to use.  To reference resources insde the popup, simply reference the $oMLT object from the session.inc.php file.  i.e. $oMLT->get( 'common', 'Close', 'Close' ).

The MLTPHPInclude class object has the ability to cache the include file.  Chameleon creates a temporary PHP include file that is stored in the temp directory.  Chameleon will create a PHP include file for each template instance.   

By default caching is turned ON.  A new configuration item has been added to the Chameleon.xml config file, it is called "cache_mlt".  Its value can be either true or false to allow caching or not.

This value can be overridden in an individual application by defining a variable called 'MLT_NOCACHE' and setting it to either true or false.  This must be done in the application prior to the creation of the Chameleon instance.

define( 'MLT_NOCACHE', true );
class MyChameleon extends Chameleon

Streamlining Chameleon for Speed
Some Chameleon applications do not need language translation and, as such, should not have to pay the overhead costs of the translation.  mlt.php now includes a class that can be used in place of the MLTPHPInclude such that it will only return the default value.  This class is called "MLTPHPIncludeDefault".

This class has all the same methods and member variables as the real MLTPHPInclude class, but it does not have the overhead of including and/or processing files.  It simply returns the default value.

Chameleon can be overridden to use this default mode by defining a 'MLT_DEFAULT_ONLY' variable and setting it to true or false.  It must be set in the application before creating the Chameleon instance.


define( 'MLT_DEFAULT_ONLY', true );
class MyChameleon extends Chameleon

More information about the Chameleon-dev mailing list