List of Controls

Block

allows combining several sense-connected items. It's identical to fieldset but doesn't have label and frame.

Attributes

blockOffsetnumberleft-side offset of the item content (default 20)
classNamestringthe user-defined css class for block's items
disabledbooleandisables/enables the block's items
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the position is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the position is set as "absolute"
namestringthe identification name. Used for referring to item
listarraydefines the array of nested elements
offsetLeftnumbersets the left relative offset of item
offsetTopnumbersets the top relative offset of item
positionstringlabel-left, label-right, label-top or absolute - defines the position of label relative to block. As just labels are defined for block, just value absolute makes sense and is used for setting absolute label position
widthnumberthe width of block


var formData = [
    {type: "settings", position: "label-right"},
    {type: "block", width: 900, list:[
        {type: "label", label: "Internal Color"},
        {type: "radio", name: "n1", value: 1, label: "Red"},
        {type: "radio", name: "n1", value: 2, label: "Orange"},
        {type: "radio", name: "n1", value: 3, label: "Yellow"},
        {type: "radio", name: "n1", value: 4, label: "Green"},
        {type: "radio", name: "n1", value: 5, label: "Blue"},
        {type: "button", value: "Yes"},
        {type: "newcolumn"},
        {type: "label", label: "External Color"},
        {type: "radio", name: "n2", value: 1, label: "Red"},
        {type: "radio", name: "n2", value: 2, label: "Orange"},
        {type: "radio", name: "n2", value: 3, label: "Yellow"},
        {type: "radio", name: "n2", value: 4, label: "Green"},
        {type: "radio", name: "n2", value: 5, label: "Blue"},
        {type: "button", value: "No"}
    ]}
];

Btn2state

presents a customizable checkbox

Attributes

checkedbooleandefines whether or not checkbox will be checked initially. The default value is "false"
classNamestringthe user-defined css class for item
cssNamestringallows setting individual look for a specific item's instance (see details below)
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the position is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the position is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of the item
labelAlignstringleft, right or center - the alignment of label within the defined width
labelHeightstring|numberthe height of DIV where the label is placed (not the font size). The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the position is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the position is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
listarraydefines the array of nested elements
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to check box
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the "NotEmpty" validation rule to the input
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by button click in browser (meanwhile, item's value can be changed programmatically anytime)
tooltipstringcreates the tooltip for the input label
valuestringthe initial value of item
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type:"label", label: "Settings"},
    {type: "btn2state", label:"Auto-update the app",checked:true,
       info:true,required:true},
    {type: "btn2state", label: "Configure privacy settings", list:[
        {type: "btn2state", label: "Start when I start Windows"},
        {type: "btn2state", label: "Allow to be shown on the web"},
        {type: "btn2state", label: "Accept browser cookies", checked:true}
    ]}
];

Details

The control behaves itself as a checkbox but doesn't have any visual representation ( i.e. if you simply add it to the page the page will display nothing (it just adds an empty DIV).

To form the look of the control you should specify 4 css classes with the following names (the css classes will be applied to all controls of type bt2state):

  • .dhxform_obj_dhx_skyblue div.dhxform_img.btn2state_0 - applied when the item is enabled and not checked
  • .dhxform_obj_dhx_skyblue div.dhxform_img.btn2state_1 - applied when the item is enabled and checked
  • .dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.btn2state_0 - applied when the item is disabled and not checked
  • .dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.btn2state_1 - applied when the item is disabled and checked
.dhxform_obj_dhx_skyblue div.dhxform_img.btn2state_0 {
    background-image: url("imgs/toggle_off.png");
    width: 42px;
    height: 20px;
};
.dhxform_obj_dhx_skyblue div.dhxform_img.btn2state_1 {
    background-image: url("imgs/toggle_on.png");
    width: 42px;
    height: 20px;
};
.dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.btn2state_0 {
    background-image: url("imgs/toggle_off_dis.png");
    width: 42px;
    height: 20px;
}
.dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.btn2state_1 {
    background-image: url("imgs/toggle_on_dis.png");
    width: 42px;
    height: 20px;
}
 
formData = [
    {type: "btn2state", label: "Update the app automatically", checked: true},
        ...
]

To set the look of just a specific bt2state instance you should use the cssName attribute.

In this case, CSS classes must have the following names:

  • .dhxform_obj_dhx_skyblue div.dhxform_img.[cssName]_0
  • .dhxform_obj_dhx_skyblue div.dhxform_img.[cssName]_1
  • .dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.[cssName]_0
  • .dhxform_obj_dhx_skyblue div.disabled div.dhxform_img.[cssName]_1

Related sample:  Button 2-State

Button

presents a standard button

Attributes

classNamestringa user-defined css class for an item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
inputLeftnumbersets the left absolute offset of control. The attribute is applied only if the *position* is set as "absolute"
inputTopnumbersets the top absolute offset of control. The attribute is applied only if the *position* is set as "absolute"
namestringthe identification name. Used for referring to item
offsetLeftnumbersets the left relative offset of item
offsetTopnumbersets the top relative offset of item
tooltipstringcreates the tooltip for the control label
valuestringthe text label of button
widthnumberthe button's width
userdataobjectsets some user data for the control "key:value" pairs)
var formData = [
    {type: "label", label: "Protocols"},
    {type: "checkbox", name: "ssl", label: "Use SSL 3.0", checked:true},
    {type: "checkbox", name: "tls", label: "Use TLS 1.0", checked:true},
    {type: "button", name: "btn", value: "Save Changes"}
];

