ChildList

The ChildList component is used to display various types of data in a grid format.

Childlists have the following features:

• Filtering/Sorting
• Creating a new record
• Visual appearance customization
  • Resize columns
  • Toggle column visibility
  • Toggle filters
  • Adjust page size
  • Adjust pager location
• Data exporting to Excel and CSV formats
• Advanced search using Search Components
• Saving/Loading custom childlist configurations defined by the user
• Executing commands/events/wizards

ChildLists can have a search component attached to it to provide greater flexibility in terms of displaying data. Learn more about available search components here or learn how to create your own search components here.

Along the top of the childlist there are two buttons, Grid Settings and Export Data. Both will open popup windows, screenshots can be seen below.

IMPORTANT NOTE:

The Grid Settings button is only visible if the Suppress Grid Settings element in the FieldDefinition parameter is set to No. The same is true for the Export Data button, it’s only visible if the Suppress Export Data element in the FieldDefinition parameter is set to No.

Grid Settings window:

Export Data window:

IMPORTANT NOTE: The settings and export windows are separate components used only by the ChildList component. Please view the the technical documentation for ChildList Settings and ChildList Export for more information on how they work.

Example Video

Targets

ChildLists provide the option to call a target to return and display data when using custom data. When not using custom data the ListInstances stored procedure is used, in this case a Child Concept Type needs to be specified.

Component Code

The code for the component is broken up into various regions to make it easier to navigate and follow along with this documentation.

Variables

This region contains all the variables, references, parameters, etc. that are used throughout the component. All are broken into their own sections by using comments to explain their purpose within the component.

Initialization

OnParameterSetAsync()

This method is called when the component initializes and when the parent component is updated. It’s purpose is to assign values to variables and populate the grid with data.

This method also checks the value of the FieldDefinitionGUID, this check allows us to know if the user has changed tabs or not so grid data and properties can correctly be set in as few API calls as possible.

SetupAutoRefreshTimer()

This method is called when data auto refresh is enabled and will configure a timer to refresh the data.

IDisposable.Dispose()

This method is called when the component is disposed to additionally dispose the auto refresh timer.

Grid Data

ReadItems(GridReadEventArgs args)

This is the method that’s called when any CUD (Create, Update, Delete) operation is performed on the grid. This allows us to have more control over the grid by performing manual data source operations.

This method is used to bind your data to the grid for it to be displayed and capture the total number of results in the dataset.

Follow this link to view Telerik’s official documentation that dives into the lower-level functions of the OnRead event and the different CUD operations.

GetChildListData()

This method is used to call the target to get data for the childlist. This method will return a DataTable that contains the data returned from the target.

Other than getting the data for the childlist this method also gets the gets the remaining settings and column data.

GetColumnData()

This method is used to populate the ColumnList variable. It will attempt to pull column data from the GridXML variable which will either be equal to the FieldUX parameter or will be a grid configuration the user previously created, regardless both have the same XML structure and the column data will be pulled accordingly.

If no column data is found then a call is made to SetupInstanceNameColumn() where a single column will be created and displayed on the childlist.

GetChildListSettings()

This method is used to setup some properties on the childlist, specifically the number of items on the current page and if filters are enabled.

Grid Columns

AddColumnToColumnList(ColumnDefinition column)

This method accepts a ColumnDefinition object and adds it to the columnList list of ColumnDefinitions if it’s not a duplicate entry.

SetupInstanceNameColumn()

This is called when no column definitions were found in the field definition. Here a single column is generated and added to ColumnList, its name will be the value of the ListConcepts element in the FieldDefinition parameter if it’s specified, otherwise it defaults to InstanceName.

Grid Rows

OnRowRenderHandler(GridRowRenderEventArgs args)

This method is called each time a row is rendered in the grid. It’s used to indicate if the row is clickable or not by checking the value of the AllowRowClick element in the FieldDefinition parameter. If the row is clickable a CSS class is added so when the user hovers over the row with their cursor it turns into a pointer, view example below.

Clickable row:

Non-Clickable row:

OnRowSelect(IEnumerable<Dictionary<string, object>> selectedRow)

When any row is selected this method is called.

This method includes an anti-spam mechanism to prevent the user from making multiple API calls before the first call has finished processing. Inside that mechanism there are four checks made before any action is performed in the following order: 

1. Check that a valid row was selected 

2. Ensure the AllowRowClick permission is true 

3. Make sure the selected row contains an InstanceGUID 

4. The current page is valid (No fields have validation errors) 

If all the checks pass, then it attempts to navigate the user to the selected rows instance page using the InstanceGUID tied to the selected row.

