Suggest List

API Reference

Overview

Suggest is a list of options for input controls that aids form filling by suggesting the necessary value on the base of already typed text. It is based on Webix list component.

Related sample:  Suggest List for Input: Populating with Server-side Data

Suggest list can be used with the following components (should be configured separately):

  • standard HTML input;
  • Webix JS text field;
  • text editor within a component item.

Suggest list is already implemented in the following Webix components (but can be customized):

How does it work?

A popup window with a suggest list control appears each time you try to enter a value into the control or editor:

  • when you type something into an HTML input or Webix text and combo control.
  • when you click the richselect control;

Suggest list and Text input

When suggest list is combined with text control (editor) or HTML input its values are automatically filtered according to the letters you have already typed. You can select an item from the list to fill the input or ignore the suggest list and type you own text.

Suggest list and Combo

When suggest list is combined with combo control (editor) its values are automatically filtered according to the letters you have already typed. You can either select an option from the list or type the text to match any of the options. You cannot ignore the suggest list and enter you own text.

Suggest list and Richselect

When suggest list is combined with richselect control (editor) a popup appears the moment you click its non-editable input. You must obligatory choose some value from the list.

Suggest list values can be stored

  • on client side;
  • on server side.

Default timeout between key pressing and filtering equals to 1 ms, still it can be modified by the dedicated property.

{
    view:"suggest",
    data:[..] //or url:"some.php",
    keyPressTimeout:100ms
}

Initialization

Suggest list can be initialized as:

1 . Separate view attached to an input with the help of the input property that points to the input's ID:

webix.ui({
    view: "suggest",
    input: "country4", // will be linked to 'country4' input
    data: [
        {id:1, value: "Albania"},
        {id:2, value: "Bhutan"},
    ... //list of suggest values can be as long as you wish
    ]
});
 
<input type="text" id="country4" value="Sweden" />

2 . The same-name property of JS text input, combo and richselect:

{view:"text", name:"country", label:"Country", value:"Belarus", suggest:[
        {id:1, value: "Albania"},
        {id:2, value: "Bhutan"},
        ...]
}

3 . The same-name property of JS combo and richselect and take the extensive configuration:

webix.ui({
    view:"richselect", suggest:{
        data:[
            {id:1, value:"One"},
            {id:2, value:"Two"} //options list
        ],
        ready: function(){
            // defines the initially visible option
            $$("richselect_1").setValue(this.getFirstId()); 
        }
    }
});

Related sample:  Suggest for richselect and combo

Note that you must select any value from a suggest list, since it's required by combo and richselect nature.

Loading data to Suggest list

Normally, a dataset for suggest items contains an array of objects, each of which may have the following properties:

  • id - item ID (if not set, will be generated automatically);
  • value - the property to display in suggest items (if another template is not set);
  • $empty - indicates that an item contains not data (blank item);
  • any other properties.

Suggest list with client-side data

On the client side the list with suggestions can be stored in any of supported formats. It may be put directly into data property (as shown above) or in a variable declared beforehand.

Suggest List with JSON data

var countries = [
    {id:1, value: "Albania"},
    {id:2, value: "Bhutan"}
];
 
{ 
    view:"text", 
    label:"Country", 
    value:"Belarus", 
    suggest:countries
}

Related sample:  Suggest List for Input: Populating with Client-side Data

Suggest list with server-side data

At the same time, data can come from the server side. All you need is to specify the script file that will get the data from the database.

As a value of the dataFeed property of the Suggest component

webix.ui({
    view: "suggest",
    input: document.getElementById("country4"),
    body:{ 
        dataFeed:"server/data.php" 
    }   
});

As a value of the suggest property

{ 
    view:"text", 
    name:"country", 
    label:"Country", 
    value:"Albania", 
    suggest:"server/data.php"
}

Related sample:  Suggest List for Input: Populating with Server-side Data

Suggest list is connected with an input field by suggest property included into the text constructor.

Suggest list for component editors

Component editors duplicate editing controls yet they are initialized within the component body.

Suggest can be initialized for combo and text editors. To do this, make the following steps:

  • create a suggest list as separate view or define its configuration in a JSON object and set options for it:
  • create a component, specify text editor type for it and link to the suggest:
