1 Introduction

The tree component can be used to display hierarchical data. This tree displays its data vertically, with every node of the tree corresponding to one ResultSet record. A node can either be a leaf or a branch. Every deep level will be loaded asynchronously, meaning a tree only loads one level at the start. The user can click on the branch expand/contract icon to toggle the visibility of child nodes. If the node is expanded for the first time, the tree will make a request to the server to get child nodes.


Tree component can be used in Axional Forms. It can be related to users in various ways:

  • Selecting the node:
    • There are two types of selection: multiple or single.
    • Selection results can be used in a function (javascript or XSQL script) to perform actions (delete nodes, update values, etc.).
  • Clicking on link node:
    • Axional Object can be opened by filtering columns with node record values.
    • Node can be in a javascript function. It is possible to perform actions like loading an SQL Table.

To begin with, SQL Tree requires the basic Axional Studio infrastructure, which includes:

  • Axional Studio Server, properly installed.
  • Dictionary database.
  • A target database.

**The previous configuration is explained in detail under the Axional Studio/Setup block.

 

2 Architecture

As mentioned above, a tree will be loaded asynchronously. That means the tree only shows the first level and the nodes configured as expanded when the form is loaded. When the user clicks on the branch expand icon, the tree will make a request to the server to get child nodes. After child nodes have been loaded once, they are saved and the tree does not need to make another request to get child nodes again.


Trees are configured with Main Box (wic_jrep_box_sqltree), Tree Node (wic_jrep_box_sql_tree_node), Buttons (wic_jrep_form_celldata_butt) and Links (wic_jrep_box_collnk).


In Main Box, users can configure general features such as: Selection type, Ignore row selected, Erase on reset.


In Tree Node, users can configure the content of each tree level. Here, SQL statements will be used to get nodes. Users can create as many Tree Node statements as required. Each tree node can return different data and information. For example, if you want a tree with different categories (Clients, Products, Services), and each category returns information from different tables, there will be as many tree nodes as different categories.


Users can configure Buttons and Links as needed.

 

2.1 Physical Model

 

2.2 Main Box

wic_jrep_box_sqltree
Label Description
Box ID Box identifier

  • Default: THIS
Select Flag indicating if the tree allows lines selection.

  • Default: 0
  • Values:
    • 0: No.
    • 3: Multiple.
    • 1: Multiple inherit.
    • 2: Single row.
Ignore Row Selected Ignore Row Selected

  • Default: 0
  • Values:
    • 1: Yes.
    • 0: No.
Erase Erase data tree when form is cleaned

  • Default: 1
  • Values:
    • 1: Yes.
    • 0: No.
User created User that has created the object

  • Default: USER
Date created Creation date

  • Default: CURRENT
User updated User updated

  • Default: USER
Date updated Updated date

  • Default: CURRENT
 

2.3 Node

wic_jrep_box_sqltree_node
Label Description
Box ID Box identifier

  • Default: THIS
Order Order of statements executions

  • Default: 0
Condition of selection Condition of selection. If condition return true, the tree will load this node. If there is more than one node with condition equals to true, the tree will load the first node. Values of dynamic column will be values of parent node statement.

  • Format: UELSQL_EXPR
SQL Stmt SQL Stmt

  • Format: SQLCOND_EXPR
Is It leaf? If result of condition is true, row is a leaf.

  • Format: UELSQL_EXPR
Initially expanded? Expression to expand node when it is loaded.

  • Format: UELSQL_EXPR
Column label Name of the recordset column with the information to show on tree
ID columns Columns to identify node on resultset
User created User that has created the object

  • Default: USER
Date created Creation date

  • Default: CURRENT
User updated User updated

  • Default: USER
Date updated Updated date

  • Default: CURRENT
 

2.4 Icons

wic_jrep_box_sqltree_icon
Label Description
Box ID Box ID
Order Icon order

  • Default: 0
Visible expression Visible expression

  • Format: JS_EXPR
Code Icon Code
User created User that has created the object

  • Default: USER
Date created Creation date

  • Default: CURRENT
User updated User updated

  • Default: USER
Date updated Updated date

  • Default: CURRENT
 

2.5 Links

Using this option, users can access the definitions of object hyperlinks. If the user possesses the necessary permissions, they will be able to create, modify, and erase these definitions.

A hyperlink represents a path or resource, used to connect a specific report to the universe of possible queries related to the business concepts in the document.

