This guideline describes a set of hierarchy conditions that you can add to the condition choice list of a search field when the data that users search for is hierarchical. The guideline also provides guidance about how to display hierarchy search results.

Note: Images used in this guideline are provided as general references. They are not exact representations of Applications Development Framework (ADF) pages.

When hierarchy search conditions are available, the condition choice list should be visible by default. Use ADF Query Basic View, not ADF Quick Query. For more information, see the Search and Query Usage Guidelines. You can use any of the Transactional Search Design Patterns for the search.

The searchable fields must include:

• Tree Node

  The prompt for the search field must be the name of the object that each tree node represents. For example, if tree nodes represent employees, the prompt for the search field should be Employee Name. See figure 1.

  Note: ApplCore provides a Tree Picker. Use it for all tree node search fields. All select tree node illustrations in this guideline represent the ApplCore tree node picker.
• Tree Node Label

  If you are using Oracle Fusion Tree Management and have the Labels function enabled, the Labels field must be searchable. The prompt for the field must be the name of the attribute that the label represents. For example, if tree node labels represent positions, the search field is labeled "Position" (see figure 1).

Figure 1. Tree node and label in search region

Figure 2. Tree node and label in search results

You have three different options to display hierarchy search condition terminology to users:

• Family terminology
• Domain-specific terminology
• Tree terminology

Family Terminology

Family terminology provides a set of seven different conditions. Some family condition names can be confusing if used standalone. For example, "Is a last descendant of node" may not make sense when used on its own. Use family terminology when users must access several levels of a hierarchy and need to use a majority of these terms.

Not all of these conditions are required in the condition choice list. Use the ones that are applicable to your use cases:

• Is a child of node
• Is a descendant of node
• Is a last descendant of node
• Is a parent of node
• Is an ancestor of node
• Is a first ancestor of node
• Is a sibling of node

Figure 3. Sample hierarchy: Chart of Accounts

Table 1. illustrates the search results of each of the family terminology conditions. For a more detailed diagram, click the link for each of the family terminology conditions.

The following steps are illustrated in figure 4:

1. Users select a hierarchy condition in a search field.
2. Users open the tree picker and select the desired tree.
3. Users click Show Tree Nodes to open the tree node picker and select the desired node. (Note that this step is not illustrated in figure 4.)
4. Results appear to users in a flat table.

Figure 4. Complete example of a search for all children of a tree node

Domain-Specific Terminology

Use domain-specific terminology when you are certain it is familiar to the majority of your users. For example, when searching for an employee of a specific manager, use a condition such as “Is an employee of person” instead of “Is a child of node,” which is the less familiar family term.

Table 2 illustrates domain-specific hierarchy conditions. For a more detailed diagram, click the link for each of the family terminology condition.

Tree Terminology

Tree terminology provides a set of eight conditions, such as, "Is a leaf node" and "Is the root node." Use tree terminology when domain-specific terminology is not appropriate and when tree terminology is the most familiar terminology for users.

Table 3 illustrates the relationship between family and tree terms. For a more detailed diagram, click the link for each of the family terminology condition.

The following conditions are selection-independent. Selecting one of these conditions hides the value field (see figure 5). Selection-independent searches do not need a value in the hierarchy to compare to execute the search.

Table 4 lists selection-independent hierarchy conditions.

When users select a selection-independent hierarchy condition the value field is hidden.

Figure 5. Selection-independent condition: Is a leaf node

When users select a selection-dependent hierarchy condition the value field remains visible.

Figure 6. Selection-dependent condition: Is a leaf node under node

This section explains the default search conditions that appear in conventional searches, hierarchy searches, and conventional and hierarchy searches.

Conventional Search Defaults

Typical focused search default conditions include Starts with, Contains, or Equals depending on the field type. For a list of default conditions by search field data type, see the Search and Query Usage guidelines.

Figure 7. Default condition list for character fields

