0 follower

CTreeView

Package system.web.widgets
Inheritance class CTreeView » CWidget » CBaseController » CComponent
Since 1.0
Source Code framework/web/widgets/CTreeView.php
CTreeView displays a tree view of hierarchical data.

It encapsulates the excellent tree view plugin for jQuery (https://bassistance.de/jquery-plugins/jquery-plugin-treeview/).

To use CTreeView, simply sets data to the data that you want to present and you are there.

CTreeView also supports dynamic data loading via AJAX. To do so, set url to be the URL that can serve the tree view data upon request.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
actionPrefix string the prefix to the IDs of the actions. CWidget
animated string|integer animation speed. CTreeView
collapsed boolean whether the tree should start with all branches collapsed. CTreeView
control string container for a tree-control, allowing the user to expand, collapse and toggle all branches with one click. CTreeView
controller CController Returns the controller that this widget belongs to. CWidget
cookieId string The cookie name to use when persisting via persist:"cookie". CTreeView
cssFile mixed the CSS file used for the widget. CTreeView
data array the data that can be used to generate the tree view content. CTreeView
htmlOptions array additional HTML attributes that will be rendered in the UL tag. CTreeView
id string Returns the ID of the widget or generates a new one if requested. CWidget
options array additional options that can be passed to the constructor of the treeview js object. CTreeView
owner CBaseController Returns the owner/creator of this widget. CWidget
persist string Persist the tree state in cookies or the page location. CTreeView
prerendered boolean Set to skip rendering of classes and hitarea divs, assuming that is done by the serverside. CTreeView
skin mixed the name of the skin to be used by this widget. CWidget
toggle string Callback when toggling a branch. CTreeView
unique boolean set to allow only one branch on one level to be open (closing siblings which opening). CTreeView
url string|array the URL to which the treeview can be dynamically loaded (in AJAX). CTreeView
viewPath string Returns the directory containing the view files for this widget. CWidget

Protected Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
clientOptions array the javascript options CTreeView

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CWidget
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
actions() Returns a list of actions that are used by this widget. CWidget
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
beginCache() Begins fragment caching. CBaseController
beginClip() Begins recording a clip. CBaseController
beginContent() Begins the rendering of content that is to be decorated by the specified view. CBaseController
beginWidget() Creates a widget and executes it. CBaseController
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
createWidget() Creates a widget and initializes it. CBaseController
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
endCache() Ends fragment caching. CBaseController
endClip() Ends recording a clip. CBaseController
endContent() Ends the rendering of content. CBaseController
endWidget() Ends the execution of the named widget. CBaseController
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getController() Returns the controller that this widget belongs to. CWidget
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getId() Returns the ID of the widget or generates a new one if requested. CWidget
getOwner() Returns the owner/creator of this widget. CWidget
getViewFile() Looks for the view script file according to the view name. CWidget
getViewPath() Returns the directory containing the view files for this widget. CWidget
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the widget. CTreeView
raiseEvent() Raises an event. CComponent
render() Renders a view. CWidget
renderFile() Renders a view file. CBaseController
renderInternal() Renders a view file. CBaseController
run() Ends running the widget. CTreeView
saveDataAsHtml() Generates tree view nodes in HTML from the data array. CTreeView
saveDataAsJson() Saves tree view data in JSON format. CTreeView
setId() Sets the ID of the widget. CWidget
widget() Creates a widget and executes it. CBaseController

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
getClientOptions() Returns the javascript options CTreeView

Property Details

animated property
public string|integer $animated;

animation speed. This can be one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000). If not set, no animation is used.

clientOptions property read-only
protected array getClientOptions()

the javascript options

collapsed property
public boolean $collapsed;

whether the tree should start with all branches collapsed. Defaults to false.

control property
public string $control;

container for a tree-control, allowing the user to expand, collapse and toggle all branches with one click. In the container, clicking on the first hyperlink will collapse the tree; the second hyperlink will expand the tree; while the third hyperlink will toggle the tree. The property should be a valid jQuery selector (e.g. '#treecontrol' where 'treecontrol' is the ID of the 'div' element containing the hyperlinks.)

cookieId property
public string $cookieId;

The cookie name to use when persisting via persist:"cookie". Defaults to 'treeview'.

cssFile property
public mixed $cssFile;

the CSS file used for the widget. Defaults to null, meaning using the default CSS file included together with the widget. If false, no CSS file will be used. Otherwise, the specified CSS file will be included when using this widget.

data property
public array $data;

the data that can be used to generate the tree view content. Each array element corresponds to a tree view node with the following structure:

  • text: string, required, the HTML text associated with this node.
  • expanded: boolean, optional, whether the tree view node is expanded.
  • id: string, optional, the ID identifying the node. This is used in dynamic loading of tree view (see url).
  • hasChildren: boolean, optional, defaults to false, whether clicking on this node should trigger dynamic loading of more tree view nodes from server. The url property must be set in order to make this effective.
  • children: array, optional, child nodes of this node.
  • htmlOptions: array, additional HTML attributes (see CHtml::tag). This option has been available since version 1.1.7.
Note, anything enclosed between the beginWidget and endWidget calls will also be treated as tree view content, which appends to the content generated from this data.

