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

Stored Procedures

ChildLists provide the option to create a custom TSQL stored procedure to return and display data. When a stored procedure is not specified the default stored procedure ListInstances is used.

If you require a custom TSQL stored procedure then you can use the template below in the attached files section (ChildListTemplate.sql), simply update the name of the procedure, error handling, and add your custom select statement. Below is the required parameter list.

• ChildListTemplate
  • SessionGUID
  • UserGUID
  • CurrentInstanceGUID
  • TargetInstanceGUID
  • AdditionalInput

IMPORTANT NOTE:
It’s encouraged to include a Hierarchy column in your select statement. Without one you will lose some functionality if the childlist is accessed through a popup window. A notification will be displayed if this happens.

IMPORTANT NOTE:
If you intend to use a search component then you need to update your stored procedure to correctly parse the search parameters. Refer to the Search Components article and follow the instructions for the specific search component you intend to use.

If you require a TSQL stored procedure for the Create Stored Procedure field in the field definition, use the CreateTemplate.sql template found in the attached files section. Simply update the name of the procedure, error handling, and add your custom code. Below is the required parameter list.

• CreateTemplate
  • SessionGUID
  • UserGUID
  • CurrentInstanceGUID
    • This will contain the InstanceGUID of the form currently loaded.
  • TargetInstanceGUID
    • This will contain the InstanceGUID of the new form being created.
  • AdditionalInput

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.

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 database to get data for the childlist. This method will return a DataTable that contains the data returned from the database.

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, if a concept is being created the instance is created then a check to see if any Create TSQL is specified in the FieldDefinition parameter, if so it is executed. 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 TSQL stored procedure must be made for the childlist and added to its field definition if one doesn’t already exist. The stored procedure will need to be updated to correctly parse the search parameters and filter the data as required.

If a TSQL stored procedure doesn’t already exist for the childlist refer to the Stored Procedure section earlier in this article to learn how to create a new one.

If you’re creating a new TSQL stored procedure or one already exists for the childlist and you want to make it compatible with a search component, refer to the Search Components article and follow the instructions for 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.