# jsTree

## javascript tree component

### Documentation

## API

Functions bound directly to the tree_component class:

- $.tree_create()

  function - accepts no arguments - returns an empty tree instance, which you can call init on.

- $.tree_focused()

  function - accepts no arguments - returns a reference to the currently selected instance.

  Example: bind $.tree_focused().rename() to the F2 key.

- $.tree_reference(id)

  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 null on error.

- $.tree_rollback(rb)

  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.

Some of the variables available for each tree instance (commonly used ones are black) (properties):

- cntr

  integer - a counter of all jstree instances - this number is unique with each instance.

- container

  jQuery - the container of the tree (the node you passed at initialization).

- current_lang

  string - the currently visible language (one of the strings you passed at initialization). If no language versions are used this is false.

- hovered

  jQuery - the currently hovered node, but only if set by the hover_branch function. This variable does not update as the mouse hovers nodes. If no node is hovered equals false.

- li_height

  integer - the height of a node (used internally for calculations).

- locked

  boolean - the current lock status of the tree.

- offset

  object - the offset (left & top) of the container.

- opened

  array - a list of ids that are opened. This is used internally and most of the time this array is empty.
  If you need to track the open nodes - either implement it yourself using the onopen and onclose callbacks or use the COOKIE functionality.

- path

  string - the path to the tree’s files (where you included tree_component.js from).

- selected

  jQuery - the object you selected last (when multiselecting this contains only THE LAST selected node).

- selected_arr

  array - array of jQuery objects - all the selected nodes (this array exists only id settings.multiple is different from false).

- settings

  object - the object you passed at initialization merged with the defaults (some properties can be modified runtime).

- sn

  string - the sheet number of tree_component.css.

Most of the functions available for each tree instance (methods)

- init

  Arguments: [REQ]container node, [OPT]options.
  The function that initializes the tree and binds all events.

- off_height

  Arguments: none
  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 (offset and li_height).

- refresh

  Arguments: [OPT]node to refresh
  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.

- parseJSON

  Arguments: [REQ]data
  This function converts a JSON object (structured acoording to the specification) into the HTML structure required by jsTree.

- getJSON

  Arguments: [OPT]node to begin from, [OPT]attributes to collect from the <li> node, [OPT]attributes to collect from the <a> node, [OPT]force long JSON format.
  This function traverses the whole tree and exports it as JSON. Refer do the data sources section 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 true
  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.
  The second argument defaults to: [ "id", "rel", "class" ]. If you want to collect other attributes - pass an array like this one as the second argument.
  The third argument defaults to an empty array.
  The fourth argument defaults to false.

- getXML

  Arguments: [OPT]type (string “flat” or “nested”), [OPT]node to begin from, [OPT]attributes to collect from the <li> node, [OPT]attributes to collect from the <a> node, cb - used only internally.
  This function traverses the whole tree and exports it as XML. Refer do the data sources section to see the format of the output.
  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.
  The second argument defaults to: [ "id", "rel", "class" ]. If you want to collect other attributes - pass an array like this one as the second argument.
  The third argument defaults to an empty array.

- focus

  Arguments: none
  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.

- attachEvents

  Arguments: none
  This function should be called only once - it attaches all required events to the tree. You do not need to call this function.

- checkMove

  Arguments: [REQ]node(nodes) that are moved or copied, [REQ]reference node, [REQ]position
  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 true if a move does not conflict any rules, otherwise false.

- reselect

  Arguments: none
  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).

- get_node

  Arguments: [REQ]node
  This function returns the jQuery extended copy of the node passed as the first argument if it is a <li> node. Otherwise it searches for the first parent of the passed node that is a list item.

- get_type

  Arguments: [REQ]node
  Return the type of the node passed as the first argument.

- scrollCheck

  Arguments: [REQ]x, [REQ]y
  This function is used internally to scroll the container when the user drags a node near its edge.

- check

  Arguments: [REQ]rule, [REQ]nodes
  This function checks a node against rules (clickable, draggable, etc). Returns true or false respectively.