htmlOptions property
public array $htmlOptions;

additional HTML attributes that will be rendered in the UL tag. The default tree view CSS has defined the following CSS classes which can be enabled by specifying the 'class' option here:

  • treeview-black
  • treeview-gray
  • treeview-red
  • treeview-famfamfam
  • filetree

options property
public array $options;

additional options that can be passed to the constructor of the treeview js object.

persist property
public string $persist;

Persist the tree state in cookies or the page location. If set to "location", looks for the anchor that matches location.href and activates that part of the treeview it. Great for href-based state-saving. If set to "cookie", saves the state of the tree on each click to a cookie and restores that state on page load.

prerendered property
public boolean $prerendered;

Set to skip rendering of classes and hitarea divs, assuming that is done by the serverside. Defaults to false.

toggle property
public string $toggle;

Callback when toggling a branch. Arguments: "this" refers to the UL that was shown or hidden

unique property
public boolean $unique;

set to allow only one branch on one level to be open (closing siblings which opening). Defaults to false.

url property
public string|array $url;

the URL to which the treeview can be dynamically loaded (in AJAX). See CHtml::normalizeUrl for possible URL formats. Setting this property will enable the dynamic treeview loading. When the page is displayed, the browser will request this URL with a GET parameter named 'root' whose value is 'source'. The server script should then generate the needed tree view data corresponding to the root of the tree (see saveDataAsJson.) When a node has a CSS class 'hasChildren', then expanding this node will also cause a dynamic loading of its child nodes. In this case, the value of the 'root' GET parameter is the 'id' property of the node.

Method Details

getClientOptions() method
protected array getClientOptions()
{return} array the javascript options
Source Code: framework/web/widgets/CTreeView.php#167 (show)
protected function getClientOptions()
{
    $options=$this->options;
    foreach(array('url','animated','collapsed','control','unique','toggle','persist','cookieId','prerendered') as $name)
    {
        if($this->$name!==null)
            $options[$name]=$this->$name;
    }
    return $options;
}

init() method
public void init()
Source Code: framework/web/widgets/CTreeView.php#134 (show)
public function init()
{
    if(isset($this->htmlOptions['id']))
        $id=$this->htmlOptions['id'];
    else
        $id=$this->htmlOptions['id']=$this->getId();
    if($this->url!==null)
        $this->url=CHtml::normalizeUrl($this->url);
    $cs=Yii::app()->getClientScript();
    $cs->registerCoreScript('treeview');
    $options=$this->getClientOptions();
    $options=$options===array()?'{}' : CJavaScript::encode($options);
    $cs->registerScript('Yii.CTreeView#'.$id,"jQuery(\"#{$id}\").treeview($options);");
    if($this->cssFile===null)
        $cs->registerCssFile($cs->getCoreScriptUrl().'/treeview/jquery.treeview.css');
    elseif($this->cssFile!==false)
        $cs->registerCssFile($this->cssFile);

    echo CHtml::tag('ul',$this->htmlOptions,false,false)."\n";
    echo self::saveDataAsHtml($this->data);
}

Initializes the widget. This method registers all needed client scripts and renders the tree view content.

run() method
public void run()
Source Code: framework/web/widgets/CTreeView.php#159 (show)
public function run()
{
    echo "</ul>";
}

Ends running the widget.

saveDataAsHtml() method
public static string saveDataAsHtml(array $data)
$data array the data for the tree view (see data for possible data structure).
{return} string the generated HTML for the tree view
Source Code: framework/web/widgets/CTreeView.php#183 (show)
public static function saveDataAsHtml($data)
{
    $html='';
    if(is_array($data))
    {
        foreach($data as $node)
        {
            if(!isset($node['text']))
                continue;

            if(isset($node['expanded']))
                $css=$node['expanded'] ? 'open' : 'closed';
            else
                $css='';

            if(isset($node['hasChildren']) && $node['hasChildren'])
            {
                if($css!=='')
                    $css.=' ';
                $css.='hasChildren';
            }

            $options=isset($node['htmlOptions']) ? $node['htmlOptions'] : array();
            if($css!=='')
            {
                if(isset($options['class']))
                    $options['class'].=' '.$css;
                else
                    $options['class']=$css;
            }

            if(isset($node['id']))
                $options['id']=$node['id'];

            $html.=CHtml::tag('li',$options,$node['text'],false);
            if(!empty($node['children']))
            {
                $html.="\n<ul>\n";
                $html.=self::saveDataAsHtml($node['children']);
                $html.="</ul>\n";
            }
            $html.=CHtml::closeTag('li')."\n";
        }
    }
    return $html;
}

Generates tree view nodes in HTML from the data array.

saveDataAsJson() method
public static string saveDataAsJson(array $data)
$data array the data for the tree view (see data for possible data structure).
{return} string the JSON representation of the data
Source Code: framework/web/widgets/CTreeView.php#238 (show)
public static function saveDataAsJson($data)
{
    if(empty($data))
        return '[]';
    else
        return CJavaScript::jsonEncode($data);
}

Saves tree view data in JSON format. This method is typically used in dynamic tree view loading when the server code needs to send to the client the dynamic tree view data.