kartik-v/yii2-tree-manager An enhanced tree management module with tree node selection and manipulation using nested sets.

bootstrap jquery ajax tree treeview krajee hierarchy nested set nestedset

yii2-tree-manager

An enhanced tree management module from Krajee with tree node selection and manipulation using nested sets. The extension features are listed below:

A complete tree management solution which provides ability to manage hierarchical data stored using nested sets. Utilizes the yii2-nested-sets extension to manage the tree structure in your database. Refer the documentation for yii2-nested-sets extension before you start using this module.
A tree view built from scratch entirely without any third party plugins. The TreeView is designed using HTML5, jQuery & CSS3 features to work along with Yii PHP framework.
Styled with CSS3, includes jquery transitions and loading sections for ajax content, includes embedded alerts, and utilizes bootstrap css.
Tree management feature options and modes:
- View, edit, or administer the tree structure using TreeView widget as a selector and a dynamically rendered form to edit the tree node
- The form works as both a detail view for the node OR as a management tool to add/edit/delete the node.
- Form is rendered via ajax. It intelligently uses caching when the same node is clicked again (unless, the nodes are modified).
- Unique Admin Mode for allowing administrator actions on tree.
- Ability to add, edit, or delete tree nodes
- Ability to reorder tree nodes (move up, down, left or right).
- Configure tree node icons, styles, and ability to add checkboxes to tree nodes
- i18N translations enabled across the module.
Includes various jquery plugin events for advanced usage that are triggered on various tree manipulation actions.
Bonus: Includes a TreeViewInput widget that allows you to use the treeview as an input widget. The TreeViewInput widget is uniquely designed by Krajee (using jQuery & PHP with HTML5/CSS) to appear as a dropdown selection menu. It allows multiple selection or single selection of values/nodes from the tree.
A Tree model that builds upon the yii2-nested-set model and is made to be easily extensible for various use cases. It includes prebuilt flags for each tree node. Check the Tree Model documentation for more.
active: whether a tree node is active (if soft delete is enabled, the tree node will be just inactivated instead of deleting from database).
selected: whether a tree node is selected by default.
disabled: disables a tree node for editing or reorder
readonly: a read only tree node that prevents editing, but can be reordered or moved up/down
visible: whether a tree node is visible by default.
collapsed: whether a tree node is collapsed by default.
movable_u: whether a tree node is allowed to be movable up.
movable_d: whether a tree node is allowed to be movable down.
movable_l: whether a tree node is allowed to be movable left.
movable_r: whether a tree node is allowed to be movable right.
removable: whether a tree node is removable - will not be removed if children exist. If soft delete is enabled, then the node will be inactivated - else removed from database.
removable_all: whether a tree node is removable with children. If soft delete is enabled, then the node and its children will be inactivated - else removed from database.

The following important PHP classes are available with this module:

kartik\tree\Module: Module, allows you to configure the module. You must setup a module named treemanager. Refer documentation for details.
kartik\tree\TreeView: Widget, allows you to manage the tree in admin mode or normal user mode with actions and toolbar to add, edit, reorder, or delete tree nodes.
kartik\tree\TreeViewInput: Widget, allows you to use the treeview as a dropdown input either as a single select or multiple selection.
kartik\tree\models\Tree: Model, the entire tree data structure that uses the Nested set behavior from yii2-nested-sets to manage the tree nodes.
kartik\tree\models\TreeQuery: Query, the query class as required for the Nested set model.
kartik\tree\controllers\NodeController: Controller, the controller actions that manages the editing of each node for create, update, delete, or reorder (move).

Demo

You can see detailed documentation, API Code Documentation and TreeView demonstration or TreeViewInput demonstration on usage of the extension.

Installation

The preferred way to install this extension is through composer.

NOTE: Check the composer.json for this extension's requirements and dependencies. Read this web tip /wiki on setting the minimum-stability settings for your application's composer.json.

Either run

$ php composer.phar require kartik-v/yii2-tree-manager "@dev"

or add

"kartik-v/yii2-tree-manager": "@dev"

to the require section of your composer.json file.

Usage

Step 1: Prepare Database

Create your database table to store the tree structure. You can do it in one of the following ways:

Option 1: Run DB Migrations

You can run the migrations script provided to create the database structure from your yii programming console:

php yii migrate/up --migrationPath=@vendor/kartik-v/yii2-tree-manager/src/migrations

Option 2: Executing SQL script

Alternatively, you can execute the SQL script to generate your DB structure. Copy and modify the migrations/tree.sql file (a MySQL example), to create the table tbl_tree (or for any table name you need).

NOTE: You can add columns you need to this table, but you cannot skip/drop any of the columns mentioned in the script. You can choose to rename the id, root, lft, rgt, lvl, name, icon, icon_type columns if you choose to - but these must be accordingly setup in the module.

