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 Application Express use APEX Tree.
• Creating a Tree on New Page
  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 Application Express 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, Oracle Application Express supported the rendering of jsTree tree regions. Oracle Application Express no longer supports jsTree tree regions. Oracle Application Express 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 Sample Apps.

13.4.2 Creating a Tree on New Page

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.
4. For Create a Page:
   1. User Interface - Select a user interface for the page (optional).
      This attribute only displays for applications using older themes and for which Desktop and Mobile User Interfaces have been defined.
   2. Select a page type - Select Tree.
5. For Page Attributes, specify the following:
   1. Page Number - Specify the page on which the tree should be created.
   2. Page Name - If the tree will be created on a new page, enter the page name.
   3. Page Mode - Select a page mode.
   4. Page Group - Select the name of the page group you would like to associate with this page. This option will only be visible when the application contains groups.
   5. Region Template - Select a region template for the tree region.
   6. Region Name - Enter a name for the region to contain the tree.
   7. Breadcrumb - Select whether you want to use a breadcrumb navigation control on your page, and which breadcrumb navigation control you want to use. If you select Breadcrumb, enter the following:

      • Entry Name - Enter a name for the breadcrumb entry.

      • Select Parent Entry - Select a parent entry.

   8. Click Next.
6. For Navigation Preference:
   1. Select how you want this page integrated into the Navigation Menu. To learn more, see field-level Help.
   2. Click Next.
7. For Table/View Owner and Name:
   1. Table/View Owner - Select the owner of the table from which the tree will be based.
   2. Table / View Name - Select the table or view which contains the columns to be included in the master page.
   3. Click Next.
8. For Query, identify the column you want to use as the ID, the Parent ID, and text that should appear on the nodes:
   1. ID - Select the column to use as the ID.
   2. Parent ID - Select the column to use as the parent ID.
   3. Node Text - Select the text to appear on the tree nodes.
   4. Start With - Select the column to be used to specify the root of the hierarchical tree query.
   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.
9. For Where and Order by, specify the following:
   1. Where Clause - Enter a WHERE clause. To learn more, expand Current Query.
   2. Order Siblings By - Select the order siblings by column, such as ENAME. The default value is based on the Node Text column selected.
   3. Click Next.
10. For Tree Attributes, specify the following:
    1. Include Buttons - Select the buttons to include.
    2. Selected Node Page Item - Select the page or application item to hold the selected node value. This item can be used to save the tree state, by holding the value of the last selected node. The value of the selected node can be saved to the selected item using the node link attribute or a page process. When the tree is reloaded, the tree opens to the last selected tree node.
    3. Tooltip - Displays a tooltip when the mouse hovers over a leaf node. Options include:

       • Static Assignment - Specifies a static value to be used as the tooltip text. Substitution strings can be used in the static text, to incorporate information from the SQL query in the tooltip text. The following substitution strings can be used:

         #VALUE# - refers to the value of ID column.

         #TITLE# - refers to the value of Node Text column.

         #LINK# - refers to the value of Link option.

       • Database Column - Select the column to use as the tooltip text.

    4. Link Option - To make leaf node text a link, choose Existing applications item and click Next.
       Existing Application Item makes the leaf node text a link. If you select this option, you must specify a page to link to and an existing application item to link leaf node text.
11. Confirm your selections and click Create.

    Tip:

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

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 Application Express 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 Application Express. 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 Application Express 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.