The editable grid control allows the user to edit the data inside of a grid within the grid itself.
Note: The Editable Grid control has no automatic way to save the data. One would need to execute a Save All action (in a button, for example) to save the data in the grid.
In the below example, the data in the second row is being edited:
- Undo Changes in Grid - This will reset the changes done in the grid.
- Delete - Mark the row for deletion
- Add Lines - Insert rows to potentially add data to the grid
- Undo changes in row - This will undo the changes done in the row
To use the Editable Grid control in your own customizations, you will configure it with the Editable Grid Builder, which is available from the contextual menu of the Editable Grid control, or in the right properties panel when the control is selected.
The builder is separated into three areas:
- Configuration - Set up the table to use as well as styling of the editable grid
- Columns - Set up the fields used as columns in the table and how to format it for viewing
- Views - Set the views the editable grid will have, including visibility, sorting, and filtering
Editable Grids Builder: Configuration
The Editable Grid's Configuration area has two sections to configure: Data and Styling.
- Select a base table - the data shown in the Editable Grid.
- Records per page - how many rows are shown in the Editable Grid. Do not choose "Display All" if you have a table with more than 10 records.
- Disable all editing (read only) - when checked, the table is viewable, but the user will not be able to edit the data inside of it.
- Show go to page input field - allow user to input which page of the grid to navigate to if the grid has multiple pages.
- Allow user to add more rows
- Button label (add more rows) - If above is checked, this lets you configure the text on the button which will add more rows to insert data
- Number of new rows to add - How many new rows are added when the "Add more rows" button is clicked.
This allows you to set up what options are available on the editable grid.
- Show delete row column - On each record, the right most column will be a trashcan so the user can select it for deletion. (This will not immediately delete the record).
- Show delete confirmation dialog - When the grid is being saved, this will show a confirmation that the records will be deleted.
- Hide view selector - If there are different filter views, you can hide the ability for the user to see and select a different view.
- Add checkbox column - This will show a checkbox column on the left of the grid to allow the user to select multiple records.
Editable Grids Builder: Columns
The Columns area allows you to add fields to the Editable Grid from the table specified from the Configuration area. Most fields you wish to add are similar when configuring, but there are special considerations for Dropdown columns and Button columns. Please see the appropriate sections for those.
On the left will be a list of columns currently added to the Editable Grid. Required columns are separated into their own heading.
To add a column, select Add another column. To delete a column, hover over the column you want deleted, and select the trashcan icon.
You can configure each column by selecting it from the list of columns. Each column will have a number of options to configure based on the type of the column. However, the following should be standard for the majority of fields:
- Header Caption - the header text shown on the Editable Grid column.
- Header Alignment (Tablet & Desktop): The header can be set to left, center, or right alignment. You can also select it to be the same as the data cell.
- Default Value - default value given to this field for new entries.
- This column is a read only column and can't be edited - check to make read only.
- Width (Tablet & Desktop) - set the width of the column relative to other columns (small, medium, large), or set it with a fixed pixel size.
- Alignment (Tablet & Desktop) - how the data is aligned within the column.
Columns: Validation Rules
Fields can be set to check for validation. For further information, please check our article on Field Validation. Rules to check for:
- Field is Required - data cannot be saved unless this field is populated.
- Field Contains a Valid Email Address - data cannot be saved if inputted text isn't a valid email address.
- Field Maximum Length - data cannot be saved if the number of characters exceeds this maximum length.
- Field Minimum Length - data cannot be saved if the number of characters is not at least this minimum length.
- Field Contains No Malicious Values - this will ensure a user isn't trying to insert malicious scripts into a text field.
Each column may have different events associated with it to add actions to. Most fields will have the Change event available to configure.
Editable Grids Builder: Dropdown Columns
As mentioned above, a column can be of different types. However, there are a number of options to configure when the column is a dropdown field. Below is an example of an editable grid configured for the Activity table. The Contacts dropdown field has been added as a column:
Dropdown Column: Display Value
By default, the data shown in the editable grid will be the Record ID of the option selected from the dropdown field.
In the below example, you can see the contact associated with the activity, but it's showing the contact's Record ID:
You can configure the default display value to point to a more appropriate field, however this field must be an already added Linked Field in the table. In our example, the Activity table has a number of linked fields for the Contacts dropdown, so we can choose the ContactsName linked field to show instead.
Dropdown Column: Columns
Once the display is set, you still need to configure how the options will look when a user wishes to open the dropdown menu. In the below example, we run into the same problem of only showing the Record ID again:
However, this time, you can show any field in the dropdown, not just linked fields. Furthermore, you can customize multiple fields to show up per option.
In the below example, we have made the RecordID invisible by unchecking Show on Desktop and Show on Mobile.
And then two more fields were added to the columns by clicking Add another column. The two fields added were Name and Email.
You can also select the format for each field, depending on the field type chosen.
Dropdown Column: Sorting and Selection Criteria
Like other lists, you can set the sorting and selection criteria for the options within the dropdown.
- Sorting - how the options in the dropdown will be sorted.
- Selection Criteria - how the data is selected to be shown in dropdown. For more information on how a selection criteria works, please see our article on The Criteria Builder. Although it deals with other controls, the concept is the same.
Dropdown Column: Change Event
Enter in the actions that will occur when the user selects an option within the dropdown.
Remember, when customizing actions, you will be able to reference data via the editable grid control, but only from the row the dropdown is on. You will not be able to alter or pull in data from another row.
Editable Grids Builder: Button Columns
Instead of a field, you can add a button to a column. This will allow you to execute actions using the data in the row the button is in.
You can configure the button column by selecting it from the list of columns. Each button column will have the below options to configure.
Button Column: General
- Header Caption - the header text shown on the Editable Grid column. This can be different than the text inside of a button.
- Header Alignment (Tablet & Desktop) - Alignment of header text in column.
Button Column: Formatting
- Width (Tablet & Desktop) - set the width of the column relative to other columns, or set it with a fixed pixel size.
- Alignment (Tablet & Desktop) - how the data is aligned within the column.
Button Column: Button
- Button Text - Label inside of button.
- Load State - Default state of the button when grid is first loaded.
- Font Size - Size of text font inside of button.
- Text Color - Color of text font inside of button.
- Background Color - Color of button.
Button Column: Click Event
Enter in the actions that will occur when the button is clicked.
Remember, when customizing actions, you will be able to pull in data via the editable grid control, but only from the row the button is on. You will not be able to alter or pull in data from another row.
In the above example, when the button is clicked, the value in the Contacts column will be assigned to an action result. The value assigned will be taken from the row the button is on.
Editable Grids Builder: Views
The Views area allows you filter which rows are shown within the Editable Grid.
On the left will be a list of views currently added to the Editable Grid. The view with the star (★) is the default view when a user first views the grid.
To add a view, select Add another view. To delete a view, hover over the view you want deleted, and select the trashcan icon. To set the order of the views shown in the view filter dropdown, select Reorder Views.
You can configure each view by selecting it from the list of views. Each view will have the below options to configure.
- General - the name of the view to be shown in the view filter drop down.Set as the default View - If the view is not the default view, this button will appear to set the view as the default view.
- Visible Columns - each view can specify which added columns are visible and which ones aren't.
- Sorting - how the data is to be sorted within the Editable Grid.
- Selection Criteria - how the data is selected to be shown in the Editable Grid. For more information on how a selection criteria works, please see our article on The Criteria Builder. Although it deals with other controls, the concept is the same.
- Duplicate View - copy the view.
When your configuration is complete, select close to exit the Editable Grid builder. All settings are automatically saved.
Saving Data in the Editable Grid
As noted at the beginning of this article, data is not automatically saved when a user adds or modifies data within the Editable Grid.
If a user were to navigate away and then come back, the data will be lost.
In order to save the data on the Editable Grid, the action Save All must be executed.
For example, you could add a button beneath the grid and label it "Update Grid". When clicked, this button could run the Save All action and save changes and/or additions to this grid.