Skip to content

Latest commit

 

History

History
401 lines (300 loc) · 13.7 KB

README.md

File metadata and controls

401 lines (300 loc) · 13.7 KB
Raw

GTreeTable 2

GTreeTable is extension of Tweeter Bootstrap 3 framework, which allows to use tree structure inside HTML table.

Thanks to the script it`s possible to create and manage tree with unlimited nesting.

Version 2 of code was completly rewrite and now it's possible to use such functions as: advanced cache, moving nodes by Drag & Drop method, or sorting directly from JavaScript level.

Test available on demo project.

Enviroment

Till now aplication was test on following browsers:

  • Mozilla Firefox 30,
  • Chrome 37,
  • Internet Explorer 11.

Minimal installation

  1. Firstly add required files:

    <link rel="stylesheet" type="text/css" href="gtreetable.min.css" />
<script type="text/javascript" src="http://code.jquery.com/jquery-2.1.1.min.js"></script>
<script type="text/javascript" src="bootstrap-gtreetable.js"></script>

  2. Next create empty HTML table:

    <table class="table gtreetable" id="gtreetable"><thead><tr><th>Category</th></tr></thead></table>

  3. Inside of method jQuery.ready define basic configuration:

    jQuery('#gtreetable').gtreetable({
  'source': function (id) {
      return {
        type: 'GET',
        url: 'nodeChildren',
        data: { 'id': id },        
        dataType: 'json',
        error: function(XMLHttpRequest) {
          alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
        }
      }
    }
});

More about source parameter and returned data format find in configuration section.

Functionality

Actions

Actions defined in defaultAction and actions parameters are available after indicate or choosing the node. defualtActions includes defualt actions, needed to CUD operations. It may be disabled by set null value. actions defined the actions which may be add after last defined position in defaultActions.

More about action format find in configuration section.

CUD

Moment of saving and deleting node can goes together witch server communication by AJAX. Responsible actions: onSave and onDelete. It's should be functions that return jQuery.ajax settings.

Example configuration:

jQuery('#gtreetable').gtreetable({
  'source': function (id) {
    return {
      type: 'GET',
      url: 'nodeChildren',
      data: { 'id': id },        
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }
  },
  'onSave':function (oNode) {
    return {
      type: 'POST',
      url: !oNode.isSaved() ? 'nodeCreate' : 'nodeUpdate?id=' + oNode.getId(),
      data: {
        parent: oNode.getParent(),
        name: oNode.getName(),
        position: oNode.getInsertPosition(),
        related: oNode.getRelatedNodeId()
      },
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
  	};
  },
  'onDelete':function (oNode) {
    return {
      type: 'POST',
      url: 'nodeDelete?id=' + oNode.getId(),
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    };
  }
});

The new node may be added in various locations:

  • before chosen node (before),
  • after chosen node (after),
  • as a first child (firstChild),
  • as a last child (lastChild).

Moving

Moving nodes may be realized by using Drag and Drop method. By default mechanism is disabled, to activate it draggable parameter need to be set on true value. Also you need to define onMove event.

At the moment of node dragging, its new locations is marked by pointer with may be located:

  • before the node (before),
  • as a last child (lastChild),
  • after the node (after).

In this case, application is using additional libraries such as: jQueryUI and jQuery Browser Plugin so it's necessary to include required files in the code:

<script type="text/javascript" src="http://code.jquery.com/ui/1.11.1/jquery-ui.min.js"></script>
<script type="text/javascript" src="jquery.browser.js"></script>

Example configuration:

jQuery('#gtreetable').gtreetable({
  'source': function (id) {
    return {
      type: 'GET',
      url: 'nodeChildren',
      data: { 'id': id },        
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }
  },
  'draggable': true,
  'onMove': function (oSource, oDestination, position) {
    return {
      type: 'POST',
      url: 'nodeMove?id=' + oNode.getId(),
      data: {
        related: oDestination.getId(),
        position: position
      },
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }; 
  }    
});

Choosing

To choose the node it's needed to click on its name. Depending on selectLimit parameter it's possible to indicate one or more nodes.

In this case it's worth to pay attention on a few events triggered in the moment of:

  • selecting node (onSelect),
  • unselecting node (onUnselect),
  • when limit of selection is overflowed (onSelectOverflow).

More information about configuration:

Sorting

Node sorting function inside of tree may be realized directly from JavaScript level. Only needed to define sorting method as sort parameter function.

Sorting operation is triggered during: expanding tree branches, adding new node and existing node name edition.

Working of sorting function is the same as in case of table sorting, so example of configuration may look as follow:

jQuery('#gtreetable').gtreetable({
  'source': function (id) {
    return {
      type: 'GET',
      url: 'nodeChildren',
      data: { 'id': id },        
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }
  },
  'sort': function (a, b) {          
    var aName = a.name.toLowerCase();
    var bName = b.name.toLowerCase(); 
    return ((aName < bName) ? -1 : ((aName > bName) ? 1 : 0));                            
  }  
});

Nodes types

Depending on node type is possible to display additional icon next to its name. Nodes type definition is based on types parameter.

Example configuration:

jQuery('#gtreetable').gtreetable({
  'source': function (id) {
    return {
      type: 'GET',
      url: 'nodeChildren',
      data: { 'id': id },        
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }
  },
  'types': { default: 'glyphicon glyphicon-folder-open'}
});

Adding various node type is realized by GTreeTableNode.add(String position, String type) method.

Translations

User interface elements by default are displayed in English. There is a possibility to change language by change language parameter and attaching appropriate files:

Example configuration:

<script type="text/javascript" src="languages/bootstrap-gtreetable.pl.js"></script>
jQuery('#gtreetable').gtreetable({
  'source': function (id) {
    return {
      type: 'GET',
      url: 'nodeChildren',
      data: { 'id': id },        
      dataType: 'json',
      error: function(XMLHttpRequest) {
        alert(XMLHttpRequest.status+': '+XMLHttpRequest.responseText);
      }
    }
  },
  'language': 'pl'
});

In the moment when some position from translations can't be found then its values stays unchanged.

Cache

In relation to 1.x version, cache mechanism was improved. It's possible to work in 3 levels:

  • 0 - mechanism off,
  • 1 - information about child nodes are stored in memory. After moving or CUD operation, redownload information from data base is required,
  • 2 - as in 1 level with the difference that all operation on nodes are mapping in cache.

There is possibility to force refesh data by pushing Alt in the moment of node expanding.

Configuration

Parameters

  • actions (Array) - set of actions, which should be added after the last position defined in defaultActions parameter. More info about required data format is located in description of defaultActions parameter.

  • cache (Integer) - define whether actual node state should be stored in cache. It's possible to work in 3 levels:

    • 0 - mechanism off,
    • 1 - partial mapping. In the moment of moving or CUD operation the state of depending nodes is resetting,
    • 2 - fully mapping.

  • classes (Object) - parameter consists set of CSS class using to build user interface.

  • defaultActions (Array) - set of default CUD actions. Parameter needs to be table consists of objects in following format:

    {
  name: 'Action label',
  event: function (oNode, oManager) { } // code to execute 
}

    Separator (horizontal line) defined by following construction (object):

    { divider: true }

    When action label is surrounded by bracket and preceded by $ i.e. ${actionEdit} then its value is translated on language parameter language.

  • dragCanExpand (boolean) - define whether during node moving is possible to expand other nodes after choosing appropriate icon.

  • draggable (boolean) - define whether nodes can be moved. Parameter value changing on true is related with necessity of adding required jQueryUI library:

    • core,
    • widget,
    • position,
    • mouse,
    • draggable,
    • droppable.

  • inputWidth (String) - width of field of adding / edition node name.

  • language (String) - user interface language. Default English, change of language is related with necessity of adding translation file. In the moment when some translated position won't be found, then its value stays in English.

  • manyroots (boolean) - define whether it's possible to create multiple nodes roots.

  • selectLimit (Integer) - define nodes selection behavours:

    • 1 - indicate exactly the same number of nodes,

    • 0 - selection disabled,
    • -1 - unlimited selection.

  • nodeIndent (Integer) - Distance between node and its container. The value is multiplied, depending on node level.

  • nodeLevel (Integer)

  • nodesWrapper (String) - define nodes wrapper property. Default nodes. More info.

  • readonly (boolean) - determines whether executing action on node is possible or not.

  • showExpandIconOnEmpty (boolean) - parameter set on true value means that expanding node icon stays visible all the time, even if there is no node child.

  • sort (callback (GTreeTableNode oNodeA, GTreeTableNode oNodeB)) - sorting function triggered in the moment of: displaying nodes, adding new one or its changing. Working of sorting function is the same as in case of table sorting.

    Example of sorting by node name in the ascending order. 

    function (a, b) {          
  var aName = a.name.toLowerCase();
  var bName = b.name.toLowerCase(); 
  return ((aName < bName) ? -1 : ((aName > bName) ? 1 : 0));                            
}

  • source (callback (Integer id)) - function must return jQuery.ajax settings, responsible for getting nodes from data base.

    If ID = 0, then tree roots should be returned.

    Information about nodes should be included in the object table in JSON format:

    {
  "id": "node ID",
  "name": "node name",
  "level": "node level", 
  "type": "node type" 
}

  • template (String)

  • templateParts (Object)

  • types (Object) - object consists relations between node types and its icon class i.e.

    { default: "glyphicon glyphicon-folder-open" }

Events

  • onDelete(GTreeTableNode node) - event triggering at the node deleting moment, must return jQuery.ajax settings.

  • onMove(GTreeTableNode node, GTreeTableNode destination, string position) - event triggering at the node moving moment, must return jQuery.ajax settings.

  • onSave(GTreeTableNode node) - event triggering at the node adding / edition moment. It must return jQuery.ajax settings.

  • onSelect(GTreeTableNode node) - event triggering at the node selecting moment.

  • onSelectOverflow(GTreeTableNode node) - event triggering when selectLimit parameter is positive number and selecting another node would be related with overflow of defined quantity.

  • onUnselect(GTreeTableNode node) - event triggering at the moment when node is unselected.

Methods (chosen)

  • GTreeTableManager.getSelectedNodes() - returns table of selected nodes.

  • GTreeTableNode.getPath(GTreeTableNode oNode) - returns table consists the node path i.e.:

    ["Node name", "Parent node", "Main node"]

Server side

GTreeTable offer supports only in JavaScript level. Special extensions of Yii framework yii2-gtreetable or yii-gtreetable can be use as server side application. Even if you don't use this software every day, don't worry in the near future will be prepared special library (written in native PHP), designed to realize this task.