Related sample:  Button

Calendar

dhtmlxCalendar integration. Presents date field with a pop-up calendar.

Please note, in order to use the calendar item you must include 2 files:

<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlx.css">
<script src="../codebase/dhtmlx.js" type="text/javascript"></script>

Using dhtmlxCalendar API

To use the dhtmlxCalendar API for the item, get the calendar object as in:

var dhxCalendar = myForm.getCalendar("myCalendar");
...
dhxCalendar.showTime();

Attributes

calendarPositionstringbottom/right - sets the position pop-up calendar will appear from. The default value is bottom
classNamestringthe user-defined css class for item
dateFormatstringsets format of date presentation in input (see available format characters in setCalendarDateFormat)
disabledbooleandisables/enables the item
enableTimebooleandefines whether time manage elements will be presented at the bottom of the calendar
enableTodayButtonbooleandefines whether the Today and Clear buttons will be displayed at the bottom of the calendar
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the *position* is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the *position* is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignleftright or center, the alignment of a label within the defined width
labelHeightstring|numberthe height of a label. The default value is "auto"
labelLeftnumbersets the left absolute offset of a label. The attribute is applied only if the *position* is set as "absolute"
labelTopnumbersets the top absolute offset of a label. The attribute is applied only if the *position* is set as "absolute"
labelWidthstring|numberthe width of a label. The default value is "auto"
minutesIntervalnumber1/5/10/15 - the time interval (in minutes) for the predefined values in the time selector. The default value is 5
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by typing in the input (you are still able to set the value by clicking on the calendar icon). Can be used to exclude the possibility of entering incorrect values
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to "true" automatically assigns the 'NotEmpty' validation rule to the input
serverDateFormatstringthe format in which the date is stored on server (see available format characters setCalendarDateFormat)
showWeekNumbersbooleanenables/disables an additional left column with weeks' numbers. By default, *false*
tooltipstringcreates the tooltip for the input label
validatefunctionpredefined rule or custom function - sets the validation rule. See details in the chapter Validation
valuestringthe initial value of item
weekStartnumberfrom 1 to 7 - sets the start day of a week. '1' relates to Monday and '7' to Sunday.
userdataobjectsets some user data for the input "key:value" pairs)
var formData = [
    {
        type: "calendar", 
        name: "start_date", 
        label: "Start Date", 
        enableTime: true, 
        enableTodayButton: true,
        calendarPosition: "right"
    },
    {type: "calendar", name: "end_date", label: "End Date", dateFormat: "%Y-%m-%d"}
];

Related sample:  dhtmlxCalendar

Checkbox

presents a standard check box

Attributes

checkedbooleandefines whether or not checkbox will be checked initially. The default value is "false"
classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the *position* is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the *position* is set as "absolute"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of DIV where the label is placed (not the font size). The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the *position* is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the *position* is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
listarraydefines the array of nested elements
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left, label-right, label-top or absolute, defines the position of label relative to check box
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to "true" automatically assigns the 'NotEmpty' validation rule to the input
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by button click in browser (meanwhile, item's value can be changed programmatically anytime)
tooltipstringcreates the tooltip for the input label
valuestringthe initial value of item
userdataobjectsets some user data for the input "key:value" pairs)
var formData = [
    {type: "checkbox", label: "Show gutter", checked: true, list:[
        {type:"checkbox", name:"ch1", value:"r1", label:"Line numbers", checked:true},
        {type:"checkbox", name:"ch2", value:"r2", label:"Line selection area", 
            checked:true}
    ]},
    //
    {type "label", label:"Mouse"},
    {type:"checkbox", label:"Drag-n-drop in text area", checked: true},
    {type:"checkbox", label:"Double-click drag joins non-alphanumeric characters", 
        checked: true},
    {type:"checkbox", label:"Quick copy using middle mouse button"},
];

Related sample:  Checkbox/Radio button

Colorpicker

dhtmlxColorPicker integration. A data field with a pop-up colorPicker.

Please note, in order to use the colorpicker item you must include 2 files:

<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlx.css">
<script src="../codebase/dhtmlx.js" type="text/javascript"></script>

Using dhtmlxColorpicker API

To use the dhtmlxColorpicker API for the item, get the colorpicker object as in:

var dhxColorPicker = myForm.getColorPicker("myPicker");
...
dhxColorPicker.hide();

Attributes

classNamestringthe user-defined css class for item
cpPositionstringthe colorpicker's position (right/bottom)
disabledbooleandisables/enables the item
enableCustomColorsbooleansets custom colors (specified in the customColors parameter) for the item. The default value - "false"
customColorsstringa comma-separated list of custom colors that will be used in the colorpicker if the enableCustomColors parameter is set to "true"
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numbersets input height. The default value is "auto"
inputLeftnumberthe left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumberthe top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numbersets input width. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumberthe left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumberthe top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by typing in the input (you are still able to set the value by clicking on the colorpicker icon). Can be used to exclude the possibility of entering incorrect values
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to "true" automatically assigns the 'NotEmpty' validation rule to the input
tooltipstringcreates the tooltip for the input label
validatefunctionpredefined rule or custom function, sets the validation rule. See details in the chapter Validation
valuestringthe initial value of item
userdataobjectsets some user data for the input "key:value" pairs)
var formData = [
    {type: "colorpicker", name: "Color", label: "Color:", value: "#2a87eb", 
        enableCustomColors:"1", customColors:"#ff9f29,#a3ff2b,#57cdff,#fb26ff,#9f96ff"},
    {type: "colorpicker", name: "Background", label: "Background:", value: "#6eea11"}
];