Additionally, with this option users can also access queries of information attached to the object which hyperlinks belong to:
  • Definition of object itself.
  • Registry of object's input fields.
  • Registry of object's output fields.
  • Registry of object query's variables.
  • Registry of hyperlink's assigned variables.
  • Registry of object's descriptive information.
  • Registry of object's headers.
  • Registry of object's restrictions.
  • Registry of object's authorizations.
wic_jrep_box_collnk
Label Description
Hyperlink identifier Name of a component field where links defined here will be added. This field refers to one of the attributes returned by the component's SQL statement. In certain cases, the link may not apply to a given column, if used generically on a component element which represents each row returned by the SQL statement. This is the case for components such as the calendar, image reel, etc.
Box ID Identifier of the box.
Column Column name.
Apply To Flag indicating where to apply styles.

  • Default: 0
  • Values:
    • 0: Cell.
    • 1: CellĀ (Starts with).
Order Link's display order within the object.
Type Link style type.

  • Default: T
  • Values:
    • T: Text.
    • I: Icon.
    • A: Alarm.
    • P: Process.
Mode Open mode.

  • Default: 0
  • Values:
    • 0: Default.
    • 3: New window.
    • 1: Modal window.
    • 2: Modal & refresh.
Hyperlink Object Code of the object to be linked.
Expression Expression of link activation condition.

  • Format: UELSQL_EXPR
lnk_expr_backup
Hyperlink Command Statement linked to the object.

  • Format: SQLCOND_EXPR
lnk_stmt_backup
 

2.6 Environment Architecture

The tree is an asynchronous component, therefore content is loaded when requested. Tree is loaded via the configuration of Main Box (wic_jrep_box_sqltree):

  • Select: Flag indicating if the tree allows node selection.
  • Ignore Row Selected: Flag indicating if this component will ignore row on object.
  • Erase: Erase data tree when form is cleared.

When the tree is initially configured, it only loads the first level and children of nodes configured as expanded. To configure one node as expanded by default use UEL expression "Initially Expanded?". In that expression user can use fields of node record. The result is below:


When clicking on a node branch, child nodes will be loaded via a request to a server (e.g. click on FOLDER 1):


To load nodes, trees can be configured with one or more SQL statements (Tree nodes). Each SQL statement will return nodes to add to the tree. However, the tree only loads one SQL statement for each branch. The SQL selected to load will be the first that evaluates the condition to true (Selection condition of Tree nodes). If all tree nodes evaluate to false or the SQL statement does not return records, the branch will be empty.


The node label will be the field value reported in Tree node column label.


SQL statements return two additional columns:

  • Record is a leaf.
  • Record has links.

Both fields are conditions. The fields of the SQL statement can be used to evaluate these conditions. It’s possible to use form fields using the adapter function ( adapter(fieldname) ). These columns will let the tree component know if a node is a leaf or a branch, and whether a node has links.


After SQL statement, system converts records on node: e.g. Load tree:

E.g. Click on FOLDER 4 expand icon (when clicking a node branch, the process is the same as in the previous case (FOLDER1)):

 

3 Implementation

The following sections show how to create tree components step by step. It starts with a simple page tree in the first section, and goes on to explain more complex situations in further sections.

 

3.1 Configuration

Open your dictionary application and go to the form object to which you wish to add a tree component:

  1. Create a box with type SQL-TREE.
  2. Enter SQL-TREE tab and add a new record.
  3. Enter SQL-TREE NODES and add a new record with the following values:
    • Order: 0
    • Condition of selection: deep == 0
    • Is it leaf ?: children_num == 0
    • Initially expanded ?: null
    • Column label: name
  4. Add a new record with the following values:
  • Order: 1
  • Condition of selection: deep > 0
  • Is it leaf ?: children_num == 0
  • Initially expanded ?: null
  • Column label: name

Result:

  1. At load tree: (Select SQL-TREE NODE with order = 0 because deep (=0) == 0):
  1. When clicking on Folder 1. (Select SQL-TREE NODE with order = 1 because deep (=1) > 0 ):
  1. When clicking on Folder 1.1.(Select SQL-TREE NODE with order = 1 because deep (=2) > 0 ):
 

3.2 Tree Selection

The system allows users to interact with the SQL tree via the different actions of a form (buttons, events, transactions, etc.). To access the data in a table, the mnemonic code which allows you to refer to a specific table within the form is essential.


When data is retrieved from a table, only data from the selected rows is obtained. By default an SQL tree does not have a selection option, but selection mode is an option.


