Skip to main content
Version: Upcoming 🦄

ComboBox

The values of the control "ComboBox" can be provided as static datasource (data formatted like a Json Array inside your template) or in case of a external datasource e.g. by referencing a SharePoint list by linking to the URL or by providing a oData source.

static datasource:

<div
    id="technician"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'Technician',
        required: true,
        dataSource: [
            { name: 'Bauer, F', code: 'Bauer, F' },
            { name: 'Gruber, P', code: 'Gruber, P' },
            { name: 'Lanner, G', code: 'Lanner, G' },
            { name: 'Simon, R', code: '3521' },
            { name: 'Herbert, W', code: '123456789012' }
        ],
        dataTextField: 'name',
        dataValueField: 'code'
    }"
></div>

external datasource (URL):

<div
    id="tab1_combobox_liste"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'ComboBox (HFSql Catalogs)',
        list: true,
        minLength: 3,
        url: '/api/catalogs/CatalogName?$select=Title,KatalogText,PLZ,Postort&amp;%24orderby=Title,PLZ&amp;%24top=1000',
        template: HFFormdefinition.Namespace.setStreetTemplate,
        dataTextField: 'KatalogText',
        dataValueField: 'Title'
    }"
></div>

multilingual external datasource (URL):

<div
    id="tab1_combobox_liste"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'ComboBox (HFSql Catalogs)',
        list: true,
        minLength: 3,
        template: HFFormdefinition.Namespace.setStreetTemplate,
        url: '/api/catalogs/Items?$select=Title,KatalogText,Streetname,Strassenname&amp;%24orderby=Title,PLZ&amp;%24top=1000',
        i18nDataTextField: {
            en: 'Streetname', 
            de: 'Strassenname',
            default: 'Streetname'
        },
        dataValueField: 'Title'
    }"
></div>

external datasource (oData):

<div
    id="liveOdataSource"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'Combobox with live OData source', 
        required: true, 
        dataTextField: 'KatalogText',
        dataValueField: 'Title', 
        autoBind: false,
        dataSource: {
            type: 'odata',
            transport: {
                read: {
                    url:'https://example.com/liveOdataSource/?select=Title,KatalogText&orderby=KatalogText',
                    dataType: 'json',
                    headers: {
                        'Accept': 'application/json;odata=verbose'
                    }
                }
            }
        }
    }"
></div>

FormControl Options​

Options of the kendo component are also available. read more

dataTextField - required​

Define the text of the key-value pair.
How to use:
dataTextField: 'name'
Type: string

dataValueField - required​

Define the value of the key-value pair.
How to use:
dataValueField: 'code'
Type: string

anytext​

Set "false" whenever free text input should be prevented.
How to use:
anytext: false
Type: boolean
Default: true

checkValueInitially​

Stored values gets initially checked if they are contained in the data source that is defined on the control. In certain scenarios this is not desireable.
How to use:
checkValueInitially: true
Type: boolean
Default: true

dataSource​

Provide the data for the drop down selection formatted like a Json Array inside your template.
How to use:
dataSource: [{name: 'Bauer, F', code: 'Bauer, F'}, {name: 'Gruber, P', code: 'Gruber,P'}]
Type: json pseudo array

defaultValue​

Define the value selected in newly created Forms. Note: This must be the appropiate dataValueField value. A Custom Code function can be used to set defaultValue.
How to use:
defaultValue: 'Title1',
Type: string | function
Signature: function() => string

disabled​

Set "true" whenever the ComboBox should be disabled.
How to use:
disabled: true
Type: boolean

doNotCopy​

Set "true" whenever the field should be cleared if the Form is copied.
How to use:
doNotCopy: true
Type: boolean

filterItems​

Define the filtering options for the DropDownList. Can be used to search the list in more than one datasource column. A field entry is required. The operator's default entry is contains. More infos
How to use:
[{ field: 'name', operator: 'contains' }, { field: 'address' }]
Type: { field: string; operator?: string; }[]

formControlMapping​

Define a mapping object to copy fields from the selected dataItem to given Form Controls. More infos
How to use:
{ example_id: 'example_key' }
Type: IFormControlMapping

hidden​

Hide FormControl in Form.
How to use:
hidden: true
Type: boolean

highlightTemplate​

Define the highlight format for filtered results of the ComboBox popup. Accepts a Kendo Template. Important: Kendo Templates use highlight as default placeholder for the highlighted text.
How to use:
highlightTemplate: '<strong>#: highlight #</strong>'
Type: string

i18nDataTextField​