Related sample:  dhtmlxColorPicker

Combo

dhtmlxCombo integration. Presents a normal combo box.

Please note, in order to use the combo item you must include 2 files:

<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlx.css">
<script src="../codebase/dhtmlx.js" type="text/javascript"></script>

Form supports combo nesting, i.e. you can set different items for different options. Subject to the selected option - the appropriate set of items will be shown.

Using dhtmlxCombo API

To use the dhtmlxCombo API for the item, get the combo object as in:

var dhxCombo = myForm.getCombo("myCombo");
...
dhxCombo.attachEvent("onChange", function(){});

Attributes

classNamestringthe user-defined css class for item
connectorurlallows loading select options of the item from database. See details in Combo Specific HowTos.
comboTypestring"checkbox" or "image" - allows adding check boxes or images to combo's items
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the item label (related event - onInfo)
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
filteringbooleanswitches on the filtering mode (when a user starts to type, combo suggests matching search results). The default value is "false"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
optionsobjectspecifies select options of item, parameters:
list - (array) defines the array of nested elements,
selected - (boolean) defines whether the option will be selected initially,
text- (string) the option's text,
value - (string) the option's id
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
readonlybooleantrue/false or 0/1 - specifies whether the value of the item can be changed by button click in browser (meanwhile, the value can be changed programmatically anytime)
requiredbooleanadds the icon after the label marking the field as mandatory. Also, setting the attribute to "true" automatically assigns the 'NotEmpty' validation rule to the field
tooltipstringcreates the tooltip for the item label
validatefunctionpredefined rule or custom function - sets the validation rule. See details in the chapter Validation
valuestringthe initial value of item
userdataobjectsets some user data for the item "key:value" pairs)
var formData = [
    {type: "combo", label: "Format", name: "format", options:[
        {text: "AAC", value: "AAC"},
        {text: "AC3", value: "AC3", selected: true},
        {text: "MP3", value: "MP3"},
        {text: "FLAC", value: "FLAC"}
    ]},
    {type: "combo", label: "Bitrate", name: "a_bitrate", options:[
        {text: "128 kbps", value: "128"},
        {text: "160 kbps", value: "160"},
        {text: "256 kbps", value: "256"},
        {text: "320 kbps", value: "320", selected: true},
        {text: "448 kbps", value: "448"}
    ]},
];

XML format for connector attribute and reloadOptions() method

<complete>
    <option value="value_a">text</option>
    <option value="value_b" selected="true">new text</option>
    ...
</complete>

Related sample:  dhtmlxCombo

Container

presents a simple HTML container where you can place any content

Attributes

classNamestringthe user-defined css class for item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputWidthstring|numberthe width of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
labelstringthe text label of item
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to _true_ automatically assigns the 'NotEmpty' validation rule to the input
stylestringspecifies css style that will be applied to the input
tooltipstringcreates the tooltip for the input label
userdataobjectsets some user data for the input "key:value" pairs)
var formData = [
    {
        type:"container", 
        name:"myGrid", 
        label:"Select Product", 
        inputWidth:330, 
        inputHeight:200
    }
];

Details

The main use case of the control is integration with the DHTMLX components.

  • components are initialized as usual with the only difference is that they use the container control as a DIV container.
  • the getContainer() method returns an HTMLDivElement object of the control.

For example, to integrate dhtmlxGrid with the form:

var formData = [
    {
        type:"container", 
        name: "myGrid",
        label: "Select Product",
        inputWidth: 330,
        inputHeight: 200
    }
];
var myForm = new dhtmlXForm("myForm", formData);
 
grid = new dhtmlXGridObject(myForm.getContainer("myGrid"));

Related events:

  • onEnable - fires when the control is enabled after being disabled
  • onDisable - fires when the control is disabled after being enabled

Related sample:  Attach Grid to Form / Container

Editor

dhtmlxEditor integration. Presents text editor.

Please note, in order to use the editor item you must include 2 files:

<link type="text/css" href="../codebase/dhtmlx.css">
<script src="../codebase/dhtmlx.js" type="text/javascript"></script>

Using dhtmlxEditor API

To use the dhtmlxEditor API for the item, get the editor object as in:

var dhxEditor = myForm.getEditor("myEditor");
...
dhxEditor.alignCenter();

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the item label (related event - onInfo)
inputHeightstring|numbersets the height of input. The default value is auto
inputLeftnumberthe left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumberthe top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numbersets the width of input. The default value is auto
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is auto
labelLeftnumberthe left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumberthe top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is auto
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the field as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the field
tooltipstringcreates the tooltip for the item label
validatefunctionpredefined rule or custom function - sets the validation rule. See details in the chapter Validation
valuestringthe initial value of item
userdataobjectsets some user data for the item ("key:value" pairs)
var formData = [
    {type:'editor', name:'Description', label:'Description:', labelWidth:90, 
      labelLeft:-4, labelTop:112, inputWidth:300, inputLeft:97, inputTop:110,
        position:'absolute', labelAlign:'right', inputHeight:124, value:"Hello,Editor!"}                
];