Hierarchy Search Defaults

The recommended hierarchy search default is to use the most common search condition for the particular task as the default. This default may differ from task to task.

For example, if the most common task in this hierarchy search example task is to find the child of an account in the hierarchy, then the default value should be Is a child of node.

Figure 8. Select the default hierarchy condition based on common use cases

Combined Conventional and Hierarchy Search Conditions

When you combine conventional and hierarchy search, group conditions by type of search. For example, group conventional search conditions together, such as Starts with, Ends with, Equals, and Contains. Then group the hierarchy search conditions together, such as Is a child of node, Is a descendant of node, and so on.

Figure 9. Combined conventional and hierarchy condition list

You can present the results of a hierarchy search in four format options:

• Results Marked in a Tree Table
• Results and Their Ancestors in a Tree Table
• Flat Table and Path
• Flat Table

To illustrate these four hierarchy search results options, this guideline uses the example of an organizational chart as the tree to be searched (figure 10). Figure 11 shows the results of the search: “Employee Name starts with K.”

Key differences between hierarchy search and flat table search include switching between flat and hierarchical views of the data (in three of the four results patterns) and the display of the "No results found" message (figure 12). In all four patterns, the "No results found" message shouldappear in a message dialog box, rather than clearing the tree table and displaying the message within the table body so that users can simply dismiss the dialog box to continue browsing the hierarchy.

Figure 10. Sample hierarchy: Organization chart

Results Marked in a Tree Table

In this option, the full hierarchy appears with nodes expanded to show matching records. Matching records are indicated using an icon

This results display is often preferred by users but produces the slowest performance. Use this display when the hierarchy is small, and it is important for users to see matching nodes in the context of their peers and descendants as well as that of their ancestors. This display (figure 11) is also preferred when most use cases involve searching for multiple target records per query.

The full hierarchy remains available within the tree table whether or not any tree nodes match the user's query. If there are no matching tree nodes, place the "No results found" message in a dialog box. Do not clear the tree table, and place the "No results found" dialog box in the table body (see figure 12).

Figure 11. Full hierarchy: Organization chart

Figure 12. Error message appears and previous highlights are cleared when no results are returned

Results and Their Ancestors in a Tree Table

In this option, search results appear in a tree table. Matching records appear as leaf nodes under their ancestors.

Users can select a matching record and click View in Hierarchy to see the selected record highlighted within the full tree.

This results display (figure 13) typically produces acceptable usability and adequate performance. Use this display when users require some context that can be adequately provided by displaying the ancestor nodes when viewing search results. This display works well when most of the use cases involve searching for a single target record.

Figure 13. Matching nodes and their ancestors in a tree table

Flat Table and Path

In this option, search results appear in a flat table along with a list of their ancestors in path or breadcrumb form.

Users can select a matching record and click View in Hierarchy to see the selected record highlighted within the full tree.

This results display (figure 14) provides the same amount of hierarchy context as the Results and Their Ancestors in a Tree Table display but in a less usable form. Use this design only if the listed path is short in the large majority of cases.

Figure 14. Matching records with their ancestors in a flat table

Flat Table

Matching nodes appear in a flat table without information regarding where they appear in the hierarchy. Users can add other relevant attributes, such as Label, to the results table.

Users can select a matching record and click View in Hierarchy to see the selected record highlighted within the full tree.

This results display (figure 15) provides no hierarchy context for result items, but it supports the display of additional node attributes better than the other alternatives. Use this display only if users do not need to see hierarchy context for matching nodes.

Figure 15. Results in a flat table with no hierarchy context

View in Hierarchy

When search results appear in a flat table (that is, Results and Their Ancestors in a Tree Table, Flat Table and Path, and Flat Table), place a View in Hierarchy button on the toolbar of the results table (see figure 16). When users select a result item, then click View in Hierarchy, the results table is replaced with a tree table. The selected item's parent (if one exists) appears as the root note, and the tree is expanded to display the children of the selected result item (if any exist).

