14.4 Managing 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.

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

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.

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.

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. Then, right-click Tree, 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.

   Page Designer indicates what actions are required next.

   The Messages tab displays a red or yellow badge indicating messages you need to address. The Message tab displays two types of messages:

   • Errors - Error messages display in red. Selecting an error message displays the associated attribute in red in the Property Editor. You must address errors before a page can be saved.

   • Warnings - Warning messages display in yellow. Selecting a warning message displays the associated attribute in yellow in the Property Editor. You must address errors before a page can be saved. Note you can save a page without addressing warning messages.

4. In either the Rendering tab or the Layout tab, select the new tree region.

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

5. To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

6. In the Property Editor, edit the attributes:

   1. Identification, Title - Enter a region title. The region title only displays when it is defined in the region template.

   2. For Source, select one of the following:

      • Local Database - Data is sourced from the local database.

      • Remote Database - Data is sourced from a remote database, where the connection is defined using REST Enabled SQL.

      • Web Source - Data is sourced from a RESTful web service defined using Web Source Modules.

   3. Layout - Edit the attributes:

      • 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.

   4. Appearance, Template - Specify the template. Select a region template to define the appearance and layout of this region.

      To learn more, click the Help tab in the central pane.

7. Edit the region Attributes:

   1. In the Rendering tab, locate the region and click Attributes.

      The Property Editor displays the Attributes.

   2. In the Property Editor, edit the region Attributes:

      • 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.

        • 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.

8. Click Save.

Developers can customize tree behavior by editing 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 region containing the tree in the Rendering tab or the Layout tab.

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

3. To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

4. Edit the tree attributes.

   Edited attributes display a blue marker to the left of the attribute name until the page is saved.

   Tip:

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

5. Click Save.