Creating long editor toolbar

If you want to create a long toolbar for Editor, you need to use 2 more properties:

  • toolbar - (boolean) true/false to enable/disable toolbar
  • iconsPath - (string) path to toolbar icons, they should be placed in the folder with Editor images ("../dhtmlxEditor/codebase/imgs/")

Related sample:  dhtmlxEditor

Fieldset

presents a standard fieldset that allows combining several sense-connected items.

Attributes

classNamestringthe user-defined css class for fieldset's items
disabledbooleandisables/enables the fieldset's items
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
labelstringthe text label of item (legend)
listarraydefines the array of nested elements
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to fieldset. As just labels are defined for fieldset,
widthnumberthe width of fieldset
userdataobjectsets some user data for the item ("key:value" pairs)
var formData = [
    {type: "fieldset",  name: "mydata", label: "Advanced Settings", width:180, list:[
        {type:"settings", position:"label-right"},
        {type: "checkbox", name: "vsync", label: "VSync", checked: "1"},
        {type: "checkbox", name: "mouse_invert", label: "Swap Mouse Buttons"},
        {type:"checkbox", name:"custom_cursor", label:"Custom Mouse Cursor", 
          checked:"0", list:[
            {type:"radio", name:"cursor_value", value:"dot", label:"Dot", checked:"1"},
            {type:"radio", name:"cursor_value", value:"cross",  label:"Cross"},
            {type:"radio", name:"cursor_value", value:"circle", label:"Circle"},
            {type:"radio", name:"cursor_value", value:"triangle", label:"Triangle"}
        ]}
    ]}
];

Related sample:  Fieldset

File

(Deprecated) presents a file upload item.

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
tooltipstringcreates the tooltip for the input label
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type: "file", name: "caret", label: "Preview", position:"label-top"},
    {type: "file", name: "caret", label: "Full-size image", position:"label-top"}
];

How to use

  • Create a real html form (this form should be "around" dhtmlxForm):
<form id="realForm" method="POST" enctype="multipart/form-data">
    <div id="dhxForm">
 
    </div>
</form>
  • Put the dhtmlxForm instance inside the real form, attach a callback to a dhtmlxForm button (or the 'submit' button of the real form) and submit the real form manually:
var formData = [
    {type: "file", name: "my_file", ...},
    {type: "button", name: "upload", value: "Upload"}
];
 
var myForm = new dhtmlXForm("dhxForm", formData);
myForm.attachEvent("onButtonClick", function(id){
    if (id == "upload") {
        document.getElementById("realForm").submit();
    }
});
 
function myCallBack(state, fileName, fileSize) {
    // see below what is this needed for
};
  • Upload files without page reloading:

    • Create a hidden iframe on your page like the one shown below:
<iframe name="upload_area" frameBorder="0" height="0"></iframe>
  • Set the "target" attribute of your real form to the name of the iframe, i.e. "upload_area". In this case, the form will be submitted into the iframe and the page won't be reloaded. The myCallBack() function can be called as in:
<?php
// move_uploaded_file() and other code here
// print result
print_r("<SCRIPT>parent.myCallBack(true, 'filename.rar', '234123')</SCRIPT>");
?>

Hidden

A hidden text field (invisible for users). Presents original input type=hidden.

Attributes

namestringthe identification name. Used for referring to item
valuestringthe initial value of item
userdataobjectsets some user data for the input ("key:value" pairs)

Usage of value is optional, but without this attribute hidden doesn't make any sense.

var formData = [
    {type: "hidden", name:"topField", value:"1"}
];

Image

presents an image with the ability to upload a new one

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of DIV where the label is placed (not the font size). The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
stylestringspecifies css style that will be applied to the input
tooltipstringcreates the tooltip for the input label
valuestringthe initial value of an item
userdataobjectsets some user data for the input "key:value" pairs)
urlstringserver side script (see the details below)
imageWidthnumberthe width of the image (image will be centered within inputWidth)
imageHeightnumberthe height of the image (image will be centered within inputHeight)

To initialize an item as a part of Form, you need to specify at least the type, name and url params (if you omit the name property Form will generate it automatically).

{
    type: "image",      
    name: "user_photo", 
    url:  "some.php",
    imageWidth: 126, 
    imageHeight: 126,
    inputWidth: 130,
    inputHeight: 130
}

Rendering an item

If you set an item value or the whole form data in the following way:

myForm.setItemValue("user_photo", "avatar.jpg");
// or
myForm.setFormData({user_photo: "avatar.jpg"});

The GET request will be performed by Form to get image source from the server:

some.php?action=loadImage&itemId=user_photo&itemValue=avatar.jpg&dhxr1441638923235=1

You can turn off the dhxr param by setting window.dhx.ajax.cache=true (see cache for details).

An example of server response:

