0 follower

CTreeView

Package	system.web.widgets
Inheritance	class CTreeView » CWidget » CBaseController » CComponent
Since	1.0
Version	$Id$
Source Code	framework/web/widgets/CTreeView.php

CTreeView displays a tree view of hierarchical data.

It encapsulates the excellent tree view plugin for jQuery (http://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

Property	Type	Description	Defined 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	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	id of the widget.	CWidget
options	array	additional options that can be passed to the constructor of the treeview js object.	CTreeView
owner	CBaseController	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
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

Property	Type	Description	Defined By
clientOptions	array	the javascript options	CTreeView

Public Methods

Hide inherited methods

Method	Description	Defined 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
getController()	Returns the controller that this widget belongs to.	CWidget
getEventHandlers()	Returns the list of attached event handlers for an event.	CComponent
getId()	Returns id of the widget.	CWidget
getOwner()	Returns owner/creator of this widget. It could be either a widget or a controller.	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 id of the widget.	CWidget
widget()	Creates a widget and executes it.	CBaseController

Protected Methods

Hide inherited methods

Method	Description	Defined 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 in 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.

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 'source' whose value is 'root'. 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 'source' 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#166 (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#133 (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');
    else if($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#158 (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#182 (show)


public static function saveDataAsHtml($data)
{
    $html='';
    if(is_array($data))
    {
        foreach($data as $node)
        {
            if(!isset($node['text']))
                continue;
            $id=isset($node['id']) ? (' id="'.$node['id'].'"') : '';
            if(isset($node['expanded']))
                $css=$node['expanded'] ? 'open' : 'closed';
            else
                $css='';
            if(isset($node['hasChildren']) && $node['hasChildren'])
            {
                if($css!=='')
                    $css.=' ';
                $css.='hasChildren';
            }
            if($css!=='')
                $css=' class="'.$css.'"';
            $html.="<li{$id}{$css}>{$node['text']}";
            if(isset($node['children']))
            {
                $html.="\n<ul>\n";
                $html.=self::saveDataAsHtml($node['children']);
                $html.="</ul>\n";
            }
            $html.="</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#225 (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.