13.4 Managing Trees

Trees to display hierarchical information in a clear, easy-to-use format. You can create a tree control using a SQL query.

• About Trees
  Tree controls in Oracle APEX use APEX Tree.
• Creating a Tree Using the Create Page Wizard
  Create a tree on a new page by running the Create Page Wizard.
• Creating a Tree in Page Designer
  Create a tree control by providing a SQL query that specifies a hierarchical relationship by identifying an ID and parent ID column in a table or view.
• Editing Tree Attributes
  Control tree behavior by editing region attributes and report Attributes.

13.4.1 About Trees

Tree controls in Oracle APEX use APEX Tree.

App Builder includes a built-in wizard for generating a tree hierarchical navigation mechanism. Trees are implemented using a single hierarchical query that identifies the row to be used as the start of your query and the relationship between parent rows and child rows of the hierarchy. Trees use the APEX Tree implementation. This is a JavaScript-based, cross browser tree component that features optional keyboard navigation, and optional state saving.

When you implement a tree control, the SQL query specifies a hierarchical relationship by identifying an ID and parent ID column in a table or view. The tree query must utilizes a START WITH .. CONNECT BY clause to generate the hierarchical query.

Tip:

The creation of APEX Tree regions is only supported on pages using a Desktop user interface.

About Desupported jsTrees

Prior to release 5.2, APEX supported the rendering of jsTree tree regions. APEX no longer supports jsTree tree regions. APEX now supports the generation of an APEX Tree tree region. APEX Tree is a JavaScript based, cross browser tree component. jsTree regions are automatically upgraded to APEX Tree regions when upgrading from a previous release or when importing to release 18.1.

Tip:

To view tree examples, install the sample app, Sample Trees. To learn more, see Installing Apps from the Gallery.

13.4.2 Creating a Tree Using the Create Page Wizard

Create a tree on a new page by running the Create Page Wizard.

A tree is based on a query and returns data that can be represented in a hierarchy. When you create a tree using the Create Page Wizard, the wizard generates the hierarchical query for you based on the options you select.

To create a tree on a new page:

1. On the Workspace home page, click the App Builder icon.
2. Select an application.
3. Click Create Page.

   Create a Page appears and features three tabs: Component, Feature, and Legacy Pages.

4. Under Component, select Tree.
5. Page Definition:
   1. Page Number - The page number is an integer value that identifies a page within an application.
   2. Name - Specify a text name for this page.

      Tip:

      This text is also used for page Title. After page creation, you can modify the Title in Page Designer.

   3. Page Mode - Identify the page mode. To learn more, see field-level Help.
6. Data Source - Select a Data Source for the page:
   1. Table/View Owner - Select the owner of the table on which you are building the page.
   2. Table/View Name - Select the table or view on which the page will be based. When entering manually, note that the table name is case sensitive.
7. Navigation - Expand the region and enable or disable navigation. If either flag is enabled, additional attributes appear. To learn more about an attribute, see field-level Help.
   1. Use Breadcrumb - Enable to create a breadcrumb entry for this page. By default, the page name is used as breadcrumb entry name.
   2. Use Navigation - Enable to create a navigation menu entry for this page.By default, the page name is used as navigation menu name.
8. Click Next.
9. Tree Attributes:

   A tree is based on a query and returns data that can be represented in a hierarchy. A start with .. connect by clause will be used to generate the hierarchical query for your tree. Use this page to identify the column you want to use as the ID, the Parent ID, and text that should appear on the nodes. The Start With column will be used to specify the root of the hierarchical query, and its value can be based on an existing item, static value or SQL query returning a single value.

   1. ID - Select the column to use as the ID. For example, select the EMPNO column for the EMP table.
   2. Parent ID - Select the column to use as the parent ID. For example, select the MGR column for the EMP table.
   3. Node Text - Select the text to appear on the tree nodes. For example, select the ENAME column for the EMP table.
   4. Start With - Select the column to be used to specify the root of the hierarchical tree query. For example, select the MGR column for the EMP table.
   5. Start Tree - Choose how to start your query. Options include:

      • Based on Existing Item - Select an existing application or page item.

      • Based on a SQL Query - Enter a SQL query that returns a single row or single column.

      • Based on a Static Value - Enter a static value.

      • Value is NULL.

   6. Click Next.
   7. Include Buttons - Select the buttons to include.