if (@$_REQUEST["action"] == "loadImage") {
 
    // load any default image
    $i = "empty_user.jpg";
 
    // check if requested image exists
    $k = "uploaded/".md5($_REQUEST["itemValue"]);
    if (file_exists($k)) $i = $k;
 
    // output image
    header("Content-Type: image/jpg");
    print_r(file_get_contents($i));
 
}

The above code will load a custom image (if it was previously uploaded to server) or just load the default 'empty_user.jpg' image which will notify the user about missing image.

Uploading an image

When the user clicks to upload an image, selects the needed image and presses "open" in the browser dialog box, uploading will start automatically.

The POST request will be performed by the form with the following parameters:

action=uploadImage
itemId=user_photo
file=file data here

The form waits for the following response:

{
    state: true,                // true if the file uploaded successfully
    itemId: 'user_photo',       // item name
    itemValue: 'item_value',    // value to set via setItemValue() after upload
    extra: {any data here}      // optional data for uploading ok/fail events
}

A server side script example:

if (@$_REQUEST["action"] == "uploadImage") {
 
    $k = md5($_FILES["file"]["filename"]);
 
    // make sure you added security checks for $k variable here
    @unlink("uploaded/".$k);
 
    // and here...
    move_uploaded_file($_FILES["file"]["tmp_name"], "uploaded/".$k);
 
    header("Content-Type: text/html; charset=utf-8");
    print_r("{state: true, itemId: '".@$_REQUEST["itemId"]."', itemValue: '".$k."'}");
 
}

After the form got the response, it will call the onImageUploadSuccess or onImageUploadFail events. If the file was uploaded successfully, the form will also update the image by calling the URL with the returned itemValue parameter.

// correctly
myForm.attachEvent("onImageUploadSuccess", function(name, value, extra){
    // your code here
});
 
// fires when an image was uploaded incorrectly
myForm.attachEvent("onImageUploadFail", function(name, extra){
    // your code here
});

Input/Textarea

presents a standard text input field or a textarea. To define textarea, use the attribute rows (see details below).

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - "false" (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center, the alignment of label within the defined width
labelHeightstring|numberthe height of DIV where the label is placed (not the font size). The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
maxLengthnumberthe max number of characters that can be entered in input
namestringthe identification name. Used for referring to item
numberFormatstring|arraysets the format of numeric data (see details below)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
readonlybooleantrue/false or 0/1, specifies whether item's value can be changed by button click in browser (meanwhile, item's value can be changed programmatically anytime).
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to _true_ automatically assigns the 'NotEmpty' validation rule to the input
rowsnumberused to present textarea (instead of a single input) of the specified height see details below)
stylestringspecifies css style that will be applied to the input
tooltipstringcreates the tooltip for the input label
validatefunctionpredefined rule or custom function - sets the validation rule. See details in the chapter (Validation)
valuestringthe initial value of an item
userdataobjectsets some user data for the input "key:value" pairs)
var formData = [
    {type:"input",name:"prj_name",label:"Project Name",value:"Project1",
       tooltip:"Enter Name",required:true, info:true, 
       note:{text:"Enter project name.The fields are required."}},
    {type:"input",name:"prj_descr",label:"Project Description",
       value:"Project is great!", rows:3,
       note:{text:"Describe your project's basic purposes.The fields are optional."}}
];

"textarea" details

Generally, to turn a standard input to textarea you should set attribute rows.

Note, the attribute doesn't specify the number of rows, it specifies the initial height of the control, calculated by the formula: 35px + (rows-1)16px . For example, rows:3 means that the height of your textarea will be 35+216 = 67px.

To set any random value for the height, use rows in pair with attribute style. In this case, rows can be set to any value (but it must be specified anyway!) while the style attribute must specify the desired height.

{type: "input", label: "Details", rows:3, style:"width:200px;height:200px;"}

Number formats

To set format of numeric data you should use the attribute numberFormat.

For JSON data you should use the following syntax:

  • numberFormat: "format";
  • numberFormat: ["format", "groupSep", "decSep"].
    • groupSep - a mark that will be used to divide numbers with many digits into groups. By default - '.' (dot);
    • decSep - a mark that will be used as the decimal delimiter. By default - ',' (comma).
formData = [
   {type:"input", name:"inp1", label:"Format: 0,000.00",  numberFormat:"0,000.00"},
   {type:"input", name:"inp2", label:"Format: @ 0,00",    numberFormat:["@ 0,00",":"]},
   {type:"input", name:"inp3", label:"Format: $ 0.00",    
      numberFormat:["$ 0,000.00",",","."]},
   {type:"input", name:"inp4", label:"Format: 0,000 Rub", 
      numberFormat:["0,000 Rub","'"]}
];

In XML format_ you can use the following attributes:

  • numberFormat="format";
  • groupSep="group_sep";
  • decSep="dec_sep".
<?xml version="1.0" encoding="UTF-8"?>
<items>
   <item type="input" label="Sales" numberFormat="$ 0,000.00" groupSep="'" decSep='.'/>
</items>

Out of the constructor, you can set the format by calling the setNumberFormat() method.

Related sample:  Text/Select/Password

Label

presents a text label.

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
labelstringthe text label of item
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
offsetLeftnumbersets the left relative offset of item
offsetTopnumbersets the top relative offset of item
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type: "label", label: "Caret"},
    {type: "radio", name: "caret", label: "Blinking", checked: true, 
       position:"label-right"},
    {type: "radio", name: "caret", label: "Block", position:"label-right"},
    {type: "radio", name: "caret", label: "Thick", position:"label-right"}
];

