====== TreeGrid ======
Treegrid is a way to represent hierarchical data in grid. \\ Treegrid supports both the Nested Set model and the Adjacency model. Good articles describing the Nested Set model can be found here: \\ 

http://ftp.ntu.edu.tw/MySQL/tech-resources/articles/hierarchical-data.html \\ 
http://www.sitepoint.com/article/hierarchical-data-database .

===== Installation =====
In order to use this module you should mark the Treegrid when you download the grid. For more information refer to [[Download]].\\ 
For Developers - this is the grid.treegrid.js in the src directory.

<note important>Before you begin with the tree grid, it is highly recommended to read the articles listed above or any other related to hierarchical data representation articles.</note>

===== Options =====
The following options can be set in the grid options to configure the treeGrid \\ 
^Option^Type^Description^Default^
|ExpandColClick|boolean|when true, the tree is expanded and/or collapsed when we click on the text of the expanded column, not only on the image|true|
|ExpandColumn|string|indicates which column (name from colModel) should be used to expand the tree grid. If not set the first one is used. Valid only when treeGrid option is set to true.|null|
|treedatatype|mixed|Determines the initial datatype (see datatype option). Usually this should not be changed. During the reading process this option is equal to the datatype option.|null|
|treeGrid|boolean|Enables (disables) the tree grid format.|false|
|treeGridModel|string|Deteremines the method used for the treeGrid. Can be nested or adjacency.|nested|
|treeIcons|array|This array set the icons used in the tree. The icons should be a valid names from UI theme roller images. The default values are: {plus:'ui-icon-triangle-1-e',minus:'ui-icon-triangle-1-s',leaf:'ui-icon-radio-off'} | |
|treeReader|array|extends the colModel defined in the basic grid. The fields described here are added to end of the colModel array and are hidden. This means that the data returned from the server should have values for these fields. For a full description of all valid values see below.| |
|tree_root_level|numeric|Determines the level where the root element begins when treeGrid is enabled|0|

<note>If the gridview option in the grid is set to true the treeGrid will not be constructed instead that set to true. </note> 

The treeReader property adds dynamically columns to the colModel property of the basic grid when treeGrid property is set to true.
Syntax:
<code javascript>
treeReader : {
   property1 : value1
   ...
   propertyN : valueN
}
</code>

The treeReader property is adds diffrent columns in the colModel depending on the  treeGridModel property - i.e. we have diffrent configurations for different models - [[Nested Set Model]] and  [[Adjacency Model]]. \\ \\ 
Currently jqGrid can work only with data returned from server. There are some tricks and articles wich describes how to work with local data.

<note important>It is important to note here that the data returned from the server should be sorted in an appropriate way; for example</note>

<code sql>
SELECT category_name, level, lft, rgt FROM categories ORDER BY lft;
</code>

{{ :wiki:treegrid.png | Tree Grid }}

===== Methods =====
In the methods below, record means the current record, which can be obtained via the getInd method like this:
<code javascript>
var record = jQuery("#grid_id").getInd(rowid,true);
</code>
NOTE: This no longer works as of version 3.7.x. Use var record = jQuery("#grid_id").getRowData(rowid); instead.

Where rowid is the id of the row. Note the second parameter in the method. If the second parameter is omited or set to false (default) the returned value is the index of the row. If the row can not be found a false is returned.

^Method^Parameters^Description^
|addChildNode| nodeid, parentid, data| Add a node in the tree according the value of the parentid parameter. The nodeid is the unique values in the row. If set to empty string the method gets the next max number + 1 from the data. if parendid is null the node is added as root. If the parentid is valid id of existing row the data is added as child of the that row. Data is a data to be inserted.|
|collapseNode|record|Collapse the node at specified record|
|collapseRow|record|Collapse the current row|
|delTreeNode|rowid|Where rowid is the id of the row. Deletes the specified node and all child nodes of that node. Does not delete the node at server|
|expandNode|record|Expand the node at the specified record|
|expandRow|record|Expand the current row |
|getNodeAncestors|record|returns array of the ancestors of the specified record|
|getNodeDepth|record|returns the depth of the specified record|
|getNodeParent|record|Returns the parent node of the specified record|
|getNodeChildren|record|Returns array of child nodes of the specified record; returns empty array if none |
|getRootNodes|none|Returns an array of the current root nodes. |
|isNodeLoaded|record|Returns true if the node is already loaded|
|isVisibleNode|record|Returns true or false if the node is visible or not|
|setTreeRow|rowid, data| The same as setRowData|
|SortTree|direction|Direction is 1 (meaning ascending) or -1 (meaning descending); sorts the tree with the currently set sortname (sortname is from grid option)|

===== Cautions and Limitations =====

  * Currently adding nodes with addRowData is not supported.
  * <del>Currently it is not recommended to combine inline editing and form editing with treegrid, or the expanded column will not be editable. </del>
  * <del>Adding nodes is currently not supported.</del>
  * [[Pager]] functionality currently disabled for treeGrid
  * Local searching is not supported at this time
  * When we initialize the grid and the data is read, the datatype is automatically set to local. This is required because treegrid supports autoloading tree nodes. This means that, for speed or efficiency, you can load the data only for the root level first and load the data for a particular child node only when the operator clicks to expand that node. The grid will determine that there is no data and try to load the node from the server, but in this case the data that is sent to the server has to have additional parameters. Setting datatype to local permits intervening before the request is made to build the request correctly. See the  [[Nested Set Model]] and  [[Adjacency Model]] on what is posted to the server