7_api.html 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266
  1. <!DOCTYPE html
  2. PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  3. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  4. <html xmlns="http://www.w3.org/1999/xhtml">
  5. <head>
  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  7. <title>jsTree &raquo; Documentation </title>
  8. <link rel="stylesheet" type="text/css" href="../media/style.css" />
  9. <link rel="shortcut icon" href="../media/favicon.ico" />
  10. <link rel="stylesheet" type="text/css" href="../media/prettify.css" />
  11. <script type="text/javascript" src="../media/prettify.js"></script>
  12. <script type="text/javascript" src="../media/iepngfix_tilebg.js"></script>
  13. <script type="text/javascript">window.onload = function() { prettyPrint(); }</script>
  14. </head>
  15. <body>
  16. <div id="container">
  17. <div id="head">
  18. <h1>jsTree</h1>
  19. <h2>javascript tree component</h2>
  20. <h3>Documentation</h3>
  21. </div>
  22. <div id="sidebar">
  23. <h3 style="margin-top:0;">Documentation</h3>
  24. <ul>
  25. <li class="page_item"><a href="1_files.html" title="Required &amp; optional files">Required &#038; optional files</a></li>
  26. <li class="page_item"><a href="2_creation.html" title="Instance creation">Instance creation</a></li>
  27. <li class="page_item"><a href="3_configuration.html" title="Configuration">Configuration</a></li>
  28. <li class="page_item"><a href="4_data.html" title="Data sources">Data sources</a></li>
  29. <li class="page_item"><a href="5_customize.html" title="Customization">Customization</a></li>
  30. <li class="page_item"><a href="6_output.html" title="Output">Output</a></li>
  31. <li class="page_item current_page_item"><a href="7_api.html" title="API">API&nbsp;</a></li>
  32. </ul>
  33. <h3>Examples</h3>
  34. <ul>
  35. <li class="page_item"><a href="../_examples/1_datasources.html" title="Data sources">Data sources</a></li>
  36. <li class="page_item"><a href="../_examples/2_operations.html" title="Operations">Operations</a></li>
  37. <li class="page_item"><a href="../_examples/3_callbacks.html" title="Callbacks">Callbacks</a></li>
  38. <li class="page_item"><a href="../_examples/4_themes.html" title="Themes">Themes</a></li>
  39. <li class="page_item"><a href="../_examples/5_others.html" title="Others">Other examples</a></li>
  40. <li class="page_item important"><a href="../_examples/7_full.html" title="Full example">Full PHP &amp; mySQL example&nbsp;</a></li>
  41. </ul>
  42. </div>
  43. <div id="data" style="margin-top:-45px;">
  44. <div id="content">
  45. <ul class='nav'>
  46. <li><a href="6_output.html" title="Output">&laquo;&nbsp;Output</a></li>
  47. <li><a href="../index.html">Up to Reference</a></li>
  48. <li>&nbsp;</li>
  49. </ul>
  50. <h2 style="margin-top:25px;">API</h2>
  51. <div class="entry"><div id="documentation">
  52. <p>Functions bound directly to the <span class="var">tree_component</span> class:</p>
  53. <ul>
  54. <li>
  55. <span class="var" id="tree_create">$.tree_create()</span>
  56. <p>function - accepts no arguments - returns an empty tree instance, which you can call <span class="var">init</span> on.</p>
  57. </li>
  58. <li>
  59. <span class="var" id="tree_focused">$.tree_focused()</span>
  60. <p>function - accepts no arguments - returns a reference to the currently selected instance.</p>
  61. <p class="note">Example: bind <span class="var">$.tree_focused().rename()</span> to the F2 key.</p>
  62. </li>
  63. <li>
  64. <span class="var" id="tree_reference">$.tree_reference(id)</span>
  65. <p>function - accepts one argument - the ID of the instance you are looking for (this can be either the container node’s ID attribute or the index of the tree) - returns the desired tree instance or <span class="var">null</span> on error.</p>
  66. </li>
  67. <li>
  68. <span class="var" id="tree_rollback">$.tree_rollback(rb)</span>
  69. <p>function - accepts one argument - a rollback object (you get this object as the final argument in the onmove, ondelete, onremove, oncopy, onrename, oncreate callbacks) - returns all the involved trees in their previous state.</p>
  70. </li>
  71. </ul>
  72. <p>&nbsp;</p>
  73. <p>Some of the variables available for each tree instance (commonly used ones are black) (properties):</p>
  74. <ul>
  75. <li style="color: gray;"><span class="var">cntr</span>
  76. <p>integer - a counter of all jstree instances - this number is unique with each instance.</p>
  77. </li>
  78. <li style="color: gray;"><span class="var">container</span>
  79. <p>jQuery - the container of the tree (the node you passed at initialization).</p>
  80. </li>
  81. <li style="color: gray;"><span class="var">current_lang</span>
  82. <p>string - the currently visible language (one of the strings you passed at initialization). If no language versions are used this is <span class="val">false</span>.</p>
  83. </li>
  84. <li><span class="var" id="api_hovered">hovered</span>
  85. <p>jQuery - the currently hovered node, but only if set by the <span class="var">hover_branch</span> function. This variable does not update as the mouse hovers nodes. If no node is hovered equals <span class="val">false</span>.</p>
  86. </li>
  87. <li style="color: gray;"><span class="var">li_height</span>
  88. <p>integer - the height of a node (used internally for calculations).</p>
  89. </li>
  90. <li style="color: gray;"><span class="var">locked</span>
  91. <p>boolean - the current lock status of the tree.</p>
  92. </li>
  93. <li style="color: gray;"><span class="var">offset</span>
  94. <p>object - the offset (left &amp; top) of the container.</p>
  95. </li>
  96. <li style="color: gray;"><span class="var">opened</span>
  97. <p>array - a list of ids that are opened. This is used internally and most of the time this array is empty.<br>If you need to track the open nodes - either implement it yourself using the <span class="var">onopen</span> and <span class="var">onclose</span> callbacks or use the COOKIE functionality.</p>
  98. </li>
  99. <li><span class="var" id="path">path</span>
  100. <p>string - the path to the tree’s files (where you included <span class="file">tree_component.js</span> from).</p>
  101. </li>
  102. <li><span class="var" id="selected">selected</span>
  103. <p>jQuery - the object you selected last (when multiselecting this contains only THE LAST selected node).</p>
  104. </li>
  105. <li><span class="var" id="api_selected_arr">selected_arr</span>
  106. <p>array - array of jQuery objects - all the selected nodes (this array exists only id <span class="var">settings.multiple</span> is different from <span class="val">false</span>).</p>
  107. </li>
  108. <li style="color: gray;"><span class="var">settings</span>
  109. <p>object - the object you passed at initialization merged with the defaults (some properties can be modified runtime).</p>
  110. </li>
  111. <li style="color: gray;"><span class="var">sn</span>
  112. <p>string - the sheet number of <span class="file">tree_component.css</span>.</p>
  113. </li>
  114. </ul>
  115. <p>&nbsp;</p>
  116. <p>Most of the functions available for each tree instance (methods)</p>
  117. <ul>
  118. <li><span class="var" id="api_init">init</span>
  119. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>container node, <span class="opt" title="optional">[OPT]</span>options.<br>The function that initializes the tree and binds all events.</p>
  120. </li>
  121. <li><span class="var" id="api_off_height">off_height</span>
  122. <p><strong>Arguments:</strong> none<br>This function is used only internally. It saves the height of a single node and the offset of the container (relative to the document) in member variables (<span class="var">offset</span> and <span class="var">li_height</span>).</p>
  123. </li>
  124. <li><span class="var" id="api_refresh">refresh</span>
  125. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>node to refresh<br>This function refreshes the whole tree (saves the status - open nodes, selected nodes, etc). If you pass a node as an argument only the node’s children are refreshed.</p>
  126. </li>
  127. <li><span class="var" id="api_parseJSON">parseJSON</span>
  128. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>data<br>This function converts a JSON object (structured acoording to the specification) into the HTML structure required by jsTree.</p>
  129. </li>
  130. <li><span class="var" id="api_getJSON">getJSON</span>
  131. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>node to begin from, <span class="opt" title="optional">[OPT]</span>attributes to collect from the <span class="var">&lt;li&gt;</span> node, <span class="opt" title="optional">[OPT]</span>attributes to collect from the <span class="var">&lt;a&gt;</span> node, <span class="opt" title="optional">[OPT]</span>force long JSON format.<br>This function traverses the whole tree and exports it as JSON. Refer do the <a href="/documentation/data">data sources section</a> to see the format of the output. If the third argument is not an empty array, or the node has an icon - the long format is used, otherwise - the short. If you prefer to always have the long format - pass the fourth argument as <span class="val">true</span><br>If you specify a node as the first argument, only that node and its children are included in the export, otherwise the whole tree is exported.<br>The second argument defaults to: <span class="var">[</span><span class="val"> "id"</span><span class="var">, </span><span class="val">"rel"</span><span class="var">, </span><span class="val">"class" </span><span class="var">]</span>. If you want to collect other attributes - pass an array like this one as the second argument.<br>The third argument defaults to an empty array.<br>The fourth argument defaults to <span class="val">false</span>.</p>
  132. </li>
  133. <li><span class="var" id="api_getJSON">getXML</span>
  134. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>type (string “flat” or “nested”), <span class="opt" title="optional">[OPT]</span>node to begin from, <span class="opt" title="optional">[OPT]</span>attributes to collect from the <span class="var">&lt;li&gt;</span> node, <span class="opt" title="optional">[OPT]</span>attributes to collect from the <span class="var">&lt;a&gt;</span> node, cb - used only internally.<br>This function traverses the whole tree and exports it as XML. Refer do the <a href="/documentation/data/">data sources section</a> to see the format of the output. <br>If you specify a node as the second argument, only that node and its children are included in the export, otherwise the whole tree is exported.<br>The second argument defaults to: <span class="var">[</span><span class="val"> "id"</span><span class="var">, </span><span class="val">"rel"</span><span class="var">, </span><span class="val">"class" </span><span class="var">]</span>. If you want to collect other attributes - pass an array like this one as the second argument.<br>The third argument defaults to an empty array.</p>
  135. </li>
  136. <li><span class="var" id="api_focus">focus</span>
  137. <p><strong>Arguments:</strong> none<br>This function focuses the instance it is called from. This function is mainly used internally - in most cases you do not need to call that function.</p>
  138. </li>
  139. <li><span class="var" id="api_attachEvents">attachEvents</span>
  140. <p><strong>Arguments:</strong> none<br>This function should be called only once - it attaches all required events to the tree. You do not need to call this function.</p>
  141. </li>
  142. <li><span class="var" id="api_checkMove">checkMove</span>
  143. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node(nodes) that are moved or copied, <span class="req" title="required">[REQ]</span>reference node, <span class="req" title="required">[REQ]</span>position <br>This function checks if a move does or does not conflict with the specified rules for the tree. It also checks internal rules specified as metadata. You do not need to call this function. Returns <span class="val">true</span> if a move does not conflict any rules, otherwise <span class="val">false</span>.</p>
  144. </li>
  145. <li><span class="var" id="api_reselect">reselect</span>
  146. <p><strong>Arguments:</strong> none<br>This function is usually called internally after a refresh - it restores the status that was saved before the refresh (scroll position, opened nodes, selected nodes, etc).</p>
  147. </li>
  148. <li><span class="var" id="api_get_node">get_node</span>
  149. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>This function returns the jQuery extended copy of the node passed as the first argument if it is a <span class="var">&lt;li&gt;</span> node. Otherwise it searches for the first parent of the passed node that is a list item.</p>
  150. </li>
  151. <li><span class="var" id="api_get_type">get_type</span>
  152. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>Return the type of the node passed as the first argument.</p>
  153. </li>
  154. <li><span class="var" id="api_scrollCheck">scrollCheck</span>
  155. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>x, <span class="req" title="required">[REQ]</span>y<br>This function is used internally to scroll the container when the user drags a node near its edge.</p>
  156. </li>
  157. <li><span class="var" id="api_check">check</span>
  158. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>rule, <span class="req" title="required">[REQ]</span>nodes<br>This function checks a node against rules (clickable, draggable, etc). Returns <span class="val">true</span> or <span class="val">false</span> respectively.</p>
  159. </li>
  160. <li><span class="var" id="api_hover_branch">hover_branch</span>
  161. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>Sets the node passed as the first argument as hovered.</p>
  162. </li>
  163. <li><span class="var" id="api_select_branch">select_branch</span>
  164. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node, <span class="opt" title="optional">[OPT]</span>is multiselect<br>Selects the node passed as the first argument. If the second argument is set to <span class="val">true</span> the previously selected nodes are not deselected (mutliselect).</p>
  165. </li>
  166. <li><span class="var" id="api_deselect_branch">deselect_branch</span>
  167. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>Deselects the node passed as the first argument.</p>
  168. </li>
  169. <li><span class="var" id="api_toggle_branch">toggle_branch</span>
  170. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>Toggles the state of the node (opened or closed) passed as the first argument.</p>
  171. </li>
  172. <li><span class="var" id="api_open_branch">open_branch</span>
  173. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node, <span class="opt" title="optional">[OPT]</span>disable animation, <span class="opt" title="optional">[OPT]</span>callback function<br>Opens the node passed as the first argument. If the second argument is set to <span class="val">true</span> there is no animation. The third argument can be a function that will be called upon completion (usually this is used only internally - for most need you could use the <span class="var">onopen</span> callback).</p>
  174. </li>
  175. <li><span class="var" id="api_close_branch">close_branch</span>
  176. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node<br>Closes the node passed as the first argument.</p>
  177. </li>
  178. <li><span class="var" id="api_open_all">open_all</span>
  179. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>node<br>Opens all nodes. If you pass a node as the first argument - all of its subnodes are opened.</p>
  180. </li>
  181. <li><span class="var" id="api_close_all">close_all</span>
  182. <p><strong>Arguments:</strong> none<br>Closes all nodes.</p>
  183. </li>
  184. <li><span class="var" id="api_show_lang">show_lang</span>
  185. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>index<br>Switches to the language specified by the index passed as the first argument (the index corresponds to one of the items in the <span class="var">settings.languages</span> array).</p>
  186. </li>
  187. <li><span class="var" id="api_cycle_lang">cycle_lang</span>
  188. <p><strong>Arguments:</strong> none<br>Switches to the next language in the <span class="var">settings.languages</span> array.</p>
  189. </li>
  190. <li><span class="var" id="api_create">create</span>
  191. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>obj, <span class="opt" title="optional">[OPT]</span>reference node, <span class="opt" title="optional">[OPT]</span>position for the new node<br>Creates a new node at the specified location (the second argument). The first argument is a JavaScript object, which follows the JSON jsTree format. If the second argument is not a valid node - then the currently selected node is used. The final argument positions the node amongst the children of the parent node (it is zero-based, so passing 0 would position the node as the first child), if position is not passed - the value from <span class="var">settings.rules.createat</span> is used (”top” or “bottom”). You can also pass <span class="val">“before”</span> or <span class="val">“after”</span> as the final argument - then the new node will be positioned before or after the reference node, and not inside it.</p>
  192. </li>
  193. <li><span class="var" id="api_rename">rename</span>
  194. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>node<br>Renames the passed or currently selected node.</p>
  195. </li>
  196. <li><span class="var" id="api_remove">remove</span>
  197. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>node<br>Removes the node specified in the first argument. If not present - removes the currently selected node.</p>
  198. </li>
  199. <li><span class="var" id="api_next">next</span>
  200. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node, <span class="opt" title="optional">[OPT]</span>strict <br>Returns the next sibling of the node passed as the first argument. If strict is not set to <span class="val">true</span> next behaves like the explorer shortcuts (if you are at the last child of a node, calling next will return the next sibling of the parent node).</p></li>
  201. <li><span class="var" id="api_prev">prev</span>
  202. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node, <span class="opt" title="optional">[OPT]</span>strict <br>Returns the previous sibling of the node passed as the first argument. If strict is not set to <span class="val">true</span> prev behaves like the explorer shortcuts (if you are at the first child of a node, calling prev will return the parent node).</p></li>
  203. <li><span class="var" id="api_parent">parent</span>
  204. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node <br>Returns the parent node of the node passed as the first argument.</p></li>
  205. <li><span class="var" id="api_children">children</span>
  206. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node <br>Returns the children nodes of the node passed as the first argument.</p></li>
  207. <li>
  208. <span class="var" id="api_get_next">get_next</span><br>
  209. <span class="var">get_prev</span><br>
  210. <span class="var">get_left</span><br>
  211. <span class="var">get_right</span>
  212. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>force selection<br>Those functions recreate the standart functionality of the keyboard arrows when browsing a tree, by moving the selection. If <span class="var">settings.ui.hover_mode</span> is set to <span class="val">true</span> they only move the hover state, unless the force argument is set to <span class="val">true</span>.</p>
  213. </li>
  214. <li><span class="var" id="api_toggleDots">toggleDots</span>
  215. <p><strong>Arguments:</strong> none<br>Toggles the dots connecting the nodes.</p>
  216. </li>
  217. <li><span class="var" id="api_set_cookie">set_cookie</span>
  218. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>type<br>Set the cookies if the cookie functionality is enabled. The argument is either <span class="val">“selected”</span> or <span class="val">“open”</span> - this defines which cookie to set.</p>
  219. </li>
  220. <li><span class="var" id="api_moved">moved</span>
  221. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>node(nodes) that are moved or copied, <span class="req" title="required">[REQ]</span>reference node, <span class="req" title="required">[REQ]</span>position, <span class="opt" title="optional">[OPT]</span>is new, <span class="opt" title="optional">[OPT]</span>is copy <br>This is the actual function that moves nodes around and performs the cleanup after a move. It is used internally.</p>
  222. </li>
  223. <li><span class="var" id="api_error">error</span>
  224. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>error message<br>A simple function that only executes the <span class="var">onerror</span> callback and returns false.</p>
  225. </li>
  226. <li><span class="var" id="api_lock">lock</span>
  227. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>state<br>This function locks / unlocks the tree (when locked no user interaction is allowed). The state argument is Boolen - <span class="val">true</span> to lock, <span class="val">false</span> to unlock.</p>
  228. </li>
  229. <li>
  230. <span class="var" id="api_cut">cut</span><br>
  231. <span class="var">copy</span>
  232. <p><strong>Arguments:</strong> none<br>Those cut/copy functions cut or copy the currently selected nodes.</p>
  233. </li>
  234. <li>
  235. <span class="var">paste</span>
  236. <p><strong>Arguments:</strong> <span class="opt" title="optional">[OPT]</span>refenrece node, <span class="opt" title="optional">[OPT]</span>position. <br>The paste function pastes the cut or copied nodes in the specified reference node, or the currently selected node. Position is the same as with the <span class="var">create</span> function. If you pass <span class="val">-1</span> as reference node, nodes are pasted as root nodes.</p>
  237. </li>
  238. <li><span class="var" id="api_search">search</span>
  239. <p><strong>Arguments:</strong> <span class="req" title="required">[REQ]</span>search string<br>This function performs a search by opening all parent nodes of nodes which contain the search string. Those nodes receive the class <span class="val">“search”</span>. If <span class="var">settings.data.async</span> is set to <span class="val">true</span>, a request is also made to <span class="var">settings.data.url</span> along with the parameter (GET or POST) <span class="val">“search”</span> containing the search string - the expected response is a list of comma-separated IDs which will be loaded.</p>
  240. </li>
  241. <li>
  242. <span class="var" id="api_context_menu">context_menu</span>
  243. <p><strong>Arguments:</strong> none<br>Builds the context menu onload and after a refresh.</p>
  244. </li>
  245. <li>
  246. <span class="var" id="api_context_menu">get_rollback</span>
  247. <p><strong>Arguments:</strong> none<br>Gets a rollback object for the tree it is executed in.</p>
  248. </li>
  249. <li><span class="var" id="api_destroy">destroy</span>
  250. <p><strong>Arguments:</strong>none<br>This function destroys the instance. It also unbinds all events associated with it. If the instance was focused - the first available instance is focused.</p>
  251. </li>
  252. </ul>
  253. </div></div>
  254. </div>
  255. </div>
  256. </div>
  257. </body>
  258. </html>