Tech Tip: Filter a Tree Grid View with Parameters

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.

The Goal

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.

  1. Navigate to Administration > Configuration > Query Definition and click Create New.
  2. Set the name to Part CAD Structure and context item type to Part, then click Save.
  3. Click the Show Editor button in the sidebar to open up the Query Builder UI.
  4. Build out the relationship structure.
    1. Right click the Part level and select Add Related Item > Using Relationship.
    2. Select CAD Documents and click Add.
    3. Right click CAD level and select Add Related Item > Using Relationship.
    4. Select Structure and click Add.
  5. Set the return properties for each level:
    1. Part: id, Part Number, name, generation, state
    2. Part CAD: Sequence
    3. CAD: id, Document Number, Gen, name, state
    4. CAD Structure: Sequence
  6. On the Part CAD and CAD Structure levels, set the order on the Sequence property.
  7. Make the CAD > CAD Structure > CAD part of the query recursive.
    1. Right click on CAD_1 (bottom level) and select Reuse Query Element Definition.
    2. In the dialog that appears, select the CAD level and click Add.
  8. Create a Parameter for the query.
    1. Click the Edit Parameters button in the toolbar.
    2. Click the New button in the Query Parameters dialog to define a new parameter.
    3. In the new parameter row enter the following:
      1. Name: cad_released
      2. Label: CAD Released
      3. Default Value: *
    4. Close the Query Parameters dialog to set the changes.
  9. Click the Filter button in the top CAD level.
  10. In the Where Condition tab, enter the filter: Released LIKE $cad_released.
    1. Note: You can reference your parameter in any filter using the $param_name syntax.
  11. 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

  1. Navigate to Administration > Configuration > Tree Grid View and click Create New.
  2. 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.
  3. Click the Show Editor button in the sidebar.
  4. Right click the Part row and select Map Element. Repeat for the top CAD row.
  5. Add any columns and data mappings you need. For this example I've added columns for name, generation, and state.
  6. Click the Show Parameter Mapping button in the toolbar.
  7. Check off Visible for the cad_released parameter in the Map Parameters dialog.
  8. 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.
  9. Click the green checkmark to save your changes and close the dialog.
  10. Save the Tree Grid View.

Set the Tree Grid View Usage

  1. To add the Tree Grid View to the context item type, click Actions > Set Tree Grid View Usage.
  2. In the dialog that appears, choose Relationship Tab as the Target Usage and click Next.
  3. Accept the default settings (new relationship on Part) on the next page and click Next.
  4. Enter CAD Structure as the tab label on the next page and click Next.
  5. Accept the default settings on the next page and click Next.
  6. 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.
  7. 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:

  1. Navigate to Design > Parts in the TOC.
  2. Open a part with a related CAD structure.
  3. Click on the CAD Structure tab. A collapsed view of the structure will render in the tab.
  4. Click the Grow button (green leaf) in the toolbar to expand the structure.
  5. To filter the structure based on release status, click the Modify Parameters button (white box with blue x) in the toolbar.
  6. 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.


Subscribe to our blog and follow @ArasLabs on Twitter for more helpful content! You can also find our latest open-source projects and sample code on the Aras Labs GitHub page.

  • Hi Eli, 

    I'm running into an issue when a child item is queried to show all of the parents. The resulting parents include the parent that we started with. Is there a way to filter this out?  So for example:

    A   --> (get all the children of A)

    -- B  (child of A)  --> (get all the parents of B)

        |__C (parent of B)

        |__  A (parent of B)  <---- this confuses the view, since the parent is already there at the higher level. 

  • This was very helpful.  I needed to exclude some items based on their field value.  This is what I used to accomplish that.

    [Change Item State] != 'Closed'