Step 2: Setup Model

Create your model for storing the tree structure extending kartik\tree\models\Tree class. You can alternatively build your own model extending from yii\db\ActiveRecord but modify it to use the kartik\tree\models\TreeTrait. You must provide the table name in the model. Optionally you can add rules, or edit the various methods like isVisible, isDisabled etc. to identify allowed flags for nodes.

So when extending from the \kartik\tree\models\Tree, you can set it like below:

namespace frontend\models;

use Yii;

class Tree extends \kartik\tree\models\Tree
{
    /**
     * @inheritdoc
     */
    public static function tableName()
    {
        return 'tbl_tree';
    }    
}

Alternatively, you can configure your model to not extend from kartik\tree\models\Tree and instead implement and use the kartik\tree\models\TreeTrait:

namespace frontend\models;

use Yii;

class Tree extends \yii\db\ActiveRecord
{
    use kartik\tree\models\TreeTrait;

    /**
     * @inheritdoc
     */
    public static function tableName()
    {
        return 'tbl_tree';
    }    
}

Step 3: Setup Module

Configure the module named treemanager in the modules section of your Yii configuration file.

'modules' => [
   'treemanager' =>  [
        'class' => '\kartik\tree\Module',
        // other module settings, refer detailed documentation
    ]
]

Step 4: Using TreeView Widget

In your view files, you can now use the tree view directly to manage tree data as shown below:

use kartik\tree\TreeView;
echo TreeView::widget([
    // single query fetch to render the tree
    'query'             => Tree::find()->addOrderBy('root, lft'), 
    'headingOptions'    => ['label' => 'Categories'],
    'isAdmin'           => false,                       // optional (toggle to enable admin mode)
    'displayValue'      => 1,                           // initial display value
    //'softDelete'      => true,                        // normally not needed to change
    //'cacheSettings'   => ['enableCache' => true]      // normally not needed to change
]);

Step 5: Using TreeViewInput Widget

If you wish to use the tree input to select tree items, you can use the TreeViewInput widget as shown below. Normally you would use this as a dropdown with the asDropdown property set to true. If asDropdown is set to false, the treeview input widget will be rendered inline for selection.

use kartik\tree\TreeViewInput;
echo TreeViewInput::widget([
    // single query fetch to render the tree
    'query'             => Tree::find()->addOrderBy('root, lft'), 
    'headingOptions'    => ['label' => 'Categories'],
    'name'              => 'kv-product',    // input name
    'value'             => '1,2,3',         // values selected (comma separated for multiple select)
    'asDropdown'        => true,            // will render the tree input widget as a dropdown.
    'multiple'          => true,            // set to false if you do not need multiple selection
    'fontAwesome'       => true,            // render font awesome icons
    'rootOptions'       => [
        'label' => '<i class="fa fa-tree"></i>', 
        'class'=>'text-success'
    ],                                      // custom root label
    //'options'         => ['disabled' => true],
]);

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

yii2-tree-manager is released under the BSD-3-Clause License. See the bundled LICENSE.md for details.

Changelog

Change Log: `yii2-tree-manager`

Version 1.1.3

Date: 04-Mar-2022