10. Click Create Page.
11. To view page, click Save and Run Page.
    The rendered page appears.

13.4.3 Creating a Tree in Page Designer

Create a tree control by providing a SQL query that specifies a hierarchical relationship by identifying an ID and parent ID column in a table or view.

The tree query you provide must utilizes a START WITH .. CONNECT BY clause to generate the hierarchical query.

To create a tree in Page Designer

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Click the Layout tab in the central pane.
3. In the Gallery, click the Regions tab. Right-click Tree and select Add To, and select the appropriate location.

   Tip:

   You can also select the Tree region in the Gallery and drag it to the appropriate location in the Layout tab.

4. Page Designer indicates what to do next. If there are errors, the Show Messages icon displays in the Page Developer toolbar.
   1. Click the Show Messages icon on the Page Designer toolbar.
      The Messages dialog displays errors that must be addressed.
   2. Select an error to highlight the associated attribute in the Property Editor.
5. Edit the Region attributes:
   1. In the Property Editor, select the Region tab (if not already selected).

      To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

   2. Identification, Title - Enter a region title. The region title only displays when it is defined in the region template.
   3. Under Source -

      • Location - Select the location of the data.

      • Type - Select how the data is queried.

      • Table Name - Enter the case-sensitive table or view name. You can type in the name or pick from the list.

      Depending upon your selections, additional attributes may appear.

   4. Under Layout -

      • Sequence - Enter the display sequence for this item. The sequence and other layout settings determine where this item is displayed in relation to other items within the region.

      • Parent Region - Select the parent region to which this region belongs. If a parent region is selected then this region is rendered completely inside the parent region.

      • Position - Select the template position used to display this region. The selections available are derived from the appropriate template positions defined within the current theme, for the page's user interface.

   5. Appearance, Template - Specify the template. Select a region template to define the appearance and layout of this region.
6. Edit the tree Attributes:
   1. In the Rendering tab, select the region and click Attributes tab.

      Tree Attributes display in the Property Editor.

      To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

   2. Under Settings:

      • Node Label Column - Select the data source column containing the value for the node label. The value cannot contain markup.

      • Node Value Column - Select the data source column containing the value for the node value. This value is not displayed but added to the tree adapter node id property that can be accessed using JavaScript.

      • Hierarchy - Indicate whether APEX should compute the tree hierarchy from the data or whether the data already contains all hierarchy information. The user interface changes depending upon your selection.

        • Computed With SQL:

          • Node ID Column – Select the data source column containing the ID for a node. This is required when the hierarchy is being computed by APEX. Typically, a primary key column is chosen here.

          • Parent Key Column – Select the data source column containing the value for the parent key of a node. Required when APEX computes the hierarchy.

        • Not Computed:

          • Node Status Column – Select the data source column containing the value for the node status. Required when the Hierarchy attribute is set to Not Computed. The column must contain 0 for leaf nodes and 1 for nodes with children.

          • Hierarchy Level Column – Select the data source column containing the value for the hierarchy level of the node. Required when the Hierarchy attribute is set to Not Computed.

      • Tooltip - Select whether tooltips are displayed, and the source for the tooltip.

      • Link - Specify the link to be executed when a node is clicked.

      • Link Column - Select the data source column containing the value for the link to be executed when a node is clicked.

      • Icon CSS Class Column - Select the data source column containing the value for the icon CSS class to be applied to the node.

7. Click Save.

13.4.4 Editing Tree Attributes

Control tree behavior by editing region attributes and report Attributes.

By default, a tree does not have focus and node links are activated with a single click action.

To access the Tree attributes:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Select the tree region in the Rendering tab or the Layout tab.

   The Property Editor displays attributes in the right pane. Attributes are organized in groups.

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

3. Edit Region attributes:
   1. In the Property Editor (right pane), select the Region tab.
   2. Edit attributes as needed.
4. Edit tree Attributes
   1. In the Property Editor (right pane), select the Attributes tab.
   2. Edit attributes as needed.
5. Click Save.