Related sample:  Text/Select/Password

Multiselect

presents a multi-select list box.

Attributes

classNamestringthe user-defined css class for item
connectorurlallows to load select options of the item from database. See details (SelectOptionsConnector)
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the *position* is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the *position* is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the *position* is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the *position* is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
optionsobjectspecifies select options of item, parameters:
selected - (boolean) defines whether the option will be selected initially,
text- (string) the option's text,
value - (string) the option's id
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
sizenumbersets the number of lines in the item (the height of the list box)
stylestringspecifies css style of item
tooltipstringcreates the tooltip for the input label
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    { 
      type:"multiselect",
      label:"Can create/edit/delete users:",
      inputHeight:90,
      inputWidth:130,
      options:[
        {text: "Administrators", value: "Option 1", selected: true},
        {text: "Power users", value: "Option 2", selected: true},
        {text: "Registered users", value: "Option 3"},
        {text: "Guests", value: "Option 4"},
        {text: "All users", value: "Option 5"},
    ]}
];

XML format for attribute and reloadOptions() method

<data>
    <item value="value_a" label="text"/>
    <item value="value_b" label="new text" selected="true"/>
    ...
</data>
 
//in case of loading data using 'myForm.load()':
<data>
    <name>value1,value2,valueN</name>
</data>

Details

To validate a multiselect field you should define a custom validation logic. You can't use a standard validation as it works ONLY with string values and the item operates with arrays.

Newcolumn

allows creating a new column of items.

Attributes

offsetnumbersets the distance between columns

Just write

{type:"newcolumn"}

and all further items will be placed into next column. In such way you can create any number of columns.

var formData = [
        {type:"settings", position:"label-right"},
        {type: "label", label: "Content"},
        {type: "checkbox", label: "Block pop-up windows", checked: true},
        {type: "checkbox", label: "Load images automatically", checked: true},
        {type: "checkbox", label: "Enable JavaScript", checked: true},
        {type: "newcolumn", offset:20},
        {type: "label", label: "History"},
        {type: "checkbox", label: "Remember by browsing history", checked: true},
        {type: "checkbox", label: "Remember download history", checked: true},
        {type: "checkbox", label: "Remember search and form history", checked: true}
];

If you had defined "newcolumn" but the items didn't split, please, check the width of your form's container. Most probably, the container doesn't have enough width to place items into 2 columns.

Related sample:  New column

Password

presents a field where all the entered characters are shown as asterisks.

Attributes

classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
maxLengthnumberthe max number of characters that can be entered in input
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by button click in browser (meanwhile, item's value can be changed programmatically anytime)
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
stylestringspecifies css style of item
tooltipstringcreates the tooltip for the input label
validatefunctionpredefined rule or custom function - sets the validation rule. See details in the chapter Validation
valuestringthe initial value of item
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type: "settings", position: "label-left", labelWidth: 120, inputWidth: 120},
    //
    {type: "input", label: "Name", value: "John Smith"},
    {type: "password", label: "Password", value: "123"},
    {type: "select", label: "Session", options:[
        {value: "1", text: "Administration"},
        {value: "2", text: "Design"},
        {value: "3", text: "Manage Articles"}
    ]}
];

Related sample:  Text/Select/Password

Radio

presents a standard radio button.

Attributes

checkedbooleandefines whether or not radio button will be checked initially. The default value is false
classNamestringthe user-defined css class for item
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputLeftnumbersets the left absolute offset of radio button. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of radio button. The attribute is applied only if the "position" is set as "absolute"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
listarraydefines the array of nested elements
namestringthe identification name. Used for referring to item. Specify the same "name" attribute to identify group of buttons in which just one radio button can be selected at the same time
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to radio button
readonlybooleantrue/false or 0/1 - specifies whether item's value can be changed by button click in browser (meanwhile, item's value can be changed programmatically anytime)
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
tooltipstringcreates the tooltip for the input label
valuestringthe value of a radio button ( the identification name of a certain radio button in a group of buttons with the same "name" parameter)
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type:"radio", name:"font", value:"by_pages", label:"Use fonts defined by pages",
      checked:true, readonly:true},
    {type: "radio", name: "font", value: "custom", label: "Use custom font", list:[
        {type:"select", label:"Default Font", position:"label-left", 
           labelWidth:"auto", inputWidth:"auto", options:[
            {value: "1", text: "Georgia"},
            {value: "2", text: "Sans"},
            {value: "3", text: "Tahoma", selected: true},
            {value: "4", text: "Trebuchet MS"},
            {value: "5", text: "Verdana"}
        ]},
        {type: "newcolumn"},
        {type: "select", label: "Size", position: "label-left", labelWidth: "auto", 
          inputWidth: "auto", options:[
            {value: "8", text: "8"},
            {value: "9", text: "9"},
            {value: "10", text: "10"},
            {value: "11", text: "11"},
            {value: "12", text: "12"},
            {value: "13", text: "13"},
            {value: "14", text: "14", selected: true},
            {value: "15", text: "15"},
            {value: "16", text: "16"}
        ]}
    ]},
];

Related sample:  Checkbox/Radio button

