How to create your own form control?

All form controls are defined independently that makes possible to create a new one by yourself.

Common structure of form control:

dhx.ui.passive["controlName"] = {
  render:function(){...},
  setValue:function(){...},
  getValue:function()(...}
}

By default, each control, the existed or new-created, is placed to <div> container with the fixed size: 320×35. To make height flexible, use customHeight property which allows you don't depend on default height (22px). And the with of the div can be changed in the form configuration by “width” property for this element.

So, if element height could be different for 35px, you need to define customHeight for it:

  • customHeight - (boolean) cancels predefined height value (35px). The default value is false.

As an example we'll create control with the name 'textarea'.
As size 320×35 doesn't fit us and we'd like to change size dynamically, we'll use the properties customHeight.

dhx.ui.passive["textarea"] = {
  render:function(){...},
  setValue:function(){...},
  getValue:function()(...},
  customHeight:true
}

Let's start.

render

Here we define control's parameters and their processing. Later, while creating control instance, you can specify any parameter but it will be no use. Just the parameters remained here will be processed. So, textarea. What parameters do we need to define for the control?

We'll specify the following:
1. width (the parameter - width)
2. height (the parameter - height)
3. and initial value (the parameter -value)

The function will look like this:

render: function(config){
  return "<textarea class='my_textarea' style='width:"+(config.width||100)+"px;height:"+(config.height||50)+"px'>"+(config.value||"")+"</textarea>";
}
  • in simple words, input parameter 'config' unites all the parameters specified in the control instance.

    Look at the codeline
    {view:"form", id:"myForm", data:[
                                        { type:"textarea",name:"new",value:"your text",width:350,height:150}]
    }

    Here, config unites the following parameters: 'type', 'name', 'value', 'width' and height.
    render gets the mentioned above parameters and processes them.

setValue

The function mission can be understood from the name: it sets control value.
For our control we make the following definition:

setValue:function(node, value, config){
    node.firstChild.value = value;
}
  • node - html element of the control instance: a parent <div> container with nested node, created by render method.
  • value - a value that is gotten by the form's field. In our case, the parameter has the same name - 'value'.
  • config - configuration, defined while creating control instance in form (the same as in render function).

getValue

The function specifies the return value of the control. So, it lets you to get value of the control for further usage.
We will return the same staff we've set only just.

getValue:function(node, obj){
    return  node.firstChild.value;
}
  • node - html element of the control instance: a parent <div> container with nested node, created by render method.
  • config - configuration, defined while creating control instance in form (the same as in render function).

Now, combine functions' definitions and try the control in-use (full code of the control and its usage example).

Note! Your possibilities aren't limited by these 3 functions. You can define any parameter and then specify a handler function for it.

Additional information

In form, for any control you can specify parameters:className and sameline. They allow to operate with parent <div> container (a container, where any control is placed).

  • className - (css class) lets to define additional css class for parent <div> container.
  • sameLine - (boolean) specifies whether parent <div> of the control will be placed in the same row with the previous one. If it's set to false, the control will be placed in a new row, under all the controls defined before. The default value is false.
{view:"form", id:"myForm", data:[
        { type:"textarea",name:"new",value:"your text",sameLine:true, className:"myCss",width:350,height:150}
    ]
}