Creating a Custom Control

In this article you'll learn the common technique of creating a custom item.

While creating a new item you will need to use 2 prototypes:

• dhtmlXForm.prototype.items.someItem
  the prototype defines properties, inner functions and private members of the item
• dhtmlXForm.prototype.someFunction
  the prototype defines public methods of the item

Specifying properties

To specify properties, inner functions and private members of the item use the dhtmlXForm.prototype.items.someItem prototype.
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

• "item" - the parent DIV container. The parameter is mandatory for any function, i.e. the first parameter for any function is 'item'.
• "data" - the data passed to object constructor. Through data.someText you define properties, e.g. 'data.text' defines the property 'text'.

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 Specifying functions.

render

Item constructor. All the properties of an item are specified in the render function.

render: function(item, data) {
    item._type = "myItem";//the name of the item, by which it will be referred
    item._enabled = true;
    /* 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;
}

destruct

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 */
}

enable/disable

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._enabled = true;
    /* your custom code ended here */
},
disable: function(item) {
    /* your custom code started here */
    item.lastChild.style.color = "gray";
    item._enabled = false;
    /* your custom code ended here */   
}

setValue/getValue

The methods define setting and getting value of the item. Used by the setFormData(), getFormData() methods and called while validation:

setValue: function(item, value) {
    item._value = value;// it's basic code. You can add there any custom code as well.
},
getValue: function(item) {
    return item._value;//it's basic code. You can add there any custom code as well.
}

custom events

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");
});

Specifying functions

With help of this prototype you can define public methods of the item:

• Any public method of the item is called in the following way:

  //calls method 'myFunc' of the item 'myItem'
  myForm.myFunc("myItem", ...here can be other parameters...);

• Methods already defined in form are added automatically. In case of redefinition you need to specify just inner function. dhtmlXForm.prototype.items.someFunc doesn't need to be used.
• Any public method must call the doWithItem() method, with the appropriate inner function implementing all the needed functionality, within itself:

  dhtmlXForm.prototype.someFunction = function () {
  // customFunc defined in dhtmlXForm.prototype.items.myItem
  return this.doWithItem(name, "customFunc", value);
  }

• In order to validation can be applied to the item and its value could be set(gotten) by the methods setFormData(), getFormData() you should specify the following related methods:

  dhtmlXForm.prototype.getFormData_myItem = function(name){
  return this.doWithItem(name, "getValue")
  };
  dhtmlXForm.prototype.setFormData_myItem = function(name,value){
  return this.doWithItem(name, "setValue", value)
  };

Related sample:  Custom item

Back to top