| javascript_components

# Class: Bs_Tree Source Location: /components/tree/Bs_Tree.class.js.php
### Class Overview
features: all the normal behavior you know from a tree. #### Author(s): andrej arn <at blueshoes dot org> #### Copyright: blueshoes.org | ### Variables $autoCollapse $captionBgColor $checkboxSystemGuiNochange $checkboxSystemIfPartlyThenFull $checkboxSystemImgDir $checkboxSystemWalkTree $divStyle $draggable $imageDir $imageHeight $linkStyle $lookAhead $radioButtonName $showPseudoElement $stopWatch $useAutoSequence $useCheckboxSystem $useFolderIcon $useLeaf $useRadioButton $walkTree $_constructor $_currentActiveElement $_elementSequence | ### Methods debugDumpTree draw drawInto elementCheckboxEvent elementClose elementCloseWalkDown elementCloseWalkUp elementOpen elementOpenWalkUp elementToggleOpenClose executeOnElement getActiveElement getElement getElementByCaptionPath getJavascriptCode getLastError initByArray old_drawInto openPath removeElement setActiveElement toHtml _afterImgPreload _imgPreload
### Inherited Variables | ### Inherited Methods
### Class Details [line 24] features: all the normal behavior you know from a tree. optional autocollapse; only one "subtree" may be open at a time. hide first element, in the windows explorer (file manager) that would be the 'desktop'. it's the root element. then one that has no siblings. this way you can have root elements with siblings. checkbox system (like an ms installer on windows). radio button (to use it as form field where one can select a node). (since bs4.3) dependencies: /_bsJavascript/core/lang/Bs_Array.class.js #### Tags:
copyright: | blueshoes.org
author: | andrej arn <at blueshoes dot org>
[ Top ] ### Class Variables #### $autoCollapse = false [line 54] if set to true then only one node can be open at a time. any other open sibling will close when another opens. #### Tags:
var: | autoCollapse
access: | public
Type: | bool
[ Top ] #### $captionBgColor = "yellow" [line 91] the background color that is used on the caption if the tree element is active. #### Tags:
var: | captionBgColor
access: | public
Type: | string
[ Top ] #### $checkboxSystemGuiNochange = [line 183] if set to true then the user cannot change things by clicking. changes through the api functions (for the coder, you) are still possible. #### Tags:
var: | checkboxSystemGuiNochange
see: | var useCheckboxSystem
access: | public
Type: | bool
[ Top ] #### $checkboxSystemIfPartlyThenFull = true [line 157] if a checkbox is checked partly, and one clicks it, what should happen? we can check it completely, or uncheck it. default is to check it completely, set this var to false if you want to have it unchecked. #### Tags:
var: | checkboxSystemIfPartlyThenFull
see: | var useCheckboxSystem (and others)
access: | public
Type: | bool
[ Top ] #### $checkboxSystemImgDir = [line 174] if you want to use other icons than the default ones, you can specify another path here. there are different ones to chose from, and you can even create your own (path/icons) (just keep the same file names...). note: the image width/height is set to 13/13 for the tree. when you use the checkbox alone, default is 20/20. if you want something else than 13/13 in the tree, add some functionality. #### Tags:
var: | checkboxSystemImgDir
see: | Bs_Tree::$useCheckboxSystem
access: | public
Type: | string
[ Top ] #### $checkboxSystemWalkTree = 3 [line 145] how the checkboxes should walk the tree if a checkbox value changes. eg you're in level 3. now if you check the box, should all levels down automatically be checked aswell? should level 2 be "partly selected" so the user sees that something below is selected, à la windows installer? = no walking = walking up only = walking down only = walking both ways, up and down (default) = walking down to uncheck only, walking up for both (quite useful, an option to consider instead of 3.) #### Tags:
var: | checkboxSystemWalkTree
see: | var useCheckboxSystem
access: | public
Type: | int
[ Top ] #### $divStyle = 'font-family: Arial, Helvetica, sans-serif; font-size: 11px;' [line 109] a css style string to use on the div. #### Tags:
var: | divStyle
since: | bs4.5
see: | Bs_TreeElement.divStyle
access: | public
Type: | string
[ Top ] #### $draggable = false [line 282] tells if the tree elements are draggable or not. #### Tags:
var: | draggable
since: | bs4.4
access: | public
Type: | bool
[ Top ] #### $imageDir = '/_bsJavascript/components/tree/img/win98/' [line 210] the dir where the images (icons) are located. feel free to create your own dir with your own images, just name them the same way.
Type: | mixed
[ Top ] #### $imageHeight = 16 [line 220] the image height for the icons (folder icon, lines etc). i don't think you need to change this. only do it if the images in this.imageDir have a different height. #### Tags:
var: | imgHeight
since: | bs4.5
access: | public
Type: | int
[ Top ] #### $linkStyle = [line 100] a css style string to use on the link. #### Tags:
var: | linkStyle
since: | bs4.4
see: | Bs_TreeElement.linkStyle
access: | public
Type: | string
[ Top ] #### $lookAhead = 2 [line 84] how much to preload down (how many levels of tree elements). -1 = unlimited. not recommended for large trees! checkboxes with checkboxSystemWalkTree: if a checkbox click needs to walk down the tree (checkboxSystemWalkTree >= 2) then the tree elements data must be loaded, and tree element objects are instanced. that takes a little time. but the rendering is still omitted, which saves a lot of time. when the browser has to render all those icons for hundreds of (invisible) nodes... otherwise: the node objects are not instanced at all. they are once the user opens nodes into that direction. this makes it possible to use the tree even with thousands of nodes. check example 12 for this feature: http://www.blueshoes.org/_bsJavascript/components/tree/examples/example12.html history: the original idea was to call this "preloadDown" but that var has never been implemented. #### Tags:
var: | lookAhead
since: | bs4.5
access: | public
Type: | int
[ Top ] #### $radioButtonName = [line 203] the field name for the radio button. if not specified then something will be made up. #### Tags:
var: | radioButtonName
todo: | allow each TreeElement to overwrite this setting for itself.
since: | bs4.3
see: | vars this.useRadioButton, Bs_TreeElement.radioButtonSelected
access: | public
Type: | string
[ Top ] #### $showPseudoElement = false [line 116] don't set to true, it won't work (currently). #### Tags:
var: | showPseudoElement
access: | public
Type: | bool
[ Top ] #### $stopWatch = [line 338] reference to a Bs_StopWatch instance, if used. helps while profiling, looking for slow code. #### Tags:
see: | Bs_StopWatch class
since: | bs-4.5
access: | public
Type: | object stopWatch
[ Top ] #### $useAutoSequence = true [line 274] every tree element needs a unique id to be identified, just like records in a database. this can be done for you internally (default). but if you want to access tree elements from outside code you have to tell the tree somehow which element you mean. a string (the caption) is not good enough because it is not unique. so if you set this var to false, your arrays need to have an 'id' field that is truly unique over the whole structure, in the whole tree. #### Tags:
var: | useAutoSequence
see: | vars this._clearingHouse, this._elementSequence
access: | public
Type: | bool
[ Top ] #### $useCheckboxSystem = false [line 125] specifies if the built-in checkbox system is used. even if you don't want it, check it out, it's cool. :-) #### Tags:
var: | useCheckboxSystem
see: | vars checkboxSystemWalkTree, Bs_Tree::$checkboxSystemImgDir, Bs_Tree::$checkboxSystemGuiNochange, Bs_Tree::$checkboxSystemIfPartlyThenFull
access: | public
Type: | bool
[ Top ] #### $useFolderIcon = true [line 229] if the folder icons (includes leaf icon) should be used or not. default is true. #### Tags:
var: | useFolderIcon
see: | this.useLeaf
access: | public
Type: | bool
[ Top ] #### $useLeaf = true [line 238] uses a leaf icon instead of the default folder icon for the last element in a tree. default is true. this is neat, see 'leaf.gif'. #### Tags:
var: | useLeaf
see: | this.useFolderIcon
access: | public
Type: | bool
[ Top ] #### $useRadioButton = false [line 193] specifies if the built-in radio button is used. #### Tags:
var: | useRadioButton
todo: | allow each TreeElement to overwrite this setting for itself. at least to deactivate.
since: | bs4.3
see: | vars this.radioButtonName, Bs_TreeElement.radioButtonSelected
access: | public
Type: | bool
[ Top ] #### $walkTree = true [line 258] if we should walk the tree up to fetch a tree elements value (setting). if not then we're going to ask the tree object immediatly if the tree element we're looking at does not have the value. by setting this var to false, you gain speed, but loose functionality. it works like apache's htaccess files. if you're down the tree somewhere, apache walks the tree up until it finds a .htaccess file. once apache found one, it will be used. so these .htaccess config files inherit their settings down. the same is done here. and if you don't want the tree walking, only the current tree node will be checked, and then the tree object itself will be asked for a value. #### Tags:
var: | walkTree
see: | TreeElement._getVar();
access: | public
Type: | bool
[ Top ] #### $_constructor = [line 982]
Type: | mixed
[ Top ] #### $_currentActiveElement = [line 312] the currently "active" tree element, if any. #### Tags:
var: | (reference to an instance of Bs_TreeElement)
see: | this.getActiveElement(), this.setActiveElement(), Bs_TreeElement->setActive(), Bs_TreeElement->unsetActive()
Type: | object _currentActiveElement
[ Top ] #### $_elementSequence = 0 [line 321] sequence used to give tree elements a unique id. starts at 0 and increases itself on each element creation. #### Tags:
var: | _elementSequence
see: | var this.useAutoSequence
access: | protected
Type: | int
[ Top ] ### Class Methods ### method debugDumpTree [line 858]
`void debugDumpTree( int elm, string indent)`
debug method to see the tree content in a js alert box. calls itself recursively to loop the children. #### Tags:
since: | bs4.4
access: | public
#### Parameters:
int | elm | elm (the element, not specified = use first element (pseudo-element))
string | indent | indent (used internally only on recursive calls)
[ Top ] ### method draw [line 564]
`string draw( )`
outputs the tree as rendered html to the browser (document.writeln). #### Tags:
see: | Bs_Tree::toHtml(), Bs_Tree::drawInto()
access: | public
[ Top ] ### method drawInto [line 977]
`void drawInto( mixed id)`
[ Top ] ### method elementCheckboxEvent [line 844]
`void elementCheckboxEvent( mixed id, bool value)`
#### Tags:
see: | Bs_TreeElement->checkboxEvent() for details.
access: | public
#### Parameters:
mixed | id | id
bool | value | value
[ Top ] ### method elementClose [line 761]
`void elementClose( mixed id)`
closes the tree-element with the given id. note that the children won't be closed. they disappear when closing their parent, sure, but if you re-open this element they will be back as they were. open or closed. only works once the tree has been rendered to the browser. #### Tags:
see: | Bs_Tree::elementOpen(), Bs_Tree::elementOpenWalkUp()
access: | public
#### Parameters:
mixed | id | id
[ Top ] ### method elementCloseWalkDown [line 711]
`bool elementCloseWalkDown( mixed id)`
same as elementClose but also walks down the tree (to the leaf) closing all children. calls itself recursively. #### Tags:
return: | (true on success, false on failure)
since: | bs4.4
see: | Bs_Tree::elementClose(), Bs_Tree::elementCloseWalkUp()
access: | public
#### Parameters:
mixed | id | id (don't specify to close all tree elements)
[ Top ] ### method elementCloseWalkUp [line 689]
`bool elementCloseWalkUp( mixed id)`
same as elementClose but also walks up the tree (to the root) closing all parents. calls itself recursively. #### Tags:
return: | (true on success, false on failure)
since: | bs4.4
see: | Bs_Tree::elementOpen(), Bs_Tree::elementClose(), Bs_Tree::elementOpenWalkUp()
access: | public
#### Parameters:
mixed | id | id
[ Top ] ### method elementOpen [line 742]
`void elementOpen( mixed id)`
opens up the tree-element with the given id. note that if one of the parents is not open, you do not see the change immediatly. parents have to be opened manually, this method does not do it for you. or use elementOpenWalkUp(). only works once the tree has been rendered to the browser. #### Tags:
see: | Bs_Tree::elementOpenWalkUp(), Bs_Tree::elementClose()
access: | public
#### Parameters:
mixed | id | id
[ Top ] ### method elementOpenWalkUp [line 667]
`bool elementOpenWalkUp( mixed id)`
same as elementOpen but also walks up the tree (to the root) opening all parents. calls itself recursively. #### Tags:
return: | (true on success, false on failure)
since: | bs4.3
see: | Bs_Tree::elementOpen(), Bs_Tree::elementClose()
access: | public
#### Parameters:
mixed | id | id
[ Top ] ### method elementToggleOpenClose [line 652]
`void elementToggleOpenClose( mixed id)`
opens the element if closed, and vice versa. #### Tags:
access: | public
#### Parameters:
mixed | id | id (element id)
[ Top ] ### method executeOnElement [line 603]
`mixed executeOnElement( mixed id, string func, array params)`
calls an api function of the tree element specified (by id). possible methods are (currently there are about 15): open close hasChildren ... (check out the class api functions yourself the first 2 params are must have. you can give a 3rd param. if you do, that array will be cut into it's elements, and the elements will be used as params for the function you want to call. note: a max of 4 params is currently defined. if you want more, recode. #### Tags:
return: | (the return value of the called function, void if that was not possible.)
see: | Bs_Tree::getElement()
access: | public
#### Parameters:
mixed | id | id (string, number, whatever it is)
string | func | func (function name, without brackets!)
array | params | params (vector, see above)
[ Top ] ### method getActiveElement [line 396]
`object (or getActiveElement( )`
returns the currently active tree element as object. active means the 'clicked' one. it has nothing to do with the checkbox (in case you're using this.useCheckboxSystem) or the radio (if you're using useRadioButton). #### Tags:
return: | bool false if none)
since: | bs4.3
see: | var this._currentActiveElement, this.setActiveElement()
access: | public
[ Top ] ### method getElement [line 505]
`object (byref) getElement( mixed elementId)`
returns a reference to the tree-element with the given id. special case: elementId 0 = first element aka pseudo element. #### Tags:
throws: | bool false
access: | public
#### Parameters:
mixed | elementId | elementId
[ Top ] ### method getElementByCaptionPath [line 812]
`object (instance getElementByCaptionPath( array data)`
returns the tree element for the given 'caption path'. example usage: var myArr = new Array('world', 'europe', 'france'); var myElm = yourTree.getElementByCaptionPath(myArr); note that it does not work if you have two tree elements with the same caption (and the one you want does not come first). #### Tags:
return: | of Bs_TreeElement)
throws: | bool false (not found)
access: | public
#### Parameters:
array | data | data
[ Top ] ### method getJavascriptCode [line 642]
`string getJavascriptCode( )`
returns the js code that's needed to build this tree. #### Tags:
see: | Bs_TreeElement.getJavascriptCode()
access: | public
[ Top ] ### method getLastError [line 900]
`mixed getLastError( )`
returns the last occured error. #### Tags:
return: | (string if there was an error, bool false otherwise.)
see: | var this._errorArray
access: | public
[ Top ] ### method initByArray [line 371]
`bool initByArray( array arr)`
inits the tree with the given data array (holding info about the tree elements). #### Tags:
return: | (true on success, false on failure)
access: | public
#### Parameters:
array | arr | arr
[ Top ] ### method old_drawInto [line 917]
`void old_drawInto( string id)`
outputs the tree as rendered html into the element specified. #### Tags:
see: | Bs_Tree::draw(), Bs_Tree::toHtml()
access: | public
#### Parameters:
string | id | id (element id)
[ Top ] ### method openPath [line 787]
`bool openPath( array data, string valueType)`
opens up the tree nodes to the element specified. you need to know the path to your element, for examples the captions. example: you have a tree node with the captions "world", "europe" , "france". now you don't know the id's of the tree elements, but you want to open up the tree to (and including) the "france" element. so you do: var myArr = new Array('world', 'europe', 'france'); yourTree.openPath(myArr, 'caption'); note: if you know the id of that element, use elementOpenWalkUp(). but if you don't, this method may help you. note that it currently does not work if you have two tree elements with the same caption (and the one you want does not come first). #### Tags:
return: | (true on success, false if not found.)
access: | public
#### Parameters:
array | data | data
string | valueType | valueType (currently only 'caption' is supported', and it's the default anyway.)
[ Top ] ### method removeElement [line 527]
`bool removeElement( mixed elementId)`
removes the tree-element specified and all it's children. internally we have to do this: 1) in the parent of the given elementId, remove it from the _children array. 2) remove it and all its children in the _clearingHouse. 3) if the parent has already been rendered, re-render it. #### Tags:
return: | (true on success, false if it does not exist.)
since: | bs4.4
access: | public
[ Top ] ### method setActiveElement [line 414]
`void setActiveElement( object treeElement treeElement)`
sets the currently active tree element. don't use this, use yourElement.setActive() instead. i think this method should be declared private. #### Tags:
since: | bs4.3
see: | var this._currentActiveElement, this.getActiveElement()
access: | public
#### Parameters:
object treeElement | treeElement |
[ Top ] ### method toHtml [line 577]
`vector toHtml( )`
returns the tree as rendered html string #### Tags:
return: | (element 0=html, 1=js (to execute))
see: | Bs_Tree::draw(), Bs_Tree::drawInto()
access: | public
[ Top ] ### method _afterImgPreload [line 964]
`void _afterImgPreload( )`
[ Top ] ### method _imgPreload [line 939]
`void _imgPreload( )`
[ Top ] Documentation generated on Mon, 29 Dec 2003 22:18:34 +0100 by phpDocumentor 1.2.3