Select

presents a dropdown list.

Form supports select nesting, i.e. you can set different items for different options. Subject to the selected option - the appropriate set of items will be shown.

Attributes

classNamestringthe user-defined css class for item
connectorurlallows to load select options of the item from database. See details (SelectOptionsConnector)
disabledbooleandisables/enables the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
infobooleanadds the icon after the input label (related event - onInfo)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input. The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft, right or center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
optionsobjectspecifies select options of item, parameters:
list - (array) defines the array of nested elements,
selected - (boolean) defines whether the option will be selected initially,
text- (string) the option's text,
value - (string) the option's id
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
stylestringspecifies css style of item
tooltipstringcreates the tooltip for the input label
userdataobjectsets some user data for the input ("key:value" pairs)
var formData = [
    {type:"radio", name:"type", label:"Guest login", labelWidth:"auto", 
      position:"label-right", 
      list:[
        {type: "select", label: "Account type", options:[
            {text: "Admin", value: "admin"},
            {text: "Organizer", value: "org"},
            {text: "Power User", value: "poweruser"},
            {text: "User", value: "user"}
        ]},
        {type: "checkbox", label: "Show logs window"}
    ]},
    {type: "button", value: "Proceed"}
];

XML format for attribute and reloadOptions() method

<data>
    <item value="value_a" label="text"/>
    <item value="value_b" label="new text" selected="true"/>
    ...
</data>

Related sample:  Text/Select/Password

Settings

allows overriding some default form settings for items (placed at the beginning of data block).

For example, attribute position. You'd like to place labels of several items to left. You can specify position:"label-left" for each item or just put this stuff into settings item once.

In case you specify the same attribute in settings and item: setting's value will be ignored.

Attributes

blockOffsetnumberthe offset of the item content. For the Block only
inputHeightstring|numbersets the height of input. The default value is "auto"
inputWidthstring|numbersets the width of input. The default value is "auto"
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numbersets the height of label. The default value is "auto"
labelWidthstring|numbersets the width of label. The default value is "auto"
noteWidthstring|numbersets the width of the details block (which is placed under the input)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
var formData = [
    {type:"settings",position:"label-left",labelWidth:120,inputWidth:120,
       labelAlign:"right"},
    {type: "input", label: "Name", value: "John Smith", labelAlign: "left"},
    {type: "password", label: "Password", value: "123", labelAlign: "center"},
    {type: "select", label: "Session", options:[
        {value: "1", text: "Administration"},
        {value: "2", text: "Design"},
        {value: "3", text: "Manage Articles"}
    ]}
];

Related sample:  Settings

Template

allows setting any template to item. It can be some link, some text, another item, etc. Template is specified by the parameter format where you define the appropriate template handler.

Attributes

classNamestringthe user-defined css class for item
infobooleanadds the icon after the input label (related event - onInfo)
formatfunctiondefines template handler. This function should return value (formatted by user) which will be inserted instead of input. Gets parameters - "name", "value"
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
inputHeightstring|numberthe height of input. The default value is "auto"
inputLeftnumbersets the left absolute offset of input.The attribute is applied only if the "position" is set as "absolute"
inputTopnumbersets the top absolute offset of input.The attribute is applied only if the "position" is set as "absolute"
inputWidthstring|numberthe width of input. The default value is "auto"
labelstringthe text label of item
labelAlignstringleft/right/center - the alignment of label within the defined width
labelHeightstring|numberthe height of label. The default value is "auto"
labelLeftnumbersets the left absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelTopnumbersets the top absolute offset of label. The attribute is applied only if the "position" is set as "absolute"
labelWidthstring|numberthe width of label. The default value is "auto"
namestringthe identification name. Used for referring to item
noteobjectcreates the details block which is placed under the input, parameters:
text- (string) the note's text,
width - (number) the note area's width (get from input by default)
offsetLeftnumbersets the left relative offset of item (both input and label)
offsetTopnumbersets the top relative offset of item (both input and label)
positionstringlabel-left/label-right/label-top/absolute - defines the position of label relative to input
requiredbooleanadds the icon after the label marking the input as mandatory. Also, setting the attribute to true automatically assigns the 'NotEmpty' validation rule to the input
stylestringspecifies css style of item
tooltipstringcreates the tooltip for the input label
valuestringthe initial value of item
userdataobjectsets some user data for the input ("key:value" pairs)
function doLink(name, value) {
    var f = this.getForm();
    return '<a href="script/do_edit.php?id='+value+'&t=abc">hello</a>';
}
var formData = [
    {type: "checkbox", label: "Accept cookies from sites", checked: true, list:[
        {type:"checkbox", label:"Accept third-party cookies", checked: true},
        {type:"select", label:"Keep until", inputWidth:"auto", position:"label-left", 
          options:[
            {value: "1", text: "they expire", selected: true},
            {value: "2", text: "I close Firefox"},
            {value: "3", text: "ask me every time"}
        ]},
        {type:"template",name:"a",label:"Today:",value:"Hello",position:"label-left",
          format:doLink}
    ]}
]

Related sample:  Template

Upload

An item that allows uploading multiple files and tracking the progress of individual file upload.

You can find specific methods and events of the Uploader control in the dhtmlXFileUploader API.

Attributes

