<!-- 
/*
Copyright 2017 apHarmony

This file is part of jsHarmony.

jsHarmony is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jsHarmony is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this package.  If not, see <http://www.gnu.org/licenses/>.
*/
-->
<script type="text/x-tutorial-info">
{
  "Title": "Tree Controls",
  "Menu": ["Models","Fields / Controls","Built-in Controls"],
  "Code": [
    "/models/FieldTree_Standard.json"
  ],
  "Demo": [
    { "url": "jsHarmonyTutorials/FieldTree_Standard?action=update&category_id=6", "title": "Tree Control" }
  ]
}
</script>

<h3>Overview</h3>
A tree control enables the user to select a value from an expandable tree.  This is useful for navigating complex or recursively-defined structures, such as file folders or store categories.<br/>
<br/>
The tree control uses a similar syntax to the list of values, and has the following tree-specific field properties:
<pre>
{
  "control": "tree",
  
  //The "List of Values" expression for populating the tree nodes
  "lov": {
    "sql": "select ----- as code_id, ----- as code_parent_id, ----- as code_val, ----- as code_txt, ----- as code_icon from ----- where 1=1 %%%DATALOCKS%%% order by -----",
    "datalock":{ ... }
  },

  //Bind to a database to save the selected item, or set field.always_editable to interact with the control via the field.onchange event
  "name": "Item_ID",

  "controlparams": {

    //Array of menu items that are displayed when a tree node is right-clicked.
    //  The selected value is passed as "context_item" to the "command" JavaScript method
    "item_context_menu": [
      { "icon": "insert", "text": "Add", "command": "XExt.Alert('insert ' + context_item);", "actions": "IUD" }
    ],

    //Expand all tree nodes by default
    "expand_all": false,      
    
    //Automatically expand tree to the selected node, when selected on load or via JavaScript
    "expand_to_selected": true
  }
}
</pre>
The tree List of Values expression should return a table of tree nodes, defined as follows:
<ul>
  <li>code_id :: The unique ID of the tree node</li>
  <li>code_parent_id :: The ID of the parent node</li>
  <li>code_val :: The value of the node that will be saved to the database, if selected</li>
  <li>code_txt :: The display text of the node</li>
  <li>code_icon :: The icon name to be used for the node (same format as the model.buttons icons)</li>
</ul>
The code_id and code_parent_id fields recursively define the tree structure.  The code_val field is used for getting / setting the currently selected tree node.  The code_txt and code_icon properties are used to render each individual tree node.

<h3>Example</h3>
The following example uses a tree control to select the parent category in a category tree:
<%-getScreenshot('jsHarmonyTutorials/FieldTree_Standard?action=update&category_id=6&popup=1','Tree Control')%>
<pre>
{
  "layout":"form",
  "table":"category",
  "caption": ["Category", "Categories"],
  "onecolumn":true,
  "fields": [
    {"name": "category_id", "caption": "Category ID", "control": "label"},
    {"name": "category_name", "caption": "Category Name", "control": "textbox", "validate": ["Required"]},
    {"name": "category_parent_id","caption": "Parent Category","control": "tree",
      "lov": { "sql": "select category_id code_id, category_parent_id code_parent_id, category_id code_val, category_name code_txt, 'folder' code_icon from category where category_id<>ifnull(@category_id,0) order by code_txt;" },
      "default": { "sql": "select category_id from category where category_parent_id is null order by category_name limit 1" }
    }
  ]
}
</pre>