A grid displays a list of records, specified by the sub data source of that control.
In Brixxbox, app configuration allows you to add different controls in your app. It also provides four types of properties which manages how control should behave or look in app. Those four property types are:
General Properties
Size
Style
Translation
General Properties
These are the main properties of any control. These properties define how control behaves in Brixxbox App.
Control Type
- For using grid control, click on "Add Control" and select "Grid" control type from drop down.
Control Id
- For each Brixxbox app, this id should be unique. For Example: "_abcdef". Brixxbox allows you to change its value only once. You can change this id to any value but it should be meaningful. Recommended way is to start with mandatory prefix(set in app). It can contain numbers, underscores, uppercase and lowercase letters.
Label
- It is the display value for control.
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.
Hide Select Checkbox Column
- By default, grid also display's a checkbox with each row. This checkbox is used to select a specific row. If it is enabled then user can select multiple rows at a time and perform different operations on them like deletion. If user does not want to display this checkbox then this property should be checked.
Hide Edit Button Column
- This property is by default unchecked. It allows grid to display an edit button with each displayed row. If user does not want to display Edit button then this property should be checked.
Cascade Delete
- This is a checkbox. If it is set and a delete operation is performed on a record, in an app containing this Grid control then all the lines of a record will get deleted. For example: User wants to delete an order with all of its item's lines.
Cascade Copy
- If it is set and a copy operation is performed on a record, in an app containing this Grid control then all the lines of a record will get copied. For example: User wants to copy an order with all of its item's lines.
Server Side Paging
- Use this property for big data tables. If checked, grid will only be able to data from server side only instead of getting all the data from data source.
Smooth Scroll
- If checked, this property allows the users to scroll through list of items of grid instead of scrolling up and down via paging buttons.
No automatic refresh
- Use this property when fetching expensive Grid data. If set, it will block unnecessary calls for data. Brixxbox allows an app to refresh data of all of its controls using "app.refresh()" function. Settings this property will exclude this grid from data refresh calls. However, you can refresh grid data by specifying the grids name in refresh function. For Example: app.refresh("myGrid").
Gird control can be used in two possible scenarios: displaying all data of sub data source. For example: listing all customer orders, and displaying some values. For example: listing order lines of a specific customer order only.
This tutorial assumes that a user has an existing customer order app which records customer's order data. They want to list all customer orders in a new app and update grid to display all order lines of a specific customer order in customer order app.
For first scenario, create a customer order list app, select "Grid" from list of controls. After that you need to give an id to your grid. As grid is usually used to display data from a sub data source, so there is no need to create column in database for Grid control.
Let start with the first case. Select a new app, name it "customerOrderList". Select a "Grid" control type from the list, assign a unique id and meaningful label:
As you can see from the above picture, we have added a grid control but nothing appears in app editor on right side. This is not an error but expected behavior because grid control is used to display a list of records but first we need to specify "sub data source" in grid properties. For this click on "edit sub data source" and select "config" as a data source type. Now select "CustomerOrder" app to display all customer orders and save app settings.
Now you can see that our grid list all customer orders. In its menu, grid allows multiple options like adding new data row, deleting data row, refresh grid, copy data, search filter and drop down list for specifying number of entries for display. Grid provides each data row with plus, select, and edit button. Depending on screen size grid displays only few data columns and plus button is used to see remaining columns as shown below:
Grid allows us to enable or disable select and edit buttons(see General Properties). We have successfully listed all customer orders, now we move towards second scenario. We have two relations between customer order and order lines which are: customer order can have multiple order lines, and one order line can only belong to one customer order. In this part, we want to cover second relation. Now we want to display order lines which belong to only one customer order in customer order app grid. Our customer order app looks like this:
There are a lot of details in this app which are not important here. Our concern is order lines gird which will display only those order lines which belong to one specific order. To allow this behavior, we need to edit "sub data source" settings of our order lines grid and set "target field binding" with the customer order line id.
Now we will see only those order lines in our grid which belong to same customer order. Lets add a new order for our customer John and add a new order line for this order.
Now order lines which belong to John's order are being displayed in our order lines grid. In our case we only added one order line.
Comboboxes are often used to refer to header records (an order line record will most likely have a combobox with its order record).
In Brixxbox app configurations you can add different controls. One of them is ComboBox. Each control has four types of settings
General Properties
Size
Style
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 Brixxbox app, this id should be unique. By default Brixxbox assigns a random id which starts with underscore and followed by a string. For Example: "_abcdef". Brixxbox 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 Brixxbox 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 Brixxbox 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.
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.
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".
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.
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.
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.
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.
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.
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.
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.