Form Grid

The Form Grid extends the default functionalities of a typical grid element in Joget's Form Builder. Unlike the generic grid element that only accepts standard text fields, the Form Grid captures data by referencing other form elements, allowing full use of features like validation and formatting.

How does it work?

To see how the Form Grid works, use the built-in App Expenses Claims and create a new form to mimic an existing form in the app. Follow these steps:

1. Start the Joget Server and open the App Center.
2. Log in as admin and click the pencil icon on the Expenses Claim to open the App Composer.
   
3. Under the Form Builder column, click Expense Claim Form.
   
4. Drag and drop the Form Grid element onto the canvas.
5. Click the Form Grid element on the canvas to open the Configure Form Grid properties.
6. Fill up the Configure Form Grid properties as follows and click Apply Change :
   • ID: entries
   • Form: Expense Claim Entry
   • Columns:
     

     Field	Label	Type
     date	Date	Date
     category	Category
     purpose	Purpose
     amount	Amount	Decimal

7. Click Preview. Click the plus sign on the Form Grid, and it will open a popup displaying the form it references.
   
8. Open up Expense Claim Entry and note that the Field IDs are the same as those in the Form Grid configuration. This is how the Form Grid displays data from the target form.

Configure form grid

Configuring the Form Grid involves setting labels, IDs, form references, and column definitions to ensure the element captures and displays data as intended.

When adding a Form Grid, you will see the following fields available for configuration:

• Label: The element label is to be displayed to the end-user.
• ID: Element ID. A corresponding database table column c_entries will be created by declaring it as entries. See Form Element for more information about defining the ID and a list of reserved IDs.
• Form: Target form to refer to.
• Columns: The columns defined here must correspond to the form chosen above.
  • Field ID: Field ID of the form element to refer to the target form.
    For example, the HR Expense Claim Entry form contains Form Elements with the ID date, category, purpose, and formattedAmount.
  • Label: Column label.
  • Format Type: Format the returned value using available format types.
    • Text: Formats the value as text.
    • HTML: Outputs data as HTML
    • Multiple lines text: Maintains the spacing and formatting for multiple lines of text, such as TextArea.
    • Decimal: Format as a decimal. The number of decimals is expected in the Format field.
    • Date: Formats as a date. Original Date and New Date formats are expected in the Format field.
      

      Example of usage:
      Original value: 5/23/2012
      Expected value: 2012/5/23
      Format : M/d/y|y/M/d

      Note: See Java SimpleDateFormat for the date format.
    • File: Show the value as a link to the attachment. Form ID is expected in the Format field.
      
      Important 
      

      1. Specify the Form ID that contains the actual File Upload form element.
      2. Ensure you use the Multirow Form Data Store as the Load Data Store.
      3. The file will be downloaded as an attachment but will NOT follow the properties set in the target form's File Upload properties.
    • Image: Show the value as a thumbnail of the attachment. Form ID is expected in the Format field.
      
      Expected Form ID: Specify the Form ID that contains the actual Image Upload / File Upload form element.
      
    • Options: Show the label of a multiple-choice element given the value given. Form ID is expected in the Format field.
      
      Expected Form ID: Specify the Form ID that contains the actual Select Box / Radio / CheckBox form element.
  • Format: Additional argument depending on the chosen Format Type.
  • Width: Column width in characters (such as 200px).

UI 

UI settings configure the appearance and behavior of the Form Grid, including sorting, layout, and interaction features.

Sorting

Sorting in Joget's Form Builder allows you to control the order of rows in a form grid. This ensures data is displayed in a specific sequence, enhancing data organization and readability.

• Enable Sorting Feature: Determines if the ordering of rows is to be enforced.
  • When enabled, this feature records the row sequence of form grid records, meaning it logs which ID is in row 1, row 2, and so on, and rearranges it back in this ascending order upon loading the Data Store.

  • Check this box to activate row ordering in your form grid.

• Field ID for Sorting: Field to keep the ordering sequence. This Field ID corresponds with a hidden field that keeps the sequence number (e.g., 0, 1, 2, 3, 4) in the target form.
  This field ID must *not* be an existing field in your form that you use for your form data. Potential result in data loss if you use the existing column.

Advanced sorting options

If you need automatic sorting based on another column value when loading the form grid or spreadsheet, you can use:

• Load Grid Data with Custom Sorting and Filtering.
• Database SQL Query with the ORDER BY ASC SQL statement.

These options allow for more complex and customized sorting logic to be implemented in your form.

