Working with Grids
This topic describes how to add grids to your intake forms to collect and display data in a tabular format.
To collect and display data in a tabular fashion, with rows and columns, you can add grids to your intake form design. Grids can be added for these offerings:
-
Permits
-
Planning and Zoning
-
Business Licenses
You can create grids for only the current intake form you are creating, or you can also create reusable grids, which you create once and can add to multiple forms.
Adding a Grid
To add a grid:
-
Expand the Add New > Layout section in the Elements panel.
-
Select the Grid layout element, and drag it onto the workspace of your form design.
Note: You can drop grids directly onto a page tab, or you can drop them within a group box. -
Select the grid, and set the required attributes in the Grid Attributes panel.
|
Page Element |
Description |
|---|---|
|
Remove |
Click to remove the element from the page. Note: Remove all grid
columns before removing a grid. The grid must be empty
before you can remove it.
|
|
Label |
Add a name for the element, describing the collection of items within it. |
|
Collapsible |
Turn on to enable the element to be collapsed when an end user clicks it, hiding items it contains. If not turned on, the group box is always expanded and its content is always visible. |
|
Show Row Numbers |
Turn on to display row numbers for every row in the grid. Row numbers can help users to identify rows in larger grids. If enabled, at design-time a Rows column displays on the left-hand side of the grid to remind you that space will be occupied by the row number at runtime. |
|
Show Label |
Select to hide the element label (specified in the Label field). Note: You can add help
only to grids with Show
Label turned on. If Show Label is turned
off, the Add
Help button does not appear on the
attributes panel and any help icons associated with any
previously added help no longer appear.
|
|
Hide Border |
Hides the group box border. When turned on, the border is not visible. |
|
Reusable |
Enable if you want to reuse the grid on other intake forms. You can set a grid to be reusable only before the initial save of the intake form design. You can continue editing the reusable grid until you publish the intake form. When you publish the intake form, grids that are set to be reusable are locked from further editing and appear within the Ready to Use > Grids section in the Elements panel. Note: Reusable grids aren't available for Code Enforcement.
For more information on reusable grids, see the section below titled "Working With Reusable Grids." |
|
Initial Sort |
Select the grid column by which you want the grid sorted when it first displays at runtime. |
|
Sort Order |
Displays only when you've selected a column from the Initial Sort drop-down list. You can set how the grid is sorted as it first renders on the page. Options are:
The end user can change the sort order at runtime as needed. |
|
Add Help |
Click to launch the Contextual Help page, which you can use to add help information to aid public users in completing the intake form. The Add Help button appears only if Show Label is turned on. Help text added for group boxes should apply to the overall group box content. Help can be added also at the page level, field group level, and field level depending on the scope of the help text. Note: You can add help
at the grid-level only. You can't add help to individual
grid columns.
For more information on adding Contextual Help, see Adding Contextual Help to Forms. |
|
Control Display |
Expand the Display section to the view this attribute. Click to select an element in the form that controls the display of the group box. For more information, see Displaying Form Elements Conditionally. |
|
Hide from public user |
Expand the Security section to view this attribute. Hides the entire grid and all the grid columns it contains from the public user at runtime. Note: Individual
columns in the grid can't be hidden from or exposed to the
public.
Only agency staff can view and update information within a grid with Hide from public user turned on. In addition to hiding the UI element from the public user in the interface, the application also secures the back end for that specific UI element, such as preventing any unauthorized access to the fields contained within that UI element using a REST API, for example. Note: For fields within
elements set to be hidden from the public, the default value
for that field entered on the intake form design can be used
to calculate fees for the intake form application at
runtime.
|
|
Confidential |
Note: The Confidential
attribute applies only to the Business Licenses
offering.
Expand the Security section to view this attribute. Turn this attribute on to specify that the grid field content is confidential information. At run time, fields with confidential information will be visible only to users with the appropriate privilege. These users can see the confidential information:
Note: The grid fields
appear in the JSON payload for the page, however the field
value will be null.
Note: The Hide from
public user setting and the Confidential setting are
mutually exclusive.
|
|
Business Object |
Indicates the name of the custom object created for the current intake form. |
|
Collection ID |
The name of the child object within the parent business object created for the grid. When writing Groovy business logic or setting up integrations, you will need to refer to the data within the grid child object using the collection ID. For example: LNP1IDBuildPermit2207g1Collection_c Where LNP1IDBuildPermit2207 is the permit ID and g1Collection_c is the first grid in the form design. Note: The name of the
grid is automatically generated based on the transaction ID,
such as the permit ID, and the index number of the grid
within the intake form layout, indicated by g1, g2,
g3, and so on. The index number is determined by when you
added the grid to the form layout, not where
the grid displays in terms of sequence. For example, the
third grid you added to an intake form would contain g3Collection_c in its collection ID.
For a reusable grid, the collection ID will look like the following: LNP1ResBuildPermit2023g1_rel_LNP1ResBuildPermit2023g1_LNP1ResBuildPermit2023_Tgt |
Adding Fields to a Grid
Adding fields creates the columns in the grid.
To add fields to a grid:
-
Expand the Add New > General section in the Elements panel.
-
Select a field type, and drag it onto the grid.
Each field type you add to the grid becomes a column in the grid.
You can add these field types to a grid:
-
Date field
-
Date time field
-
Drop-down list
-
Number field
-
Single-item check box
-
Text field
Note: You can't add ready-to-use field groups or fields, such as Job Cost or user-defined reusable fields, to a grid. -
-
Select the column header cell to display the Grid Column Attributes panel, and set the required attributes for that field type.
The same attributes that apply to fields apply also to grid columns. For more information on field attributes, see Working with Fields.
The following attributes apply specifically to grid columns.
Page Element
Description
Rows
The Rows column appears only if Show Row Numbering is enabled in the Grid Attributes panel. Each grid row is assigned a sequential row number automatically. At design-time, the row numbers appear to remind you that the left-hand column is reserved for the automatic row numbers. At runtime, when the user saves each new row of data, the next sequential number is assigned to that row.
Sequence
Adjust the order, from left to right, in which the selected grid column appears. For example, if the Sequence for a grid column is set to 1, it will be the first grid column appearing on the left of the grid.
Wrap
Select to wrap the field content so that all the required text is visible to users.
Applies to text fields and drop-down lists.
Read-only
Select to make the grid column read-only at runtime so it can't be edited.
Use this option for any field value that you don't want edited, such as for data imported into the grid from outside data sources that you want to appear for informational purposes only or for fields containing default values.
Field ID
If performing tasks like writing Groovy, importing data, configuring integrations, and so on, use the field ID to identify the grid column.
Working with Reusable Grids
When creating reusable grids, keep these items in mind:
- You can only set a grid to be reusable prior to the initial save of the form. Once you save the form, the Reusable switch in the elements panel is disabled.
- After you've saved the intake form, you can continue to add fields, and update the available attributes for the grid or grid fields.
- Once published, the grid and the grid fields become locked, with only certain attributes available to modify.
|
Page Element |
Description |
|---|---|
|
Grid Labels Grid Field Labels |
You can update the labels for a published reusable grid and the grid fields, but make sure to consider that doing so affects every intake form using that grid. When labeling reusable grids and the grid fields, consider all of the forms in which they'll be used, and use labels general enough to apply to all contexts. |
|
Intake Form Versions |
Reusable grids don't support versioning. You can have reusable grids on intake forms that are versioned, but you can't make changes to a reusable grid and apply them to a specific intake form version. |
|
Hide from public user Help Control Display |
You can modify these attributes for reusable grids and the setting applies only to the instance of the reusable grid on current intake form. |
Importing Intake Forms with Grids
If you are importing an intake form with a grid in the layout, you need to either save or publish the form after a successful import to make sure the grid layout and database object are created completely in the target environment.
For more information on exporting and importing forms, see Exporting and Importing Intake Forms.
Working with Grids and Groovy
You can reference grid data in object-level Groovy, but you can't add Groovy directly to grids or a particular grid field.
When referencing data in grids in your object-level business logic, follow the syntax described in "Accessing Data Within Grids" in Adding Logic.