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.

Stack

Extends

 Uxi, Touch

Requires

 Templater

OML

Format

 {"selector:Tree":{CONFIG}}

Instantiate

//from a Uxi
let tree = this.create('Tree', config);

//With OML from a Uxi
OGX.Object.render(this, {"#selector:Tree":{}});

//from OGX.Object
let tree = OGX.Object.create('Tree', config);   

Config

{
      el:_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,
      data:_OBJECT_ //Optional, The actual tree data/structure
      show_root:_BOOLEAN_ //Optional, defaults to true
 };

Item Types

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
 }

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

 let types = {
      root:{mode:"folder"},
      folder:{mode:"folder"},
      file:{mode:"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"}} 

You can use the data-compound attribute, to style your items

 .ogx_tree_item[data-compound="root-open"] .ogx_tree_item_icon {
     background-image: url('../../themes/io-globules-ogx/dark/img/folder_open.svg');
 }
 .ogx_tree_item[data-compound="root-closed"] .ogx_tree_item_icon {
      background-image: url('../../themes/io-globules-ogx/dark/img/folder_closed.svg');
 }
 .ogx_tree_item[data-compound="folder-open"] .ogx_tree_item_icon {
       background-image: url('../../themes/io-globules-ogx/dark/img/folder_open.svg');
 }
 .ogx_tree_item[data-compound="folder-closed"] .ogx_tree_item_icon {
      background-image: url('../../themes/io-globules-ogx/dark/img/folder_closed.svg');
 }

}

When an item is selected, a css class ogx_tree_selected_item is assigned to the sub element .ogx_tree_item > .ogx_tree_item_content of an item

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 Tree, such as

 let tree = this.create('Tree', {el:'#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_, _ID_); //Add item as child to selected node
 tree.getItem(_ID_); //Retrieve item by id
 tree.getItemByPath(_STRING_); //Retrieve item by path
 tree.getSelectedItem(); //Retrieve selected item
 tree.selectItem(_ID_); //Select item by id
 tree.openItem(_ID_); //Open item by id
 tree.closeItem(_ID_); //Close item by id
 tree.selectItemByPropVal(_STRING, *); //Select item by property/value pair
 tree.selectItemByPath(_STRING); //Select item given its path
 tree.updateItem(_ID_, _OBJECT_, _RENDER_BOOL_); //Update item given its id, optional re-render of children, defaults to true
 tree.replaceItem(_ITEM_); //Replace item of same id
 tree.deleteItem(_ID_); //Delete item by id
 tree.deleteSelectedItem(); //Delete selected item   
 tree.getTree(); //Get the data tree    
 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

addItem

The 2nd parameter is optional. If no ID is passed, it will fallback onto the selected item of the tree

 tree.addItem({_id:'a123', label:'Hello'});
 tree.addItem({_id:'a124', label:'Hello'}, 'a123');

Events

 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)

Destroy

 tree.destroy();