Data Grid Widget

<< Click to Display Table of Contents >>

Navigation:  Enterprise > Widgets >

Data Grid Widget

The Data Grid widget displays the output of a grid report (i.e., IGridReport) in a sortable, filterable grid that supports paging. EQuIS Information Agents (EIAs) for grid reports can also be used as a data source for the widget. Since the visibility and order of report fields can be configured, this widget is useful for reviewing data without downloading the full report output. The Data Grid widget can be configured to act as a dashboard filter, using the underlying report's parameters as the filters and the data as the filter values. The Data Grid widget also supports filtering using Filter widgets (if not set as a dashboard filter).


Note: The Data Grid widget will run the underlying report with each action (sort, filter, switch pages, change page size, etc.). EarthSoft highly recommends using report caching (see User Profile) when using the Data Grid report. Report caching will significantly reduce database load and improve the end user experience while using the widget.




When using the Chrome browser, individual cell selection in the data grid is functional. The data columns of the Data Grid widget can be sorted or filtered.

Sorting – The columns are sortable in ascending or descending order by clicking on the column header (click again to reverse the sort). The sort is applied to full report output (with filter, if applicable); it does not just apply to the currently visible page of the grid.

Filtering – Beneath each column header is a filter box that filters on that column only. Enter a search term (one or more characters) in the appropriate search box beneath the column header. Only records that contain the search term will be displayed. Filtering is cumulative if multiple columns are filtered.

Download – Click the Download button to download all pages of the grid data as a Microsoft Excel file (*.xlsx). The downloaded file will respect any active filter currently applied to the grid.


The bottom of the widget contains paging controls for displaying a limited number of items at a time, as described below.  

Arrows – Use the left/right arrows to navigate through pages.

Go to Page List – Select a specific page to navigate directly to that page.

Rows per Page – Change the number of items to be displayed per page by using the drop-down menu.

Count of Pages and Total Items – This control indicates the total number of items available in the widget, how many pages to display the items, and which page is currently selected.



Widget Properties


The Data Grid widget is empty when added to a dashboard and must be configured to show report results. The editor for this widget allows the user to select a report, and then use the columns from the report to configure the widget appearance. The columns that are displayed and their order are controlled by the widget properties.


To add a report or edit other widget properties, open the Widget Editor by selecting the More Options Ent-More_Options-Icon icon in the upper right corner of the widget to display the drop-down menu and then select the Edit menu option. The Widget Editor includes two tabs used to define what and how the widget contents are displayed: Report and Advanced.


Widget Title – By default, the widget title is Data Grid. The title can be modified.

Widget Color – The color of the widget can be changed using the Change Widget ThemeEnt-Theme_Color_Iconicon to the left of the widget title.

Widget Object Editor – To set various appearance properties of the widget, select the Object Editor Ent-Widget-Editor_Properties icon in the widget header to open the Widget Object Editor. See the Widget Editor article for more details.

Cancel – Select the Close without Saving Ent-Close_icon button to exit the Widget Editor without saving changes.

Save – Changes will be applied to the widget by clicking on the Save Ent-Widget_Save-Icon button. The Widget Editor screen will close after the save operation is complete.

Help – The Help Ent-Help-Icon button connects to the online documentation related to the specific widget.



Report Tab


Report Chooser This control is used to select the report or EIA to be used with this instance of the Data Grid widget. The name of the currently selected report (if applicable) is displayed by default. To select a different report or EIA, click the Choose a Report button or name of the report. The Report Chooser will open and display available reports. Select the desired report or EIA.


Note: Because the report output is displayed as rows of data in a grid, you must choose a report that produces a table of data (i.e., an IGridReport).


Report Parameters – The report parameters (e.g., facility, sample date range, etc.) can be edited by clicking on the Edit button Ent-Report_Edit-icon to open the Report Parameter Editor for the selected report. A user with editor permission on the selected report may update the report.


