In this article you'll know a common technique of creating a custom item.
While creating a new item you will need to use 2 prototypes:
The prototype can contain any functionality, but 6 methods must be defined necessarily.
dhtmlXForm.prototype.items.myItem = { //mandatory functions render: function(item, data){}, //constructor destruct: function(item){}, //destructor setValue: function(item, value){}, //sets the value of the item getValue: function(item){}, //specifies the return value of the item enable: function(item){}, // enables the item disable: function(item){} //disables the item //any custom functions custom_inner_func_1: function(){}, custom_inner_func_2: function(){}, ...
where
Important!
Custom functions specified in the prototype are inner, but to define any public function through dhtmlXForm.prototype.items.someFunc you need to define the appropriate inner function implementing all the needed functionality. See details in the chapter dhtmlXForm.prototype.items.someFunc.
Item constructor. All the properties of an item are specified in render function.
render: function(item, data) { item._type = "myItem";//the name of the item, by which it will be referred /* your custom code is started here */ item.appendChild(document.createElement("DIV")); item.lastChild.innerHTML = data.item_text;// defines the property 'item-text' /* your custom code is ended here */ return this; }
Destructor. Used by the form's method unload().
destruct: function(item) { /* your custom code is started here */ item.lastChild.onclick = null; item.innerHTML = ""; /* your custom code is ended here */ }
The methods define enabling/disabling of the item. Called while nesting items.
Let's assume you nest the new-created item into a checkbox. So, each time you check/uncheck the checkbox, the methods enable/disable will be called.
enable: function(item) { /* your custom code started here */ item.lastChild.style.color = "black"; item._is_enabled = true; /* your custom code ended here */ }, disable: function(item) { /* your custom code started here */ item.lastChild.style.color = "gray"; item._is_enabled = false; /* your custom code ended here */ }
The methods define setting and getting value of the item. Used by setFormData(), getFormData() methods and called while validation:
setValue: function(item, value) { item._value = value;// this's basic code. You can add there any custom code as well. }, getValue: function(item) { return item._value;//this's basic code. You can add there any custom code as well. }
To define a custom event you should specify when and how this event should be invoked, i.e. you should call the event in some inner methods with the needed number of parameters.
Then, you should attach it as an ordinary event and specify the desired event-handling code.
Consider, for example, an event that must be invoked on changing value of item. Name it 'onValueChanged'. As it should be invoked each time the value is changed we will call it in the method setValue.
setValue: function(item, val) { item._value = val; item.callEvent("onValueChanged",[item._idd,value]); }
We call event with some parameters. These parameters should correspond with the parameters specified in the handler function of attached event:
myForm.attachEvent("onValueChanged",function(name,value){ alert("Value has beed changed"); });
With help of this prototype you can define public methods of the item:
//calls method 'myFunc' of the item 'myItem' myForm.myFunc("myItem", ...here can be other parameters...);
dhtmlXForm.prototype.someFunction = function () { return this.doWithItem(name, "customFunc", value);// customFunc defined in dhtmlXForm.prototype.items.myItem }
dhtmlXForm.prototype.getFormData_myItem = function(name) {return this.doWithItem(name, "getValue")}; dhtmlXForm.prototype.setFormData_myItem = function(name,value) {return this.doWithItem(name, "setValue", value)};
See usage example here.