- hover_branch

  Arguments: [REQ]node
  Sets the node passed as the first argument as hovered.

- select_branch

  Arguments: [REQ]node, [OPT]is multiselect
  Selects the node passed as the first argument. If the second argument is set to true the previously selected nodes are not deselected (mutliselect).

- deselect_branch

  Arguments: [REQ]node
  Deselects the node passed as the first argument.

- toggle_branch

  Arguments: [REQ]node
  Toggles the state of the node (opened or closed) passed as the first argument.

- open_branch

  Arguments: [REQ]node, [OPT]disable animation, [OPT]callback function
  Opens the node passed as the first argument. If the second argument is set to true 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 onopen callback).

- close_branch

  Arguments: [REQ]node
  Closes the node passed as the first argument.

- open_all

  Arguments: [OPT]node
  Opens all nodes. If you pass a node as the first argument - all of its subnodes are opened.

- close_all

  Arguments: none
  Closes all nodes.

- show_lang

  Arguments: [REQ]index
  Switches to the language specified by the index passed as the first argument (the index corresponds to one of the items in the settings.languages array).

- cycle_lang

  Arguments: none
  Switches to the next language in the settings.languages array.

- create

  Arguments: [OPT]obj, [OPT]reference node, [OPT]position for the new node
  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 settings.rules.createat is used (”top” or “bottom”). You can also pass “before” or “after” as the final argument - then the new node will be positioned before or after the reference node, and not inside it.

- rename

  Arguments: [OPT]node
  Renames the passed or currently selected node.

- remove

  Arguments: [OPT]node
  Removes the node specified in the first argument. If not present - removes the currently selected node.

- next

  Arguments: [REQ]node, [OPT]strict
  Returns the next sibling of the node passed as the first argument. If strict is not set to true 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).

- prev

  Arguments: [REQ]node, [OPT]strict
  Returns the previous sibling of the node passed as the first argument. If strict is not set to true prev behaves like the explorer shortcuts (if you are at the first child of a node, calling prev will return the parent node).

- parent

  Arguments: [REQ]node
  Returns the parent node of the node passed as the first argument.

- children

  Arguments: [REQ]node
  Returns the children nodes of the node passed as the first argument.

- get_next
  get_prev
  get_left
  get_right

  Arguments: [OPT]force selection
  Those functions recreate the standart functionality of the keyboard arrows when browsing a tree, by moving the selection. If settings.ui.hover_mode is set to true they only move the hover state, unless the force argument is set to true.

- toggleDots

  Arguments: none
  Toggles the dots connecting the nodes.

- set_cookie

  Arguments: [REQ]type
  Set the cookies if the cookie functionality is enabled. The argument is either “selected” or “open” - this defines which cookie to set.

- moved

  Arguments: [REQ]node(nodes) that are moved or copied, [REQ]reference node, [REQ]position, [OPT]is new, [OPT]is copy
  This is the actual function that moves nodes around and performs the cleanup after a move. It is used internally.

- error

  Arguments: [OPT]error message
  A simple function that only executes the onerror callback and returns false.

- lock

  Arguments: [REQ]state
  This function locks / unlocks the tree (when locked no user interaction is allowed). The state argument is Boolen - true to lock, false to unlock.

- cut
  copy

  Arguments: none
  Those cut/copy functions cut or copy the currently selected nodes.

- paste

  Arguments: [OPT]refenrece node, [OPT]position.
  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 create function. If you pass -1 as reference node, nodes are pasted as root nodes.

- search

  Arguments: [REQ]search string
  This function performs a search by opening all parent nodes of nodes which contain the search string. Those nodes receive the class “search”. If settings.data.async is set to true, a request is also made to settings.data.url along with the parameter (GET or POST) “search” containing the search string - the expected response is a list of comma-separated IDs which will be loaded.

- context_menu

  Arguments: none
  Builds the context menu onload and after a refresh.

- get_rollback

  Arguments: none
  Gets a rollback object for the tree it is executed in.

- destroy

  Arguments:none
  This function destroys the instance. It also unbinds all events associated with it. If the instance was focused - the first available instance is focused.