var year_suggest_a = webix.ui({
    view: "suggest",
    data:[...]
});
 
//or
var year_suggest_a = {
    view: "suggest",
    data:[...]
};
 
webix.ui({
    view:"datatable",
    columns:[  
        {id:"year", editor:"text", suggest:year_suggest_a}
    ]
});

Related sample:  Datatable: Autosuggest

At the same time, you can provide all the logic by API, which allows customizing suggest behavior:

  • create a suggest list as separate view and set options for it:
  • link suggest list to the input field of the editor object with the linkInput method:
  • provide handlers for edit events.
var year_suggest_b = webix.ui({
    view: "suggest",
    data:[...]
});
 
var gridb = webix.ui({
    view:"datatable",
    columns:[  
        {id:"year", editor:"text"}
    ]
});
 
 
gridb.attachEvent("onAfterEditStart", function(object){
    if (object.column == "year") { //only for editors in this column
        var editor = this.getEditor(object);
        year_suggest_b.linkInput(editor.getInput());
    }
});
 
gridb.attachEvent("onAfterEditStop", function(object){
    year_suggest_b.hide();
});

Related sample:  Datatable: Autosuggest

Suggest list can as well be attached to combo and richselect editors, yet then it loses its status of 'adviser' and selection from it becomes compulsory.

webix.ui({
    view:"datatable",
    columns:[  
        {id:"year", editor:"combo", suggest:{
            data:[...], //or url:""
            on:{
                //events            
            }
        }}
    ]
});

Related sample:  Datatable: Advanced Combo Editor

Customizing suggest list

Suggest list allows defining lots of custom settings in case of a long initialization pattern.

It works for a suggest defined as a standalone view:

{view:"suggest",
    //popup settings
    ...,
    body:{
        //list settings 
    }
}}

As well as for a suggest defined as a control/editor property:

{view:"combo", options:{
    //popup settings
    ...,
    body:{
        //list settings 
    }
}}

Note that an suggest list configuration can be set via either suggest or options property for richselect, combo, multiselect and multicombo controls.

Where can the customization be useful?

Sizing and positioning

Popup height

Suggest list is tuned to show maximum 10 items at a time. If there are more items, a scrollbar appears. If there are fewer item in the list, its height shrinks.

The number of items in the suggest list can be controlled by an yCount property of list object:

{view:"combo", suggest: { 
    body:{
        yCount:5,
        data:[...] 
    }
}}

Popup width

By default, a popup is adjusted to the width of a master control. To change it, set fitMaster property to false and define any desirable width or use the default 300px:

{view:"combo", suggest: { 
    fitMaster:false,
    width:400,
    data:[...] 
}}

Popup position

Suggest API offers the following variants of popup positioning in relation to the text field it's initialized for:

  • "bottom" (default). Doesn't require direct initialization;
  • "top";
  • "left";
  • "right".

Since we speak here about relative position, the property to set it has the same name:

{ view:"text", suggest:{ data:countries, relative:"left" }}

Related sample:  Attaching Suggest List to Input

Advanced suggest lists

The functionality is available in Webix Pro edition only.

Webix offers advanced suggest controls for extra functionality and greater visual effect:

  • CheckSuggest - a suggest control based on Webix List. Features checkboxes that enable multiple choice;
  • MultiSuggest - a suggest control based on Webix List with the ability to select multiple items at a time;
  • GridSuggest - a suggest control based on Webix DataTable;
  • DataSuggest - a suggest control based on Webix DataView;
  • DateRangeSuggest - a suggest control based on Webix DateRangePicker.

CheckSuggest

CheckSuggest control is used in a number of PRO controls. You can find its implementations in:

MultiSuggest

MultiSuggest control is used in the multiselect component editor.

If needed, it can substitute CheckSuggest for the above-mentioned use cases. See Advanced Configuration of Popup Selectors for details.

GridSuggest

Related sample:  Grid Suggest

GridSuggest can be used with form controls as well as with component editors. More about its configuration can be found in the related article.

DataSuggest

Related sample:  Data Suggest

DataSuggest can be used with form controls as well as with component editors. More about its configuration can be found in the related article.

DateRangeSuggest

Related sample:  DateRange Picker

DateRangeSuggest control is used in the DateRangePicker widget. More details are given in the related section.

Back to top