IMPORTANT NOTE:
If the instance is in a popup window and a row is selected there are additional checks made that validate the initial instance loaded in the window is part of the selected instances hierarchy. If it’s not part of the same hierarchy the instance is not loaded.

In other words, if your childlist contains a list of (for example) contracts and you click contract A, it attempts to load contract A’s instance.

On top of this the selected row is also highlighted a different color to indicate the row was selected regardless of if the checks above passed or failed, this helps avoid confusion if the new instance is taking a while to load so the user is aware their selection was made and is being processed.

Grid Toolbar

RefreshButtonOnClickHandler()

This is called every time the refresh button is selected. It will call GetChildListData() to get the latest data then rebind the data to the grid. A notification is also displayed to the user once the operation completes.

AddNewItemClicked()

This method is called when the add new item button is selected. It saves the current instance then checks if a wizard is launching or a concept is being created. If a wizard is launching then the wizard is opened. Finally the user is automatically navigated to the new instance if a concept was created.

Grid Settings

ConfigurationUpdated()

This method is called when a new configuration is saved from the settings window. It will update the ChildListConfiguration, GridXML, and Data variables and rebind the updated data to the childlist.

DisposeSettingsWindow(DotNetObjectReference<GI_ChildList_Settings> settingsWindowObjRef)

This method is called when the settings window is closed so the settings component can be disposed.

Grid Export

UpdateGridForExport(Dictionary<string, object> gridDetails)

This method is called from the export window to update the grid so the data can be exported. It will update the grids page size and state or potentially reset the grid back to its default state after modifying it in the export window.

DisposeExportWindow(DotNetObjectReference<GI_ChildList_Export> exportWindowObjRef)

This method is called when the export window is closed so the export component can be disposed.

Right-Click Menu

OnContextMenu(GridRowClickArgs args)

This is called when a user right clicks on a row. First, it ensures the row is an instance that can be navigated to by making sure the row has an InstanceGUID tied to it. If an InstanceGUID is found, it attempts to load that instance in the PopupForm of the AppState which the user cannot see. To the user it looks like something is processing in the background.

Once it successfully loaded the instance, it fetches all the available events, commands, and wizards for that instance that are available in its current state and visible with the user’s permission level. All the data is then displayed in the right-click menu that appears in the position the user right clicked.

If no commands, events, or wizards were found a message is displayed in the right-click menu that no commands were found.

If the current instance is not loading in a popup window then an additional option will be added to the right click menu, Open Instance which will open the selected instance in a popup window.

No commands, events, or wizards found:

Events/commands/wizards found:

Additionally, an Open In Window button will be added to allow you to open the instance in a popup window. A Delete option will also be added if the user has permissions and the instance can be deleted.

OnRightClickMenuItemClicked(RightClickMenuItem item)

This method is called when an item in the right-click menu is selected.

If the Open Instance option was selected then the selected instance will be loaded into a popup window.

If the Delete option was selected then the selected instance will be deleted.

Otherwise, a command/event/wizard was selected so a check is made to see if the item has a confirmation prompt, if so it is displayed. If the user accepts the confirmation prompt or there is none then the selected instance is saved and the command, event, or wizard is executed.

Once execution has complete the childlist on the current instance has its data refreshed. If a wizard was selected then once the wizard is closed the data on the childlist will be refreshed

DisposeInstanceWindow(DotNetObjectReference<InstanceWindow> instanceWindowObjRef)

This method is called when the instance window is closed so the instance window component can be disposed. The childlist data is also refreshed and bound since the data could of changed.

DisposeWizard(DotNetObjectReference<Wizard> wizardObjRef)

This method is called when the wizard is closed so the wizard component can be disposed. The childlist data is also refreshed and bound since the data could of changed.

DeleteInstanceResponse(bool wasInstanceDeleted)

This method is called as an event callback from the Delete components. Its purpose is to determine if the instance was actually deleted, if it was refresh the childlist, otherwise display an error notification.

Advanced Search

IMPORTANT NOTE:
To use the advanced search functionality, a target must be specified for the childlist and added to its field definition if one doesn’t already exist. The target will need to correctly parse the search parameters and filter the data as required based on the specific search component you intend to use.

UpdateSearchParameters(XElement searchParams)

This is the method that is triggered from the OnSearchButtonPress event that is invoked from all search components when the Search button is selected. When the event is captured, an XElement is received that contains all the search parameters from the search component. 

In this method it assigns our searchParameters variable to the value of searchParams, gets the data for the childlist, and binds the data.