Module configuration file
What's in it ?
A module configuration file contains the full description of a module.
It contains all the binding, listeners and plugin used by the module. It also contains the name of the ModelHelper, ControllerHelper and other properties. Act carefully when editing the XML file : do not break it !
Let's take a look :
<?xml version="1.0" encoding="utf-8"?> <conf model="ModuleModel" controller="ModuleController" view="" dynamicLoad="true" folder="application/module/" version="0.1" type="simple" compressed="false" > <bind id="button" attribute="innerHTML" propertie="buttonValue"/> <bindAsListener id="button" event="click" handler="buttonClickHandler"/> </conf>
This file describes a simple module. This module is related to the model helper ModuleModel and the controller helper ModuleController. These two classes ModuleModel and ModuleController are in the folder application/module/. The dynamicLoad is set to true, that means the framework will load automatically the files application/module/ModuleModel.js and application/module/ModuleController.js. There is no view associated to it. The version of this module is 0.1.
In the DOM, there is an element called button. The innerHTML attribute of this element is binded to the propertie buttonValue in the model ModuleModel. The controller ModuleController has a method called buttonClickHandler that will be launched when the user click on the element button.
Attribute description
model
Required. The name of the model helper for this module. This name should also be the name of the file that will contains the code of your model and the name of the class in it. With the example above, you will have :
Module configuration file :
<?xml version="1.0" encoding="utf-8"?>
<conf model="ModuleModel"
...
In application/module/ModuleModel.js
var ModuleModel = Class.create(ModelHelper, {
...
});
controller
Required. Same as model helper but for the controller.
view
Optional. The URL of the view that is linked to the model helper and the controller helper.
addViewInId
Optional. The id of the DOM element where the view will be added.
dynamicLoad
Required. Can be either true or false. This attribute specify if the framework has to load the controller helper and the model helper by itself. If it set to false, you will have to include the JS files by yourself in the header of your HTML file like below :
<head> ... <script type="text/javascript" src="application/module/ModuleController.js"></script> <script type="text/javascript" src="application/module/ModuleModel.js"></script> ... </head>
It is recommanded to let the framework take care of this.
folder
Required. This is where the framework will be able to find the model helper and the controller helper files.
version
This is the version of your module. The version is used to kill client cache. When you change a module, you have to change this value.
Load : application/module/ModuleModel.js?v=1.0
type
Optional. Default to simple. The type of the module. Can be either simple or multiple. More information about this in the module type section.
compressed
Required. Can be either true or false. Is your module compressed or not ? If you set it to true, the framework will not load application/module/ModuleModel.js?v=1.0 and application/module/ModuleController.js?v=1.0 but only application/module/compress.js?v=1.0. That can be good to speed up the loading of your module (one HTTP request instead of two). The compressed file have to contain the model helper and the controller helper file. Take a look at the compression section and at the compressedName attribute.
Bind description
id
The DOM id of the element you which to apply a binding on.
attribute
The attribute to bind. Example of attribute :
innerHTML, className, value, disabled, src...
The only attribute you should not bind is style.
style
The style to bind. Example of style :
color, background-color, font-size...
If you wish to bind more than one style on the same element, you should probably bind the className attribute instead.
On the back, it will use the getStyle() and setStyle() prototype methods.
propertie
The model propertie that will correspond to the binding.
Example with the file above, you will be able to read or write the attribute 'innerHTML' of the element 'button' by using :
this.set_buttonValue('42');
alert(this.get_buttonValue()); // 42
The good thing about that is that you can bind more than one element attribute to the same model propertie. An example of that is below :
In the conf.xml of the module :
<bind id="button" attribute="innerHTML" propertie="buttonValue"/>
<bind id="toto" attribute="value" propertie="buttonValue"/>
In one of the method of the model helper:
this.set_buttonValue('42');
Both button.innerHTML value and toto.value will be change with 42.
Caution : in this case, if you are using the this.get_buttonValue() method before using the this.set_buttonValue() method, the value returned will be the innerHTML content of the element button, not the value content of the element toto (it will return the first one).
langPropertie
If your module is an international module, you probably have some static value that will just change when the lang of your application will change. This is here for that. An example below :
In the conf.xml of the module : <bind id="button" attribute="innerHTML" langPropertie="SEARCH"/> In the fr_FR.xml of your application : SEARCH = Recherche In the en_EN.xml of your application : SEARCH = Search
If the default langage is set to fr_FR, the button.innerHTML will be set to Recherche. If later you change the langage to en_EN, the framework will change it to Search. Take a look at the lang section for more information.
readOnly
Optional. As we saw above, you have two ways to interact with a propertie (the set and get method). If you set readOnly to true, the set method is not created and calling it will result as an error. Using it can speed up your module.
writeOnly
Optional. Same as readOnly but for the get method.
initPropertie
Optional. Default to true. Does the model propertie needs to be initialized ? Sometimes, you don't need to know the initialized value of the view in the model. This is done for that. Using it can really speed up the initialization of your module. When you will call for the get method for the first time, it will return undefined even if the value on the view is different.
optional
Optional. Default to false. In a PHP application, it is possible that an element is here in a case and not in another. If you bind an element that is not in the view, you will have an error. Setting optional to true will remove that.
BindAsListener description
id
The DOM id of the element you which to listen to.
event
The type of event you which to listen to. Examples of event are :
click, change, keyup...
handler
The name of the controller helper method that will be called when the event is fired. Example :
In the conf.xml of the module :
<bindAsListener id="button" event="click" handler="buttonClickHandler"/>
In the controller helper class :
var ModuleController = Class.create(ControllerHelper, {
...
buttonClickHandler: function(event) {
alert('42');
},
...
});
You can also launch a listener by listening different events on different elements. Example :
In the conf.xml of the module :
<bindAsListener id="button" event="click" handler="myEventHandler"/>
<bindAsListener id="toto" event="change" handler="myEventHandler"/>
Both click on element button and change on element toto will launch myEventHandler().
optional
Optional. Default to false. In a PHP application, it is possible that an element is here in a case and not in another. If you bind a listener to an element that is not in the view, you will have an error. Setting optional to true will remove that.
Plugin description
id
The id of the plugin to load with the module.
<plugin id="Scriptaculous"/>
See the plugin section for more information.