Form

Form properties in Joget's Form Builder allow you to configure the form's behavior and appearance, including the submit button labels, read-only settings, and popup dialog dimensions.

Configure the fields below:

• Form Submit Button Label (Normal Mode): The Submit button's label in normal mode.
• Form Submit Button Label (Readonly Mode): The Submit button's label is in read-only mode.
• Display field as Label when Readonly?: Displays the element's value as plain text when set to Readonly.
• Popup Dialog Height: Specifies the height in characters (e.g., 200px).
• Popup Dialog Width: Specifies the width in characters (e.g., 200px).

Grid

The Grid element in Joget's Form Builder enables the capture of structured and related data. It supports multiple features to enhance data entry, including row numbering, pagination, and validation.

Configure the fields below:

• Readonly: Determines if the element is editable.
• Disable Add Feature: Determines if a new row can be added.
• Disable Delete Feature: Determines if a row can be removed.
• Delete Confirmation Message: Confirmation message when deleting a row.
• Show Row Numbering?: Shows numbering on the grid.
• Paging Size: Items to be displayed per page.

Validation & data store

Validation settings ensure data integrity, while data store settings manage how data is retrieved and saved.

Validation

Validation settings help ensure that the data entered in the grid meets specific criteria before saving it.

Configure the fields below:

• Validator: Attach a Validator plugin to validate the input value. Validation occurs whenever a form is submitted except when submitted as Save as Draft.
• Unique Column: Column/Field ID to identify record ID.
• Min Number of Row Validation (Integer): Minimum number of rows required.
• Max Number of Row Validation (Integer): Maximum number of rows allowed.
• Error Message: An error message will be shown when row requirements are unmet.

Data store

Data store settings manage how the grid data is retrieved and saved.

Configure the fields below:

• Load Data From: Customize the method for data retrieval to populate the multi-row form grid.
• Save Data To: Customize how the form grid row records are saved. 

This option is empty by default. An empty Data Store means the form grid records will be saved/loaded as JSON in the parent form and database table. See the list of available Form Data Store options for more options.

The Multiple Form Row is recommended to save each record into a child database table via a subform definition. The Data Store will update the foreign key parent id in each child record to point to the parent database table.

Child form data deletion options

These settings specify how to handle the deletion of associated data when a row is deleted from the grid.

• Delete Associated Grid Data?: Deletes inner grid data if the popup form has grid elements.
  Warning
  These 3 options (Delete Associated Grid Data, Delete Associated Child Form Data, Delete Files), in combination, do apply to nested grid/child elements.
  
  

  These options traverse the entire form tree. It will move on to the next grid/child element upon encountering a false condition.

  For example, consider that the popup form has a form grid, form grid has a subform, subform has a file upload element with abc.pdf. If all options are checked, abc.pdf will be deleted. If all except ONE of the options is checked, abc.pdf will NOT be deleted.

• Delete Associated Child Form Data?: Deletes child data if the popup form has child elements.
  Warning
  These 3 options (Delete Associated Grid Data, Delete Associated Child Form Data, Delete Files), in combination, do apply to nested grid/child elements.
• Delete Files?: Deletes actual uploaded files if the popup form contains file upload elements.
  Warning
  These 3 options (Delete Associated Grid Data, Delete Associated Child Form Data, Delete Files), in combination, do apply to nested grid/child elements.
• Abort Related Running Processes?: Aborts process instances related to the deleted row.

Advanced

Advanced settings provide additional customization options for grid behavior and interaction.

URL request parameters for popup form

These settings allow you to map values as URL parameters to pass data between forms.

Configure the fields below:

• Parameter: Map values as URL parameters.
• Field ID: Field ID of the form element in the current form.
• Default Value: Default value when no existing value is found/selected. Hash variables are accepted (e.g., #currentUser.firstName# #currentUser.lastName#) to pre-populate the field with the currently logged-in user's name.

Bulk deletion

The Form Grid now supports bulk deletion of rows of data (temporary deletion).

Configure the fields below:

• Selection: Users can select the records they want to delete by checking individual checkboxes or using the checkbox in the header to select all rows.
• Deletion: After selecting the rows, click the trash icon above the table to delete the selected rows.

Related documentation

For more information on file uploads in grids and duplicating form grids, see the following tutorials:

• File Upload in Grid
• Duplicate Form Grid
• How to use URL Request Parameters for Popup Form

Download Tutorial App: Grid from Joget Marketplace to learn more.

Download sample app