Tree Grid Views are a great way to visualize hierarchical data in the Aras Innovator web client, however sometimes they can contain a lot of data. To help users hone in on the most meaningful data in a Tree Grid View, we can define parameters. These parameters allow users to update the query that populates the Tree Grid View. In this post, we'll walk through how we can use a parameter to implement a filtering effect for our end users.
This walk-through assumes a basic familiarity with Query Builder, Query Definitions, and Tree Grid Views. If you're new to any of these features or you just want a quick refresher, check out our previous blog post, An Introduction to Query Builder and Tree Grid View.
For this walk-through, we are going to create a simple Tree Grid View that displays related CAD structure in a relationship tab on a Part. We will also define a parameter that will allow the user to filter the related CAD items by release status. The final result will look something like this:
Demo: Using parameters in a tree grid view
Setting Up The Query Definition
In order to build a new Tree Grid View, we first need a Query Definition. The Query Definition lets us define the query structure and the output that is displayed by the Tree Grid View.
- Navigate to Administration > Configuration > Query Definition and click Create New.
- Set the name to Part CAD Structure and context item type to Part, then click Save.
- Click the Show Editor button in the sidebar to open up the Query Builder UI.
- Build out the relationship structure.
- Right click the Part level and select Add Related Item > Using Relationship.
- Select CAD Documents and click Add.
- Right click CAD level and select Add Related Item > Using Relationship.
- Select Structure and click Add.
- Set the return properties for each level:
- Part: id, Part Number, name, generation, state
- Part CAD: Sequence
- CAD: id, Document Number, Gen, name, state
- CAD Structure: Sequence
- On the Part CAD and CAD Structure levels, set the order on the Sequence property.
- Make the CAD > CAD Structure > CAD part of the query recursive.
- Right click on CAD_1 (bottom level) and select Reuse Query Element Definition.
- In the dialog that appears, select the CAD level and click Add.
- Create a Parameter for the query.
- Click the Edit Parameters button in the toolbar.
- Click the New button in the Query Parameters dialog to define a new parameter.
- In the new parameter row enter the following:
- Name: cad_released
- Label: CAD Released
- Default Value: *
- Close the Query Parameters dialog to set the changes.
- Click the Filter button in the top CAD level.
- In the Where Condition tab, enter the filter: Released LIKE $cad_released.
- Note: You can reference your parameter in any filter using the $param_name syntax.
- Save the Query Definition. It should look something like this:
Setting Up The Tree Grid View
Now that the Query Definition is complete, we can create the Tree Grid View.
Define the Tree Grid View
- Navigate to Administration > Configuration > Tree Grid View and click Create New.
- Set the name and Query Definition to Part CAD Structure, then click Save.
- Note: Tree Grid Views don't have to have the same name as their Query Definitions, it's just my personal preference.
- Click the Show Editor button in the sidebar.
- Right click the Part row and select Map Element. Repeat for the top CAD row.
- Add any columns and data mappings you need. For this example I've added columns for name, generation, and state.
- Click the Show Parameter Mapping button in the toolbar.
- Check off Visible for the cad_released parameter in the Map Parameters dialog.
- Set the parameter's data type to String.
- Note: The is_released property is actually a boolean property, but we want to treat it like a string for this scenario so the user can enter a wildcard and retrieve all items.
- Click the green checkmark to save your changes and close the dialog.
- Save the Tree Grid View.
Set the Tree Grid View Usage
- To add the Tree Grid View to the context item type, click Actions > Set Tree Grid View Usage.
- In the dialog that appears, choose Relationship Tab as the Target Usage and click Next.
- Accept the default settings (new relationship on Part) on the next page and click Next.
- Enter CAD Structure as the tab label on the next page and click Next.
- Accept the default settings on the next page and click Next.
- The next page of the dialog shows the configuration for the new relationship tab that will be created to show the Tree Grid View. Click Generate.
- Once the view is generated, close the dialog.
Using the Parameter
Now we have a Query Definition to get our data, we have a Tree Grid View to display our data, and we have a parameter in place to filter the data. Let's see how to use it:
- Navigate to Design > Parts in the TOC.
- Open a part with a related CAD structure.
- Click on the CAD Structure tab. A collapsed view of the structure will render in the tab.
- Click the Grow button (green leaf) in the toolbar to expand the structure.
- To filter the structure based on release status, click the Modify Parameters button (white box with blue x) in the toolbar.
- Change the default value of the cad_release parameter to 1 and click the green check mark to submit your change. This will display only released CAD documents in the related structure.