Skip to content

Latest commit

 

History

History
110 lines (90 loc) · 4.52 KB

autocomplete.md

File metadata and controls

110 lines (90 loc) · 4.52 KB
Raw

Forms: Autocomplete

UI component for autocomplete to use in forms

They are located in toolkit bundle, that can be included like so:

<use:bundle path="toolkit:bundle"/>

This is also automatically included when using

<use:bundle path="keeper:bundle"/>

See Usage Samples in demo repository

Usage

<form:autocomplete
    name="userId2"
    label="Simple Autocomplete"
    value="1"
>
    <script role="sf-options" type="application/json">
        {
            "url": "/keeper/users/list",
            "searchKey": "firstName",
            "valueKey": "id"
        }
    </script>
</form:autocomplete>

Simple Autocomplete

Autocomplete uses same API as DataGrids. Autocomplete by default only operates values, not labels, so in pre-population phase it will make request to server to fetch current labels. I.e. sample above will make a request with filter[id][]=1 body to keeper/users/list URL on load.

To handle comma separated values on backend, implement a value accessor

form:autocomplete

There are 2 blocks of parameters you can specify. Most used ones can be specified directly inside xhtml tag, however more advanced parameters are defined in JSON block

Basic params

<form:autocomplete
    name="userId2"
    label="Simple Autocomplete"
    value="1"
    url="/keeper/users/list"
></form:autocomplete>
Parameter Required Default Description
url yes - Url that implements DataGrid API
name yes - Field name to use
placeholder no - Placeholder for input
disabled no - Render input as disabled
value no - Provide pre-populated value of autocomplete
labelValue no - Provide pre-populated label of autocomplete. If specified autocomplete will not try to resolve "value" from server.
preserve-id no - Don't erase selected id when user types after autocomplete select happens, only for single choice autocompletes

Extended params

Extended params allow to specify templates and customize mapping for API

<form:autocomplete
    name="userId2"
    label="Simple Autocomplete"
    value="1"
>
    <script role="sf-options" type="application/json">
        {
            "url": "/keeper/users/list",
            "searchKey": "firstName",
            "valueKey": "id"
        }
    </script>
</form:autocomplete>
Parameter Required Default Description
id no - Id to use for input
url yes - Url that implements DataGrid API
method no POST POST or GET
headers no {} Headers to send
name yes - Field name to use
isMultiple no false Allow multiple selections
preserveId no - Don't erase selected id when user types after autocomplete select happens, only for single choice autocompletes
data no - If specified, can operate as server-less autocomplete with data pre-defined. Accepts array of strings or IAutocompleteStaticDataItem array
inputTemplate no - handlebars template to customize what will display in input. Accepts row data item as variables available in template.
suggestTemplate no - handlebars template to customize what will display in suggestions. Accepts row data item as variables available in template.
loadingTemplate no - handlebars template to customize what will display during loading.
valueKey no 'id' Field that will be used as value
searchKey no 'name' Field that will be used as label
dataField no 'data' Field that will be used as data list field from response
separator no ',' Separator that will be used for separating values in multi-select
debounce no 0 Debounce value to throttle search events
exposeLabelAs no - If specified, label will have a separate input that also will be submittted with a form
exposeLabelAsRequired no false If specified, exposed label will be rendered with "required" attribute
initialDataItems no - If specified will be used as replacement for value + valueLabel. Can contain multiple values, so can be used for pre-populating multiselect inputs. Should be a IAutocompleteDataItem array

For demo of usages refer to Usage Samples