If the user selects single option, they can only select one row at a time. The selection is made by clicking directly on the row. In order to select more than one node, the Multiselection indicator must be activated in the table definition. In this way, a column is enabled with the checkboxes that allow more than one row to be selected at a time.


To set a selection mode for a tree, go to the SQL Tree box and enter SQL Tree tab. Set value to single or multiple in the SELECT column.

If tree has one or more node selected, the system returns a JSON structure with the selection. This structure only contains the selected nodes and their branches. For each branch, a variable is selected to indicate if its node is selected. See the example below:

 

3.2.1 Use JavaScript Function

To get selection with a JavaScript function, users must add a button. Enter button tab and add a new button with the following column values:

  • Type: Javascript.
  • XSQL statement / Javascript: Function name or javascript code.

For JavaScript functions, it is possible to get tree selection using sqltreeGetSelected(BOX_ID), where BOX_ID is the Mnemonic of the SQL tree box. This function returns nodes selected on a JSON structure.

 

3.2.2 Use XSQL Script Function

To get selection with an XSQL Script function, users must add a button. Enter button tab and add a new button with the following column values:

  • Type: Execute or Execute and refresh or Execute and refresh cursor.
  • XSQL statement / Javascript: call to xsqlscript function.

For XSQL script functions, it is possible to get tree selection as shown below:

Where BOX_ID is the Mnemonic of the SQL tree box. This function returns nodes selected on a JSON structure.

 

3.2.3 Use on Transaction

To get selection on a transaction (TX manager), you need to add a TX Manager. Enter TX Manager button tabs, and add a new TX.


In statement, you can call an XSQL script. For XSQL script functions, it is possible to get tree selection as shown below:

 

3.3 Tree Links

SQL trees allow hyperlinks on values returned by the execution of the SQL statement. There are four types of destination mode:

  • Default: the link opens in the same window.
  • New window: the link opens in a new window.
  • Modal window: the link opens in a modal window.
  • Modal and refresh: the link opens in a modal window and refreshes the main form.
 

3.3.1 Link to Object

When user clicks on a node, a new object is opened with the condition indicated in Hyperlink command. In this column it is possible to use form columns (adapter) and record node values. E.g. parent_id = ${id) AND type = ‘${adapter(“type”)}’

 

3.3.2 Call JavaScript Function

When user clicks on a node, this executes a JavaScript function indicated in Hyperlink command. This column must be set to return funct_name(param1, param2, ...), where funct_name is the name of the JavaScript function and param1 are the parameters. Parameters can be form columns or node record values. E.g. return openObject(${id), ‘${adapter(“type”)}’)

  • Related to the SQL-TABLE: It is possible to relate an SQL Tree to an SQL Table. To do so, the user must create a link that calls the JavaScript function and inside, use the function sqltableSearchBy. (For more information, see SQL-TABLE information).
 

3.4 Tree icons

Tree allow to add icons to every node. Each node can have a different icon. It can be configured on wic_jrep_box_sqltree at box tree icons. That Box is a sql-table.


There are three fields in tree icon configuration:

  • Order: Order of prevalence of icon. Its field is important because each node only can have one icon. The icon to show will be the first that evaluates a visible expression.
  • Visible Expression: This expression will be evaluated to show the icon.
  • Code: Code of icon. It has to be defined on table wic_image_object.
 

4 Example

The current section shows a complete practical example with the most common uses of SQL-Tree. However, SQL-Tree is versatile and can load all type of structures. The example below demonstrates how to display songs in different categories (Artist, Album, Genre).

  1. Add SQL-Tree
    • Select: none.
    • Ignore row selection: false.
    • Erase on reset: false.
  2. Add first node level:
    • Order: 1
    • Condition of selection: deep == 0 (deep == 0 when is a first level)
    • Initially Expanded: deep == 0 (Expand first level on tree load)
    • Column label: name
  3. Add artist level:
    • Order: 2
    • Condition of selection: deep > 0 type =="artist_group" (when node branch is artist_group).
    • Column label: name
  4. Add genre level:
    • Order: 3
    • Condition of selection: deep > 0 type =="genre_group" (when node branch is genre_group).
    • Column label: name
  5. Add album level:
    • Order: 4
    • Condition of selection: deep > 0 type == "album_group" (when node branch is album_group)
    • Column label: title
  6. Add album folder:
    • Order: 5
    • Condition of selection: deep > 0 (type == "artist" || type == "genre") (when node branch is artist or genre).
    • Column label: name
  7. Add album level for artist and genre folder:
    • Order: 6
    • Condition of selection: deep > 0 type == "album_group_v2" (when node branch is album_group_v2).
    • Column label: title
  8. Add track level:
    • Order: 7
    • Condition of selection: deep > 0 type == "album" (when node branch is album).
    • Is leaf: 1==1
    • Column label: name
  9. Relate to SQL Table when clicking on album. Filter SQL Table by albumid. Add next link:
    • Column: name
    • Mode: default
    • Hyperlink object: Same object
    • Hyperlink command: return sqltableSearchBy("SQLTABLE_TRACK", {'albumid': '${albumid}'})
    • Expression enabled: type == "album"
  10. Relate to SQL Table when clicking on track. Filter SQL Table by trackid. Add next link:
    • Column: name
    • Mode: default
    • Hyperlink object: Same object
    • Hyperlink command: return sqltableSearchBy("SQLTABLE_TRACK", {'trackid': '${trackid}'})
    • Expression enabled: type == "track"
  11. Open object when clicking on artist. Add next link:
    • Column: name
    • Mode: default
    • Hyperlink object: Same object
    • Hyperlink command: return sqltableSearchBy("SQLTABLE_TRACK", {'trackid': '${trackid}'})
    • Expression enabled: type == "track"
 