Use the i18nDataTextfield instead of the dataTextfield to use multilingual catalogs in addition to the translation.json file.
How to use:
{ en: 'Streetname', de: 'PLZ', default: ‘Streetname' }
Type: { default: string, [langCode: string]: string }

itemTemplate​

Define the formatting of the ComboBox values for display e.g. combining one or more columns of the datasource for single selection. Accepts a Kendo Template or a function returning a string. Important: Have to return string inside a wrapping element. Unless template option, itemTemplate keeps the original filter highlighting.
How to use:
itemTemplate: '<span>#: entry1 # - #: entry2 #</span>'
Type: string | function
Signature: function(item: any) => string

label​

Define a label for your control element.
How to use:
label: 'Technician'
Type: string

list​

Set this property to "true" if data connected with this control should be a sorting/filtering/grouping option on the ListPage, is used in template objects (eg. the listTemplate) or it should show up in Admin UI listings.
How to use:
list: true
Type: boolean

listOptions​

Set additional options for controls with list equals true. E.g. set custom label for filter/sort/group dialogs or hide them completely.
How to use:
listOptions: {...}
Type: { dialogText: string, dialogHide: boolean }

minLength​

The minimum number of characters the user needs to type before a search is performed. Set a higher value than 1 whenever the search could match a lot of items.
How to use:
minLength: 3
Type: number

onChanged​

Call a pre-defined JS-method to do something when the status of the control changes.
How to use:
onChanged: HFFormdefinition.Namespace.Method
Type: function
Signature: function(data: { value: string, text: string }) => void

paging​

Enable virtualization for the ComboBox. This is useful for large data sets. The ComboBox will only load the items that are currently visible in the viewport. This improves performance and reduces memory usage.
How to use:
paging: true
Type: boolean

pagingItemHeight​

The height of each item in the virtualized list of the ComboBox. This is used to calculate the number of items that can be displayed in the viewport. The default value is 34.
How to use:
pagingItemHeight: 40
Type: number

persistent​

It is the value where the "user" sets the initial selected value of the ComboBox to the value of the previous Form Item of the current user and overwrites any defaultValue.
How to use:
persistent: 'user'
Type: 'user'

placeholder​

Define a placeholder text for the ComboBox.
How to use:
placeholder: 'Please select ...'
Type: string

required​

Set "true" if the control has to be filled in.
How to use:
required: true
Type: boolean

tooltip​

Write a comment to provide further information about the field. A question mark will then be shown within the label and with a click/tap on it, the information will occur.
How to use:
tooltip: 'Please indicate at least one cause of damage.'
Type: string

tooltipTemplate​

Write an ID of an HTML container to provide further information about the field. A question mark will then be shown within the label and with a click/tap on it, the content of the container will occur.
How to use:
tooltipTemplate: 'example_control_tooltip'
Type: string

url​

The URL must be a server relative SharePoint URL. For instance, the oData link to a SharePoint list.
How to use:
url: '/_api/web/lists/getbytitle('SP')/Items?$select=Title&$orderby=Title'
Type: string

valueMapperDelay​

Add a delay to the Kendo ValueMapper. Useful for very large catalogs.
How to use:
valueMapperDelay: true
Type: boolean

visiting​

Set "true" whenever the Form element should be marked as "visited" when the user has clicked or tapped at the Form field.
How to use:
visiting: true
Type: boolean

listOptions Object​

dialogHide​

Hide field from filter/sort/group dialogs.
How to use:
dialogHide: true
Type: boolean

dialogText​

Set custom label for filter/sort/group dialogs.
How to use:
dialogText: 'Display Text'
Type: string
Note

Please follow the conventions to build an OData Source Link by considering the following documentations:

formControlMapping

​

The mapping objects consist of keys which are the Form Control IDs to copy to and the value which can be a data source key or an object with the data source key and a format function.

By every value change the specified data source entries are copied to the given Form Controls.

<div
    id="exmaple_mapping"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'Example',
        url: '/api/catalogs/Example?$select=Text,Value,Description,Date',
        dataTextField: 'Text',
        dataValueField: 'Value',
        formControlMapping: {
            description: 'Description',
            date_picker: {
                key: 'Date',
                callback: HFFormdefinition.ExampleNamespace.formatDateFunc
            }
        }
    }"
></div>
type FormControlMappingType = {
    key: string;
    callback: (dataItem: any, dataKey: string) => any;
};

interface IFormControlMapping {
    [id: string]: string | FormControlMappingType;
}

Stored data

​

<div
    id="technician"
    data-hf-control="ComboBox"
    data-hf-options="{
        label: 'Technician',
        dataSource: [
            { name: 'Bauer, F', code: 'Bauer, F' },
            { name: 'Gruber, P', code: 'Gruber, P' },
            { name: 'Lanner, G', code: 'Lanner, G' },
            { name: 'Simon, R', code: '3521' },
            { name: 'Herbert, W', code: '123456789012' }
        ],
        dataTextField: 'name',
        dataValueField: 'code',
        required: true   
    }"
></div>

For each ComboBox inside your Forms there are two value pairs of stored data:

First the information for the ComboBox itself

{
    "id": "technician",
    "value": "3521"
}

and second for the selected value:

{
    "id": "technician_HFComboText",
    "value": "Simon, R"
}