15.6 Creating Trees

This section describes how to create tree components in Application Builder.

About Trees
About Support for Legacy jsTrees
Creating a Tree on New Page
Managing Trees in Page Designer
Managing Trees in Component View

Tip:

In Oracle Application Express release 5.0, you can continue to edit existing jsTree regions, but no longer have the ability to create them. See "About Trees."

15.6.1 About Trees

Application Builder includes a built-in wizard for generating a tree that displays a hierarchical view. With Oracle Application Express release 5.0, trees use a new APEX Tree implementation. Like the legacy jsTree region, this new tree implementation is a Javascript-based, cross browser tree component that features optional keyboard navigation, and optional state saving. The APEX Tree shares the same functionality as jsTree, with the exception that the Template attribute does not apply to the new tree. The look, usability, and accessibility is also improved with the new implementation. You can continue to edit existing jsTree regions, but no longer have the ability to create them.

You can create a Tree from a query that specifies a hierarchical relationship by identifying an ID and parent ID column in a table or view. The tree query 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.

15.6.2 About Support for Legacy jsTrees

Previous releases of Oracle Application Express supported the creation of jsTree tree regions. Although existing trees are still supported, Oracle Application Express no longer supports the creation of 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, similar to jsTree.

15.6.3 Creating a Tree on New Page

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 wizards generates this hierarchical query for your based on the options you select.

To create a tree on a new page:

On the Workspace home page, click the Application Builder icon.
Select an application.
Click Create Page.
For Create a Page:
1. User Interface - Select Desktop.
2. Select a page type - Select Tree.
3. Click Next.
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.
For Navigation Preference, specify the type of navigation to include on this page and click Next. The navigation options (for example, navigation menu or tabs) depends upon the current application theme.
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.
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.
For Where and Order by, specify the following:
1. Where Clause - Enter an optional WHERE clause. For example:
```
ename='JONE'
```
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.
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:
  - 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.
    
    This option only appears if you select the Existing Application Item link option.
  - Nothing
5. Click Next.
Confirm your selections and click Create.

Tip:

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

15.6.4 Managing Trees in Page Designer

This section describes how to manage trees in Page Designer.

Creating a Tree in Page Designer
Editing Tree Attributes in Page Designer

15.6.4.1 Creating a Tree in Page Designer

To create a tree on an existing page:

Navigate to the appropriate page in Page Designer. See "Viewing a Page in Page Designer."

Page Designer appears
From the Gallery select the Tree region and drag it to the appropriate location in Grid Layout.

Tip:
You also right-click Tree region, select Add To, and select the appropriate location.

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.
View all attributes in the Property Editor. Select Show All from the Property Editor Menu.
Edit the region attributes:

Tip:
To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.
1. Identification - Enter a title for the region.
2. Source - Enter the SQL query underlying the tree. The query must be in the following format:
```
SELECT status, level, name, icon, id, tooltip, link 
FROM ... 
WHERE ... 
START WITH... 
CONNECT BY PRIOR id = pid 

ORDER SIBLINGS BY ...
```
  Note:
  The STATUS column of the tree SQL query is used by our tree logic in the rendering of the appropriate JSON data source for the tree, and should not be modified.
  
  Consider the following example:
```
SELECT case WHEN connect_by_isleaf = 1 THEN 0 WHEN level = 1 THEN 1 ELSE -1 END as status,
       level,
       ename as title,
       'icon-tree-folder' as icon,
       empno as value,
       ename as tooltip,
       NULL as link
FROM emp
START WITH mgr IS NULL
CONNECT BY PRIOR empno = mgr
ORDER SIBLINGS BY ename
```
  Note:
  By default, a new APEX Tree will be created, using CSS class 'icon-tree-folder' to represent the image on the tree. If you are creating a jsTree (Legacy) tree implementation, an image reference should be used in place of the CSS class in the above example, you would replace 'icon-tree-folder' with '#IMAGE_PREFIX#go-small.png'.
3. Layout - Specify the Sequence, Parent Region, and Position.
4. Appearance - Specify the template.
Select the region Attributes in the Rendering tree.

The Property Editor displays attributes for the tree.
View all attributes in the Property Editor. Select Show All from the Property Editor Menu.
Edit the tree attributes:
1. Tree Implementation - Select how the tree should be implemented, either APEX Tree or jsTree (legacy).
2. Tree Template - Select the template to apply to the tree from the available jsTree template options. This option is only applicable to jsTree regions.
3. Activate Node Link With - Select the action required to activate node links on your tree.
4. Selected Node Page Item - Select the page or application item that you wish to hold the selected node value.
5. Tooltip - Select whether tooltips are displayed, and the source for the tooltip.
6. Static Tree ID - Enter the unique identifier for the tree.
7. Icon Type - A CSS class used to specify the type of icons used for all nodes. This option is only applicable to APEX Tree regions.
Click Save.

15.6.4.2 Editing Tree Attributes in Page Designer

By default, a tree does not have focus and node links are activated with a single click action. This section describes how developers can customize a tree by editing tree attributes.

To access the Tree attributes page:

Navigate to the appropriate page in Page Designer. "Viewing a Page in Page Designer."

Page Designer appears.
Select the region in the Rendering tree or Grid Layout.

The Property Editor displays attributes for the tree region.
View all attributes in the Property Editor. Select Show All from the Property Editor Menu.
Edit the region attributes:

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

15.6.5 Managing Trees in Component View

This section describes how to manage trees in Component View.

Creating a Tree in Component View
Editing Tree Attributes in Component View

15.6.5.1 Creating a Tree in Component View

To create a tree in component view:

Navigate to the page. See "Viewing a Page in Component View."
Under Region, click the Create icon.

The Create Region Wizard appears.
Select Tree and click Next.
For Display Attributes:
1. Title - Enter a title for the region. This title displays if the region template you choose displays the region title.
2. Region Template - Choose a template to control the look of the region.
3. Parent Region - Defines the parent region to which the new region belongs to.
4. Display Point - Identify a display point for this region. Two types of display points exist: page template positions and page body positions. To learn more about an attribute, see field-level Help.
5. Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.
6. Click Next.
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.
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.
For Where and Order by, specify the following:
1. Where Clause - Enter an optional WHERE clause.
2. Order Siblings By - Select the columns by which siblings are ordered.
3. Click Next.
For Tree Attributes, specify the following:
1. Include Buttons - Select the buttons to include.
2. Selected Node Page Item - Can be used to hold the selected node value. If you select an application item, you can use this item to save the tree state, by holding the last selected node of the tree.
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:
  - 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.
    
    This option only appears if you select the Existing Application Item link option.
  - Nothing
5. Click Next.
Confirm your selections and click Create Region.

15.6.5.2 Editing Tree Attributes in Component View

By default, a tree does not have focus and node links are activated with a single click action. This section describes how developers can customize a tree by editing tree attributes.

To access the Tree Attributes page:

Navigate to the appropriate page. See "Viewing a Page in Component View."
Access the Region Attributes page. Under Regions, click the Tree link next to the name of the tree region you want to edit.

Edit the appropriate attributes.

Tip:
To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."
Click Apply Changes.