5 To Do

The tree will have new features with more functionalities and options, which are summarized below:

  • Add filter or search. User should be able to search or filter one node.
  • Start tree with X levels expanded.
 

6 Appendix

 

6.1 Available Variables in Selection Condition

The SQL tree node selection condition (wic_jrep_box_sqltree_node.node_expr) has been executed when one node branch expands child content or when tree is loaded. As such, there are two different situations:

  • When tree is loaded:
    • Use of column == “value”. Cannot use it because parent branch does not exist.
    • Use of adapter(‘column’). Column is referred to form columns.
    • Use of deep. (Deep of tree. 0 at start).
  • When node branch expands content:
    • Use of column == “value”. Column is referred to resultset of node branch.
    • Use of adapter(‘column’). Column is referred to form columns.
    • Use of deep. (Deep of tree. 0 at start. In this case, the value will be greater than 0).
 

6.2 Available Variables in SQL Statements

The SQL tree node statements (wic_jrep_box_sqltree_node.node_sqlstmt) have been executed when one node branch expands child content or when tree is loaded. As such, there are two different situations:

  • When tree is loaded:
    • Use of ${column}. Cannot use it because parent branch does not exist.
    • Use of ${adapter(‘column’)}. Column is referred to form columns.
  • When node branch expands content:
    • Use of ${column}. Column is referred to resultset of node branch.
    • Use of ${adapter(‘column’)}. Column is referred to form columns.
 

6.3 Available Variables in 'is leaf' Expression

The SQL tree node 'is leaf' condition has been executed for each record of the SQL statement result. The variables you can use in this case are below:

  • Use of column == “value”. Column is referred to record of SQL statement.
  • Use of adapter(‘column’). Column is referred to form columns.
 

6.4 Available Variables in Link Expressions

The SQL tree node selection condition (wic_jrep_box_sqltree_node.node_expr) has been executed when one node branch expands child content or when tree is loaded. As such, there are two different situations:

  • When tree is loaded:
    • Use of ${column}. Cannot use it because parent branch does not exist.
    • Use of ${adapter(‘column’)}. Column is referred to form columns.
  • When node branch expands content:
    • Use of ${column}. Column is referred to resultset of node branch.
    • Use of ${adapter(‘column’)}. Column is referred to form columns.
 

6.5 Available Functions to Get SQL Tree Selection

SQL tree node selection can be obtained from two sides: Client (JavaScript function) or Server (XSQL Script function):

  • Client: sqltreeGetSelected(‘BOX_MEMOTECNIC’)
  • Server:

Both functions return a JSON structure with the node and its parents selected:

 

6.6 Available special variables with javascript execution

Special variables with javascript functions can be used on actions. These variables are next:

  • parentnode: Return the parent node of node has been clicked.
 

6.7 Available functions to refresh node

It is possible to refresh content of one node. To do it, use javascript function sqltreeRefreshNode(p_boxid, p_parentnode, p_nodevaluesID, loadlcallback).

  • p_boxid: Mnemonic code of box
  • p_parentnode: Parent node. It can be obtained on actions
  • p_nodevaluesID: JSON with the values of ID columns. User can configure it on Tree Nodes object field Columns ID.
  • loadlcallback: callback function to execute when a node is loaded.
Example
sqltreeRefreshNode("BOX_SQLTREE", parentnode, {"id": id}, false);