Enhancements for Bootstrap 5.x support.
PHP 8.1 enhancements for native functions.
(bug #259): Correct icons list display based on iconEditSettings['show'].
(enh #258): Enhanced BS4 custom checkbox and radio styling for toggle inputs.
(enh #257): Enhance search close icon styling.
(enh #255): Prevent double encoding of names.
(enh #252): Activate open collective.
(bug #253): Correct TreeSecurity parsing of icons list.
(enh #251): Rename _iconPrefix to iconPrefix and make it public.
(bug #247): Correct migration error.

Version 1.1.2

Date: 13-Mar-2021

(enh #244): Correct hidden css to use BS_HIDE within bsCssMap.
(enh #240): Rename events triggered via jquery to start with treeview:.
(enh #239): Allow CSS class to hide elements to be configurable (for BS 3.x / 4.x). New property hideCssClass.
(enh #238): Add Chinese Translations.

Version 1.1.1

Date: 29-Nov-2018

(enh #232): Correct migration path in documentation.
(enh #228): Correct parsing and sending of nodeViewParams.
(enh #223): Better styling of node tree.
(enh #222): Add German Translations.
(bug #221): Correct node view form tag.
Better sharing of noNodesMessage setting during tree manage.

Version 1.1.0

Date: 03-Oct-2018

(bug #217, bug #219, enh #220): Enhance tree management for root level additions.
(bug #212): Correct icon list parsing for node.
(enh #210): Correct Russian Translations.
Correct icons initialization for BS3 Font Awesome.

Version 1.0.9

Date: 13-Sep-2018

(enh #206): Enhancements to support Bootstrap 4.x.
(enh #205): Enhance data hashing and security via a separate TreeSecurity helper class (BC Breaking).
(enh #203): Update Russian Translations.
(enh #202): Enhance node title to be configurable in messages.
(bug #200): Correct validation for TreeView::allowNewRoots.
(enh #198): New property TreeView::nodeButtonLabels to configure submit and reset button icons/labels.
(enh #197): New database field child-allowed to control children being added for certain nodes.
Move source code to src folder as per yii standards.
(enh #196): New property TreeView::nodeViewParams for setting additional (or overriding) parameters to the nodeView.
(bug #192): Correct minified JS library kv-tree.min.js.
(enh #190): Simplify treeEncryptSalt parsing without using session dependencies.
(enh #188): Enhance node manipulation jquery events to be prevented/abandoned.
(bug #185): Correct TreeTrait data structure extraction.
(enh #183): Enhance NodeController to perform safe extraction of post parameters.
(enh #180): New property TreeView::showNameAttribute to hide/show name attribute in form.
(bug #179): Validate breadcrumbs depth more correctly.
(enh #178): Topmost root node display enhancements.
(enh #172): Update Russian Translations.
(enh #121): Pass yii CSRF parameters to ajax requests to prevent 400 errors.

Version 1.0.9

Date: 29-Apr-2017

Chronological ordering of issues for change log.
(enh #167): Add alwaysDisabled setting within toolbar buttons config to force disable the button (which will never become enabled).
(enh #165): Implement tap behavior for TreeViewInput for touch based devices.
(enh #164): Enhance search functionality and search results styling.
- Add ability to highlight search terms within shortlisted search results
- Ability to override styling of the search terms with CSS.
- New boolean property hideUnmatchedSearchItems (defaults to true) that will intelligently hide nodes/node groups that do not have any matching nodes.
- More faster tree node searching
(enh #162): Update Italian Translations.
(enh #161): Update Italian Translations.
(bug #160): Correct key attribute usage in TreeTrait::removeNode.
(bug #64): Correct VIEW_PART_5 rendering.

Version 1.0.7

Date: 15-Jan-2017

(enh #158): Fire treeview.selected after node detail form is rendered.
Code formatting updates.
(bug #157): Validate request signatures correctly for invalid initial displayValue.
(enh #156): Auto node selection and session validation enhancements.
(enh #151): Root node creation enhancements.
(enh #150): Modify NodeController actions security for console apps.
(bug #148): Parse icons list array correctly in NodeController::checkSignature.
(enh #146, #145): Enable model using TreeView behavior to run within yii console app.
(enh #144): Add dependency for kartik-v/yii2-dialog in composer.
(bug #139): New boolean property cascadeSelectChildren to control child nodes selection when parent node is selected.

Version 1.0.6

Date: 16-Dec-2016

(enh #142): Implement Krajee Dialog for all alerts and confirmation.
(enh #138): Add Finnish translations.
Update message config to include all default standard translation files.
Add github contribution and issue/PR logging templates.
(enh #143): Enhance security for NodeController actions using a stateless signature to prevent data tampering:
- New property Module::treeEncryptSalt available to generate a stateless hashed signature.
- If treeEncryptSalt is not set, it will be randomly generated and stored in a session variable.
- Tree configuration settings will be signed and the same data via POST will be cross checked using yii\base\Security::hashData and yii\base\Security::validateData.
(enh #137): Add Dutch translations.
(enh #129): More correct defaulting of CSS classes.
(bug #128): Correct asset dependency.
(bug #127): Fix migration namespace.
(enh #122): Add Estonian translations.
(enh #120): Add Persian translations.
(enh #119): Add db migrations functionality.
(enh #118): Allow configuring order of toolbar buttons.
(enh #113): Option to change node label.
(enh #112): Add French translations.
(enh #105): Generate unique nodeSelected session identifier for every TreeView widget instance.
(bug #103, #104): Correct init of options and registration of assets in TreeViewInput.
(enh #100): Add composer branch alias to allow getting latest dev-master updates.
(enh #99): Add Chinese translations
(enh #98): Add new bool property TreeViewInput::autoCloseOnSelect.

Version 1.0.5

Date: 28-Dec-2015

(enh #94): Enhancements and fixes to movable node validations.
(enh #92): Ability to control auto loading of bootstrap plugin assets.

Version 1.0.4

Date: 13-Dec-2015

(enh #90): New ajax completion jQuery events for move, remove, and select.
(enh #89): Enhance ability to display and delete inactive nodes for non admin.
(enh #88): Correct validation for readonly and disabled nodes.
(enh #86): CSS Styling Enhancements.
(enh #85): Cleanup redundant code and optimize code.
(enh #83): Breadcrumbs functionality and styling enhancements.
(enh #82): Change anonymous Tree behavior to a named one (tree).
(enh #80): Enhance boolean variable parsing in HTML5 data attributes.
(enh #71): Add Russian translations.
(enh #69): Add Italian translations.
(enh #66): Add Ukranian translations.
(enh #63): Cache active state before save.
(bug #59): Maintain consistency by using keyAttribute to parse node key.
(enh #58): Add Polish translations.
(enh #57): Add Indonesian translations.

Version 1.0.3

Date: 22-Jun-2015

(enh #52): Better exception handling and translations.
(enh #51): Move properties from TreeTrait to Tree model.
(bug #47): Ensure single select for TreeViewInput when multiple is false.
(enh #46): Better styling and alignment of tree hierarchy lines across browsers.
(enh #45): Refactor code for extensibility - implement Tree model to use a TreeTrait.
(enh #44): Enhancing tree container styles for smaller device screen sizes.
(enh #43): Code style and format fixes.
(enh #42): Close tree input widget after you've selected a node.
(bug #41): Cleanup unused variables.
(enh #40): Better dynamic styling of parent node when all children nodes are removed.
(enh #39): Expose ajax settings from beforeSend ajax request in events.
(enh #38): Validate formOptions correctly for new root creation.

Version 1.0.2

Date: 22-May-2015

(enh #36): Add German translations.
(enh #35): Initialize variables prior to extraction.
(enh #34): Better ability to disable treeAttribute by setting it to false.

Version 1.0.1

Date: 11-May-2015

(bug #33): Fix minor bug in jquery plugin's button actions code.
(enh #32): Better styling for inactive and invisible nodes.
(enh #30): New property TreeView::nodeFormOptions to control HTML attributes for form.
(enh #29): Reinitialize yii active form/jquery plugins after ajax success more correctly.
(enh #28): Enhance alert fade styling for deletions.
(enh #27): Implement root node deletion.
(enh #26): Special validation for move left when the parent is root.
(enh #25): New property TreeView::showIDAttribute to hide/show key attribute in form.
(enh #21): Purify node icons feature in Tree model.
(enh #22): Create jQuery helper methods for treeview input and toggle actions.
(enh #20): Encode node names feature in Tree model.
(enh #19): Add Russian translations and fix minor bugs in kv-tree-input.js.
(enh #18): Add new plugin events and enhance plugin event parameters.

Version 1.0.0

Date: 21-Apr-2015

(enh #15): Missing namespace for Model class in TreeViewInput.
(enh #13): Use Closure methods for rendering nodeAddlViews.
(enh #10): Avoid duplicate URL encoding.
(enh #9): Cast true & false variables in $_POST to boolean.
(enh #7): Client script enhancements.
(enh #6): Selectively disable parent only flags for leaf nodes.
(enh #5): Different default parent icons for collapsed and opened node states.
(enh #4): Error trapping enhancements to Tree::activateNode and Tree::removeNode
(enh #3): Set dependencies for Asset Bundles.
(bug #2): Empty node validation on tree init.
Initial release

Statistics

Downloads

GitHub Stars

GitHub Forks

Releases

v1.1.213 March 2019
v1.1.129 November 2018
v1.1.003 October 2018
v1.0.913 September 2018
v1.0.829 April 2017
v1.0.715 January 2017
v1.0.617 December 2016
v1.0.527 December 2015
v1.0.413 December 2015
v1.0.322 June 2015
v1.0.222 May 2015
v1.0.110 May 2015
v1.0.021 April 2015

Comments

v1.1.2 is the latest of 13 releases

kartik-v

github.com/kartik-v/yii2-tree-manager

BSD-3-Clause license

Stats

150 github stars & 106 github forks

235 downloads in the last day

5052 downloads in the last 30 days

412185 total downloads

kartik-v/yii2-tree-manager An enhanced tree management module with tree node selection and manipulation using nested sets.

yii2-tree-manager

Demo

Installation

Usage

Step 1: Prepare Database

Option 1: Run DB Migrations

Option 2: Executing SQL script

Step 2: Setup Model

Step 3: Setup Module

Step 4: Using TreeView Widget

Step 5: Using TreeViewInput Widget

Contributors

Code Contributors

Financial Contributors

Individuals

Organizations

License

Changelog

Change Log: yii2-tree-manager

Version 1.1.3

Version 1.1.2

Version 1.1.1

Version 1.1.0

Version 1.0.9

Version 1.0.9

Version 1.0.7

Version 1.0.6

Version 1.0.5

Version 1.0.4

Version 1.0.3

Version 1.0.2

Version 1.0.1

Version 1.0.0

Statistics

Downloads

GitHub Stars

GitHub Forks

Releases

Comments

Stats

Change Log: `yii2-tree-manager`