Tree

Tree is a component to display and edit data trees such as, but not limited to, a folder and file structure. It supports custom icons and separated operating modes, meaning any type of item can act as a folder and have children. In editable mode, tree items are drag-n-drop-able into one another.

OGX.Tree requires OGX.Templater.

Instantiate

 let tree = new OGX.Tree({
      container:_SELECTOR_, //HTML element containing the tree
      editable:_BOOLEAN_, //Editable (drag-n-drop),         
      sort:_OBJECT_, //Sorting, see sub section
      toggle:_BOOLEAN_, //Selection mode, if enabled, items can be unselected once selected
      icon_path:_STRING_, //The path to your image folder where icons are stored,
      icon_size:_INT_, //Optional, the icon width, defaults to 30
      types:_OBJECT_, //Object of icon types, see types subsection,
      tree:_OBJECT_ //Optional, The actual tree data/structure
      show_root:_BOOLEAN_ //Optional, defaults to true
 });

Item Types

OGX.Tree can handle a virtually unlimited amount of different icons. The operating modes are dissociated from the display. For instance, you could have a file that act as a folder. The base object structure for a type is as follow:

 {  
      mode:_OPERATING_MODE_, //Either file (doesn't have children) or folder
      icons:{open:_CSS_CLASS_, close:_CSS_CLASS_}}, //Either icons or icon, read bellow
      icon:_CSS_CLASS_
 }

If your item is operating as a folder, meaning it can have children, you can either use the icons property to store the icons for this item for its two different states, open or close. If you wish to use the same icon, or don't change the icon based on the state, use icon instead. Note that if your operating mode is file then you must use icon and not icons since the file operating mode only has one state.

Here is a basic types configuration for a simple folder and files tree.

 let types = {
      root:{mode:"folder", icons:{open:"folder_opened", close:"folder_closed"}},
      folder:{mode:"folder", icons:{open:"folder_opened", close:"folder_closed"}},
      file:{mode:"file", icon:"file"}
 };

A third optional empty icon property is available for items of folder mode, which can be used to display a closed and empty item. In this case, the icons property is to be defined as follow:

 folder:{mode:"folder", icons:{open:"folder_opened", close:"folder_closed", empty:"folder_closed_empty"}}

Tree data format

Here is the data format of a node of tree. If you wish to store custom data, use the data property to do so.

 {
      type:_STRING_, //The type of node, must be an existing type as declared in _types_ 
      label:_STRING_, //The label of the node
      state:_STRING_, //An optional state, either "open" or "close" 
      data:*, //Optional data, can be of any type (object, array, number etc.)
      items:[] //An array of nodes representing its children
 }

Here is a basic example reusing the types declared above

 {type:"root", label:"root", items:[
           {type:"folder", label:"images", items:[
                {type:"file", label:"forest.png"},
                {type:"file", label:"moutain.png"}
           ]},
           {type:"folder", label:"videos", items:[
                {type:"file", label:"sea.webm"}
           ]}
 ]}

You can of course set the types and tree after you have created the instance of OGX.Tree, such as

 let tree = new OGX.Tree({container:'#tree', ...});
 tree.setTypes(types);
 tree.setTree(data);

Or altogether with a single object

tree.setData({types:types, tree:tree});

Sorting

The sort property in the config expects an object, which contains the sorting parameters, which is applied when creating or modifying the tree. By default, the sorting parameter is as follow

 ..., sort:{enabled:true, property:'label', way:1}, ...

If you wish to sort your tree by object type instead, then use

 ..., sort:{enabled:true, property:'type', way:1}, ...

Note that way is the sorting order, either ascending (-1) or descending (1)

Methods

 tree.addItem(_OBJECT_); //Add item as child to selected node
 tree.selectItemByPropVal(_STRING_, *); //Select item given a property and value to match with the data object
 tree.selectItemByPath(_STRING_); //Select the first item matching a path (path contains target label)
 tree.updateSelectedItemDataProperty(_STRING_, *); //Update a property of the data object of the selected node
 tree.updateSelectedItemData(_OBJECT_); //Update the whole data object of the selected node
 tree.updateSelectedItemLabel(_STRING_); //Update the label of the selected node
 tree.deleteItemByPath(_STRING_); //Delete the first matching node given a path (path contains target label)
 tree.deleteSelectedItem(); //Delete the selected node
 tree.getTree(); //Get the data tree
 tree.getSelectedItem(); //Get the selected item
 tree.setTypes(_OBJECT_); //Set the types config
 tree.setTree(_OBJECT_); //Set the data tree 
 tree.setData(_OBJECT_); //Set both data tree and types with the same object
 tree.newTree(); //Remove/empty previous tree
 tree.setIconSize(_NUMBER_); //Change the icon size and the arrow relatively

Destroy

 tree.destroy();

Listen

 tree.el.on|off(
      OGX.Tree.DRAG //User start dragging
      OGX.Tree.DROP //User drops
      OGX.Tree.OPEN //User opens a node
      OGX.Tree.CLOSE //User closes a node        
      OGX.Tree.SELECT //User selects a node      
      OGX.Tree.UNSELECT //User unselects a node (toggle mode on)
  )