After choosing a valid grid report, the widget will run the report and display the output columns for the report in a grid table. Use the table columns to configure the grid displayed by the widget.


The fields will display in the Data Grid widget as columns in the order they are listed within the Widget Editor. To change the order of the columns as they are displayed in the data grid, drag and drop the column rows (i.e., fields) to the desired display order.

Show/Hide Fields – The check box determines whether or not the field will be included in the data grid as a column. The person viewing the data grid can show/hide columns within the grid itself, but they will only be able to see the fields that are selected in the Widget Editor. If a field is not checked in the editor, the person viewing the data grid will not be able to see that field. Click the header check box to automatically show/hide all columns.

Column Header – The column names are listed as input text boxes. The name of the column is displayed in the grid as is but can be changed. For example, to display the SYS_LOC_CODE column as "Location", change the column name in the text box to "Location".

Width – This number is the approximate width of the column as a percentage of the entire width of the data grid. The default column width is 10. Adjust the column width as desired.

Use as Filter – Click the check box to use the field as a filter for the entire dashboard. Multiple fields can be selected. See the Dashboard Filtering section for more information about using the Data Grid widget as a dashboard filter.

Filter Name – Click the drop-down menu and select the desired filter name. For example, select @sys_loc_codes for a field displaying location names.



Advanced Tab


The Advanced tab displays the widget settings as raw JavaScript Object Notation (JSON). This allows for easy copying and pasting, as well as maintaining the ability to edit, add, or remove properties. Improper editing of the JSON will make the widget stop working.


isFrozen Property – Implements the ability to "Freeze" columns in the Data Grid widget. The isFrozen property can be applied to as many columns as desired by the user. The "isFrozen": true JSON property must be added manually to the desired column's object; it is not included in the JSON by default. isFrozen will default to false for all columns. The frozen columns will always stick to the left side of the data grid, and will be ordered based upon the column ordering set on the Report tab.


isUrl Property – This property allows columns in the Data Grid widget to display their values as clickable hyperlinks. The "isUrl": true JSON property must be added manually to the desired column's object; it is not included in the JSON by default. Once set, this property treats values for the column as hyperlinks. This allows users with custom reports or columns that contain a URL be used as a clickable link from the Data Grid widget. For an external link, the URL will need to include the http:// or https:// protocol for the hyperlink to recognize it as an outside source. If the protocol is not provided, the URL will be treated as a relative link and attempt to find the location in the current solution.



Dashboard Filtering


The Data Grid widget can be configured to act as a dashboard filter, using the underlying report's parameters as the filters and the data as the filter values. Use the Widget Editor to configure a Data Grid widget to act as a dashboard filter. Any visible field(s) can be set as the dashboard filter by checking the "Use as Filter" check box.


The columns (fields) that are configured to be used as filters will display the Ent-Data_Grid_Widget-Filter_Icon icon next to the column name in the grid header.


Selecting a data row in the Data Grid widget configured to be used as a dashboard filter will result in the filter column(s) being used as filter value(s) for the selected filter, and other widgets on the dashboard will filter their data in response to the filter value(s). The selected filter(s) and value(s) are displayed in the upper right corner above the data grid. In the image above, B-30 is the filter value for SYS_LOC_CODEs and all other widgets on the dashboard affected by the filtering will only display content associated with Location B-30.


Note: Refreshing the Data Grid widget will clear selected filtering values. The active filter (i.e., selected row) will also be removed if the user sorts or filters the data columns of the Data Grid widget or changes the pagination.


Once the Data Grid widget is configured to work as a dashboard filter, it will no longer respond to other filters on the dashboard. The Data Grid widget will also override any other filters (e.g., Filter-List widgets) set to the same parameter on the dashboard (i.e., the filtering functionality is not additive). For example, if the FACILITY_ID and SYS_LOC_CODE columns are configured to be used as a filter, the session facility and any SYS_LOC_CODE filter on the dashboard will be overridden when a data row is selected.