If users have not selected a row, the View in Hierarchy button is unavailable. Note that the results table should not support multiple selection.

Figure 16. View in hierarchy interaction

Each of the following examples use one of three sample hierarchies: an organization chart, a geography hierarchy, and a chart of accounts. Each example shows:

• A hierarchy condition in a sample search panel
• A node selected from a hierarchical Search and Select dialog box with search results in a tree table
• Nodes that match the search criteria highlighted in yellow

Note: In this document, when hierarchy conditions appear as section headers, they appear in headline capitalization. However, when you use these conditions in a search, they should appear in sentence capitalization. For more information, see Language in UI: Capitalization.

Conditions That Use Family Terminology

You do not need to include all of these conditions in the condition choice list. Use only the ones that are applicable to your use cases:

• Is a Descendent of Node
• Is a Last Descendent of Node
• Is a Child of Node
• Is an Ancestor of Node
• Is a First Ancestor of Node
• Is a Parent of Node
• Is a Sibling of Node

Is a Descendent of Node

This condition displays all tree nodes under the selected node, children, grandchildren, and so on to the leaf nodes.

Figure 17. Descendant of a node hierarchy condition

Is a Last Descendent of Node

This condition displays all leaf nodes under the selected node.

Figure 18. Last descendant of a node hierarchy condition

Is a Child of Node

This condition displays all nodes directly under the selected node.

Figure 19. Child of node hierarchy condition

Is an Ancestor of Node

This condition displays all nodes above the selected node, parents, grandparents, and so on up to the root node.

Figure 20. Ancestor of node hierarchy condition

Is a First Ancestor of Node

Is the root node or nodes above the selected node in a multiroot hierarchy? Is the root node in a single root hierarchy? If so, you should hide the value field. For more information, see the Is the Root Node condition in this guideline.

Figure 21. First ancestor of node hierarchy condition

Is a Parent of Node

This condition displays a node directly above the selected node in multiparent hierarchies.

Note: Name this condition Is the parent of node when it is used with single-parent hierarchies.

Figure 22. Parent of node hierarchy condition

Is a Sibling of Node

This condition displays all nodes that are peers of (that is, have the same parent as) the selected node.

Figure 23. Sibling of node hierarchy condition

Conditions That Use Tree Terminology

You do not need to include all of these conditions in the condition choice list. Use only the ones that are applicable to your use cases:

• Is a Member of Branch
• Is a Leaf Node
• Is a Leaf Node Under Node
• Is the Root Node

Is a Member of Branch

This condition displays the selected node, all nodes under it, children, grandchildren, and so on to the leaf nodes.

Figure 24. Member of branch hierarchy condition

Is a Leaf Node

This condition displays all leaf nodes (the last nodes in each branch) in the tree including all last descendants of the root node.

Figure 25. Leaf node hierarchy condition

Is a Leaf Node Under Node

This condition displays all leaf nodes under the selected node and is equivalent to the Is a last descendant of node condition.

Figure 26. Leaf node under node hierarchy condition

Is the Root Node

The root node is the top-most node in a single root tree.

Note: The condition should be Is a root node for trees with multiple root nodes and requires a value field if you include multiparent nodes. For more information, see the Is a First Ancestor Node condition.

Figure 27. Root node hierarchy condition

Conditions That Require Metadata

You do not need to include all of these conditions in the condition choice list. Use only the ones that are applicable to your use cases:

• Is a Member of the Level
• Has the Label

Is a Member of the Level

This condition displays all nodes that are the same distance from the root node in a level-based hierarchy. A level-based hierarchy is a hierarchy in which all nodes at the same distance from the root node are logical peers and have the same label.

Figure 28. Member of the level hierarchy condition

Has the Label

This condition displays all nodes that have the specified developer-defined label.

Figure 29. Label hierarchy condition