Download

Concepts

Example

Documentation

Plugins

How to

Contribute

Links

Model Helper

What's in it ?

For each module, you have at least a model helper and a controller helper. Here is the Model Helper.

The Model Helper is the class that will manage data of your application, plays with bindings defined in the module configuration file and more...

Let's take a look

Here is an example of a small Model Helper :

var ModuleModel = Class.create(ModelHelper, {
	initialize: function($super) {
		$super();
	},
	
	init: function($super) {
		$super();
  	},
	
	contextualDataChangeHandler: function($super, name, value) {
		alert(value);
	},

	changeValue: function(value) {
		alert(value);
	}
});

As you can see, the ModuleModel extends from ModelHelper which is the base class you will extends for every Model Helper you will developp. This base class contains some methods that will help you to deal with communication between modules, communication with his controller and more.

Forget the $ method !

If you remember what we explain in the MVC part, you remember that the ModelHelper does not know the view. That means that you should NEVER use the $ method in a ModelHelper : binding is done for that. So use it !

Do NOT do that :
$('myId').innerHTML = '42';

Do that :
...	
<bind 	id="myId" 	attribute="innerHTML"  	propertie="myIdValue"/>
...

this.set_myIdValue('42');

If you don't anderstand why or if you find that useless, you should take a look at the bindings section.

Using binding in a ModelHelper

Let's say you have in your module configuration file :

...	
<bind 	id="button" 	attribute="innerHTML"  	propertie="buttonValue"/>
...

In your HTML file :

...	
<button id="button">Click Me !</button>
...

And in a method of your ModelHelper

var ModuleModel = Class.create(ModelHelper, {
 	...
	myMethod: function() {		
		alert(this.get_buttonValue()); // Click Me !
		this.set_buttonValue('Click Me Again !'); 	// Will change the innerHTML part of the element 
								// 'button' and set it to 'Click Me Again !'
		alert(this.get_buttonValue()); // Click Me Again !
	},
	...
});

You can bind all the attributes of an element. Don't forget you can also bind styles with the style key.

...	
<bind 	id="button" 	style="color"  	propertie="buttonColor"/>
...

There is also some information in the module configuration file section.

ModelHelper methods

initialize()

You know prototype, so you know that this method is the contructor of the class. You also know that $super() is a special method from prototype that will call the parent method you are overriding. Ok, let's continue...

So in the initialize() method, you can define some constants for your module. But at this time, all the get and set methods are still not defined. So do NOT do too much in the initialize method and always call $super() in it. If you don't, the modelHelper will not be able to initialize properly.

var ModuleModel = Class.create(ModelHelper, {
	initialize: function($super) {
		$super();
		this.default = 42;
		this.set_divInnerHTML('I love the world'); // will NOT work
	},
	...
});

init(obj)

The init() method will be automatically called by the framework once the module is done initizialing. It means that this is the moment to do whatever you need to do with your module initialization (calling method, changing value with bindings or calling your controller...). The obj parameter is an object you can pass to your module if you are loading it dynamically. If your module is not loaded dynamically, obj will be an empty object.

var ModuleModel = Class.create(ModelHelper, {
	initialize: function($super) {
		$super();
		this.default = 42;
	},
	
	init: function($super) {
		$super();
		this.set_divInnerHTML('I love the world'); // will work
  	},
	...
});

You should always call the $super() method in the init() method. You can call the $super() method with six optional parameters :

  1. listenData (default is true),
  2. listenLang (default is true),
  3. listenUrl (default is true),
  4. listenDataNow (default is false),
  5. listenLangNow (default is false),
  6. listenUrlNow (default is false).
var ModuleModel = Class.create(ModelHelper, {	
	...
	init: function($super) {
		$super(true, true, true, false, false, false);
		...
  	},
	...
});

The first three defines if your module will receive data from others model helpers, lang change and url change. Setting the last two to true also depends to what you define in your framework configuration file with useLang and useUrl. If you set useLang to false and listenLang to true, you will finally not listen to lang change. Same for useUrl and listenUrl.

The last three are more tricky, it defines if you need to listen really right now or if in a few time it is ok. Most of the time, you can let them to false. On the background, it use the setTimeout(0) function. Setting them to true can really slow down your application.

More information about communication, lang and url.

launchControllerMethod(controllerMethodName, ...args)

Sometimes, you will need to call one of your controller method. This method will help you to do that. The first argument is the name of the controller method you wish to call. Let's take an example :

In your model helper :		
var ModuleModel = Class.create(ModelHelper, {
	...
	myFunction: function() {
		this.launchControllerMethod('myControllerFunction', 'titi', 42);
	},
	...
});

In your controller helper :
var ModuleController = Class.create(ControllerHelper, {
	...
	myControllerFunction: function(str, num) {
		alert(str); // titi
		alert(num); // 42
	},
	...
});

You can pass as many parameters as you wish to the launchControllerMethod() method. Most of the time, you will not use this method too much.

Take care when you use this method. On the background, it use event (the model helper doesn't know the controller helper). That means you have no guarantee of when your controller helper method will be called.

contextualDataChangeHandler(name, value)

If you already read the Model section, you know what is contextual data. If not, contextual datas are datas you are using for communication between modules. This method is the one that will receive these contextual datas.

Most of the time, your method will look like this one :

var ModuleModel = Class.create(ModelHelper, {
	...
	contextualDataChangeHandler: function(name, value) {
		switch(name) {
			case "myData": 
				this.myFunction(value);
				break;
			case "myData2":
				this.myFunction2(value);
				break;
			...
			default:
				break;		
		}
	},
	...
});

Take a look at the model section for more information.

urlChangeHandler(location, data, from)

This method is the one that will receive data when the url will change. By url, we mean the part after the # sign. The location param is the new location, data is the information you assigned with new URL and from can be one of the tree value : fromUser, fromFramework and fromInit. Take a look at the URL section for more information.

var ModuleModel = Class.create(ModelHelper, {
	...
	urlChangeHandler: function(location, data, from) {
		...
	},
	...
});

langChangeHandler(lang)

This method is the one that will be launch when the lang change in your application. The lang parameter is the new lang. Take a look at the lang section for more information.

var ModuleModel = Class.create(ModelHelper, {
	...
	langChangeHandler: function(lang) {
		...
	},
	...
});