Skip to main content

Configuration

Arrow keys navigation#

The List component provides the possibility to navigate its items with arrow keys. You can enable this functionality using the keyNavigation property:

var list = new dhx.List("list", {keyNavigation:true});

As a value of this option you can use either true/false to switch it on/off, or specify a function that will define some custom navigation logic.

Default shortcut keys#

ArrowUpto move focus to the previous item
ArrowDownto move focus to the next item
Enter/Shift+Enter/Ctrl+Enterto add selection to a List item in focus
Ctrl+Ato select all items at once (when the "multiselection" property is enabled)

Drag-n-drop of items#

dhtmlxList supports drag-n-drop of items between lists in several modes. To begin with, you should specify the dragMode property in the configuration object of List. Then define which mode you need:

  • "target" - a list takes items from other lists, while its items can't be dragged out of it
  • "source" - a list allows dragging its items out and can't take items from other lists
  • "both" - a list both takes items from other lists and allows dragging its items out as well
var list = new dhx.List("list_container", {     dragMode:"source"});

In order to provide the possiblity of dragging several items between lists, you should enable the multiselection in addition to the dragMode:

var list = new dhx.List("list_container", {     dragMode:"source",    multiselection:true});

Read more about multiselection in List below.

Related sample: List. Setup Drag Mode

Dynamic rendering of items#

All data is loaded into List and rendered at once. In case you use large amounts of data in the list, it may slow down the work of your app.

There is a possibility to increase the speed of your application containing a List by enabling dynamic data rendering. It presupposes that data is rendered by parts and on demand. To make use of dynamic data rendering, switch the virtual property on.

var list = new dhx.List("list_container", {     virtual:true});

Related sample: List. Virtual List

Editing items#

Related sample: List. Editable List

You can enable the possibility to edit List items with the help of the editable configuration option:

var list = new dhx.List("list_container", {editable:true});

Height of an item#

Related sample: List. Setup List Item Height

You can specify the necessary height of an item and set it before initialization of List via the itemHeight property either as a number:

// sets the height of an item as a numbervar list = new dhx.List("list_container", {     itemHeight:30 /*!*/});

or as a string value

// sets the height of an item as a string valuevar list = new dhx.List("list_container", {     itemHeight:"30px" /*!*/});
note

The usage of the CSS calc() function within the itemHeight property is not possible.

When the virtual property is set to true, the default height of a list item is 37. To change this value, make use of the itemHeight property, as described above.

Height of the List#

Related sample: List. Setup List Height

You can define the desired height of a list via the height configuration option as easy as that:

var list = new dhx.List("list", {height: 700});

You can also use a string value for setting the height of List:

var list = new dhx.List("list", {height: "700px"});
note

The usage of the CSS calc() function within the height property is not possible.

Multiple selection of items#

Related sample: List. List Multiselection

By default, you can select only one item in a list, since selection of another item resets selection of the previous one. To enable the possibility to select several List items, make use of the multiselection configuration option:

var list = new dhx.List("list", {multiselection:true});

Setting the multiselection property to true presupposes selection of multiple items by using Ctrl key. It is also possible to use the "Ctrl+click" combination to select several items. For this, you need to set the multiselection configuration option to "ctrlClick":

var list = new dhx.List("list", {    multiselection:"ctrlClick"   });

Selection of items#

Related sample: List. Disable Selection

The default configuration of List provides you with the selection feature that allows highlighting a List item. To disable selection in a List you need to set the selection configuration property to false:

var list = new dhx.List("list_container", {selection: false});

Template for List items#

Related sample: List. Add Template To List Item

You can define a template for rendering items in a List with the help of the template configuration property. Set as its value a function that takes one parameter:

  • item - (object) an object of a data item

var list = new dhx.List("list", {    css: "dhx_widget--bordered",     template: function(item) {        var template = "<div className='list_item'>";        template += "<div className='item_name'>"+item.value;                        template+="<span className='item_author'> by "        template += item.authors.filter(function(item){return item}).join(", ");        template += item.publishedDate ? ", "         template += new Date(item.publishedDate.$date).getFullYear() : "";        template += "</span>";        template += "</div>";                        template += "<div className='item_categories'>"+item.categories.join(", ")+"</div>";        template += "</div>";        return template;    },    itemHeight: 72});

Event handlers for the template#

Starting from v7.0, it is possible to assign event handlers to HTML elements of a custom template of List items by using the eventHandlers configuration option:

function template(item) {    let template = "<div className='list_item'>";    template += "<div className='item_name'>"+item.value;    template +="<span className='item_author'> by "    template += item.authors.filter(function(item){return item}).join(", ");    template += item.publishedDate ? ", "     template += new Date(item.publishedDate.$date).getFullYear() : "";    template += "</span>";    template += "</div>";    template += "<span className='item_categories'>"+item.categories.join(", ")+"</span>";    template += "</div>";    return template;}
const list = new dhx.List("list", {    css: "dhx_widget--bordered",    template: template,    eventHandlers: { /*!*/        onclick: { /*!*/            list_item: function(event) { /*!*/                display("You clicked on " + event.target.tagName); /*!*/            }, /*!*/        }, /*!*/        onmouseover: { /*!*/            list_item: function(event, id) { /*!*/                display(list.data.getItem(id).value); /*!*/            }, /*!*/        } /*!*/    } /*!*/});

Related sample: List. Handling Events In Template

The eventHandlers object includes a set of key:value pairs, where:

key the name of the event. Note, that at the beginning of the event name the 'on' prefix is used (onclick, onmouseover).
valuean object that contains a key:value pair, where key is the css class name that the handler will be applied to and value is a function that takes two parameters:
  • event - an event object
  • id - the id of a List item