Common attributes:

classNamestringthe user-defined css class for the item
hiddenbooleanhides/shows the item. The default value - false (the item is shown)
namestringthe identification name. Used for referring to the item
inputHeightstring|numberthe height of the item. The default value is "auto"
inputWidthstring|numberthe width of the item. The default value is "auto"
offsetLeftnumbersets the left relative offset of the item
offsetTopnumbersets the top relative offset of the item
disabledbooleandisables/enables the item. The default value - false
userdataobjectsets some user data for the item ("key:value" pairs)

Uploader-related attributes:

modestringhtml5, html4, flash, sl - allows you to manually set the mode in use. Beware, once you set the mode manually, the control will work in this mode permanently independent of the browser you use
titleScreenbooleandefines whether the initial screen (when no files are selected) must be displayed. The default value - true
titleTextstringthe text of the initial screen. The default value - "Drag-n-Drop files here or click to select files for upload"
autoStartbooleandefines whether files must be immediately loaded after selecting. The default value - false
autoRemovebooleandefines whether files must be removed from the item after complete downloading. The default value - false

URL attributes:

urlstringthe path to the server-side script (relative to the index file) which will parse the requests received from the uploader. Used in the html5/html4 modes
swfPathstringthe path to the uploader.swf file
swfUrlstringthe path to the server script file (relative to the client flash script file) which will parse the requests. Used in the flash mode

Silverlight-related attributes:

slXapstringthe path to the dhxupload.xap file (full path is required, i.e. including http://host..)
slUrlstringthe full path to the server script file

Controls

Details

The control can work in 4 modes:

  1. html5 (multiple files selecting, tracking the progress, loading by Ajax, d-n-d for selecting files, IE10, IE11, FF, Opera, Chrome)
  2. flash (multiple files selecting, tracking the progress, loading by Flash, any browser with flash installed)
  3. html4 (works as a standard HTML input upload control, IE6-IE9)
  4. sl (based on the Silverlight engine, experimental mode, IE)

By default, the item uses the html5 mode, then flash if html5 isn't supported. If both html5 and flash aren't supported - html4.
The sl mode can be invoked just manually.

How does the control work?

To provide the loading, the control uses a script that gets files to load. The same script is used in all modes but with slight differences.

Let's assume you have the folders tree as in:

where

  • samples/07_uploader/01_basic_init.html - the index file (currently selected).
  • samples/07_uploader/php/dhtmlxform_item_upload.php - the server script we use.

To understand how the control saves files on the server side, please check the 'dhtmlxform_item_upload.php' file in the dhtmlxForm package (resided in the directory: dhtmlxForm\samples\07_uploader\php\ )

html5/html4 modes

For html5/html4 modes it's quite enough to set the url parameter:

  • url - the path to the server script file "dhtmlxform_item_upload.php" relative to the index file "01_basic_init.html", in our case the path will be "php/dhtmlxform_item_upload.php"

flash mode

For the flash mode you must specify 2 parameters: swfPath, swfUrl

  • swfPath - the path to the client flash script file "uploader.swf" relative to the index file "01_basic_init.html", in our case the path will be "../../codebase/ext/uploader.swf"
  • swfUrl - the path to the server script file "dhtmlxform_item_upload.php" relative to the client flash script file "uploader.swf", in our case the path will be "../../samples/07_uploader/php/dhtmlxform_item_upload.php"

To provide correct running in all browsers you need to specify 3 parameters at a time.

formdata = [{
    type: "upload",
    name: "myFiles",
    url: "php/dhtmlxform_item_upload.php",
    swfPath: "../../codebase/ext/uploader.swf",
    swfUrl: "../../samples/07_uploader/php/dhtmlxform_item_upload.php"
}]

"sl" mode (loading with Silverlight)

Note, it's an experimental mode.

For the sl mode you can specify the next parameters:

  • slXap - the path to the client script file "dhxupload.xap" relative to the index file "01_basic_init.html", in our case the path will be "../../codebase/ext/dhxupload.xap";
  • slUrl - the full path to the server script file "dhtmlxform_item_upload.php".
formData = [{
   type: "upload",
   name: "myFiles",
   mode: "sl", // enables the sl mode
   url: "dhtmlxform_item_upload.php",
   slXap: "../../codebase/ext/dhxupload.xap",
   // FULL path is required
   slUrl:"http://localhost/dhtmlx/dhtmlxForm/samples/07_uploader/php/dhtmlxform_item_upload.php", 
}];

Related samples: folder "samples/07_uploader"

Please, make sure that for the 'html4' mode you set the response content type to "text/html", while for the other modes - to "text/json" .

The difference between file uploader and dhtmlxVault

We have a more powerful version of file uploader - Vault. It has a more advanced functionality:

  • the ability to drop custom object (see addDraggableNode and removeDraggableNode) (PRO version)
  • the ability to load the list of previously uploaded files from the server (see load)
  • the ability to add a custom file record into the vault's files area (see addFileRecord)
  • the ability to disable multiple file selection for Flash and html5 modes
  • integration with other DHTMLX components (like windows, layout)
  • dhtmlxVault allows you to control files that will be uploaded to the server. You can manage the allowable files' extensions, the maximum size of a file, the total allowable size of uploaded files and so on.
  • bootstrap skin
Back to top