# ComboBox

Comboboxes are often used to refer to header records (an order line record will most likely have a combobox with its order record).

## Demo

{% embed url="https://youtu.be/KhrooXGYBQ4" %}

## Documentation

In Gebra Suite app configurations you can add different controls. One of them is ComboBox. Each control has four types of settings

1. General Properties
2. Size
3. Style
4. Translation

## General Properties

These are main behavioral properties of any control. These are responsible for control's functionality.

* Control Type

\- For using combobox control, combobox control type should be selected from drop down list.

* Control Id

\- For each Gebra Suite app, this id should be unique. By default Gebra Suite assigns a random id which starts with underscore and followed by a string. For Example: "\_abcdef". Gebra Suite allows you to change its value only once. You can change this id to any value. Recommended way is to start with mandatory prefix(set in app). It can contain numbers, underscores, uppercase and lowercase letters. Each control is always accessed with its Control Id. For Example, you can get and set control value by using its ControlId. If you want to store value of this control in database, use the database button to create a column. You will be able to select column datatype, max length, can be null, options.

* Label

\- It is the display value for control.

* Data

\- This property specifies from where this control gets data. If no option is specified then by default "Not in Database" option is chosen. If you want to set it then you have to specify the controlId of data source.

* Refers to config

\- You need to set this option if this is a field, that other fields refer to, to get data from another config.

* Combobox Key Field

\- This is the field value from the sub data source. It also becomes the value of our combo box. When we have to get the value of our combo box using "getfieldvalue" function. It will return the corresponding id of selected combobox entry.

* Combobox Value Field

\- This option defines how each entry of your combobox will be displayed. It can be a single or multiple columns from sub data source. For single column just name the column. For Example, "adrName". If you want to choose multiple columns, then use curly brackets. You can choose any place holders between them. For example, {id} - {adrName}. "-" is a place holder while id, adrName are column names.

* Min Search Length

\- This option specifies the minimum search length of string to trigger search function. If you do not want any search function then specify "-1". In case you want to specify after how many characters Gebra Suite should trigger the search and get actual records from the sub data source, specify it here as positive integer. For Example, if value 3 is specified then Gebra Suite will trigger actual search only after 3 characters are entered in search field.

* Multiselect

\- When this option is specified, one can select multiple values as combobox entries.

* Select List Button

\- By default this is hidden. It opens a list of all items of sub data source. It can be used to select an entry from combobox.

* Select Edit Button

\- By default this is enabled. If a value is selected in combobox then by clicking edit button will open the complete record in corresponding application. If it is clicked without any value it will open the corresponding application with no record. It can be used to add a new record.

* Default Value

\- This value is set when an application is opened or a new record is created.

## Tutorial

This tutorial will follow the similar example used in the demo for combobox. You can find this demo at the top of this page.

This tutorial assumes that a user has an existing app and they want to add a new control of type "Combo Box". First of all, select "combo box" from list of controls.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-717164d27e57d7cd87999e5f1d85f55d5fe17717%2Fimage_combobox_1.png?alt=media)

After that you need to give a id to your combobox and create column in database if necessary. Here we named it "myCombo". Also, add a public label for combobox. We labelled it "Address".

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-bcfb7ce13c168c0597f2b3eded6362c8c83459da%2Fimage_combobox_2.png?alt=media)

Now save the control. It is time to assign a sub data source to our control. Click a sub data source button. Here you can assign different types of data sources. For this example, we will use config data source type. After that select the corresponding app config. We are selecting "address" config because we want to display all the addresses.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-baadfeb58a4917cb50fa11cf25d65c9f6e570108%2Fimage_combobox_3.png?alt=media)

Up till now we have defined a combobox, assigned a unique control id and also added a sub data source to it. Now we want to assign two main properties to combobox: combobox key field, combobox value field. "Combobox key" property is a column from result set that will also be the value of our combobox when the entry of combobox is set. Mostly it is the id of result set. Here we also choose id. We can use this value for comparisons. For combobox value field, we want to display values of two columns: adrNumber, adrName from result set. We have to use curly brackets when using multiple columns.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-9b13a042432c40c0386dc6c3294d4b60bae37a9c%2Fimage_combobox_4.png?alt=media)

Each entry of combobox will now represent the number of the address and the person's name. For example "10001 John". In this way we can define and use combobox but can we use the value of combobox to display or change some other data? the answer is yes!. For demonstration, we will add grid control (see grid documentation) "myGrid". We also assign address config as a sub data source for our grid control. Now "myGrid" control will display all the addresses present in the result set.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-ad968f7451e6c33209b12d06dc87e7ad68f47299%2Fimage_combobox_5.png?alt=media)

As you can see from above picture that nothing is selected in our combobox "Address". Now we want that whenever we select a record in combobox, the grid displays the same selected record only. For this purpose, we need to modify sub data source of mygrid and add a where clause. An important thing to note here is that all controls of an app are available as sql parameters. In where clause, we need to specify a condition which displays only a record which matches combobox value. We can specify this as "id=@myCombo". Remember that we selected "combobox key field" as id of sub data source "address". In order to pass this change to grid, we have to add a control event "onChange" to our combobox control. Whenever our combobox value change, we want "myGrid" to refresh.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-58779388295336a9951bd53873b407e8cc0bd84e%2Fimage_combobox_6.png?alt=media)

Now save and set a combobox value and we will be able to see only selected record in "myGrid". As we can see from figure below.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-9d98dac6916bf446027aa824ff2e9f002dea7296%2Fimage_combobox_7.png?alt=media)

Combobox also allows us to select multiple records at a same time. To achieve this functionality, select "multiselect" checkbox from combobox properties. You can see from figure below that multiple values are selected in combobox but there is no record shown in grid.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-5e27029c59bae5b8180f7a226f853725e7d6bca5%2Fimage_combobox_8.png?alt=media)

This is because we were using where clause for comparing one value of combobox but now our combobox has multiple values. Now if we call "getfieldvalue" function on our combobox. It will return an array with selected combobox key value's. Now we have to update our where clause logic in grid to display all selected records. We add this statement to where clause **"id in (select value from OpenJson(@myCombo))"**. This statement says that if a value is present in result set then display it in grid.

![Picture of adding a combobox](https://4275956601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOvU7jyPAQ0DefSlDf98E%2Fuploads%2Fgit-blob-97f4fce111811e454f5541a5a1ca49608ed21f72%2Fimage_combobox_9.png?alt=media)
