treegrid.js

javascript 很酷的类库

    // If not specified this this behavior is determined by <code>treeGrid.showCustomIconOpen</code>
    // for this node.
    // @see treeGrid.customIconProperty
    // @see treeGrid.showCustomIconOpen
    // @visibility external
    // @group treeIcons
    //<
    customIconOpenProperty:"showOpenIcon",
    
    //> @attr   treeGrid.customIconDropProperty (string : "showDropIcon" : [IRWA])
    // For folder nodes showing custom icons (set via the +link{treeGrid.customIconProperty}),
    // this property allows the developer to specify on a per-node basis whether a
    // drop state icon (with +link{treeGrid.dropIconSuffix}) should be displayed when the 
    // user drop-hovers over this folder.<br>
    // Set <code>node[treeGrid.customIconDropProperty]</code> to true to show the drop state
    // icons, or false to suppress this.<br>
    // If not specified this this behavior is determined by <code>treeGrid.showCustomIconDrop</code>
    // for this node.
    // @see treeGrid.customIconProperty
    // @see treeGrid.showCustomIconDrop
    // @visibility external
    // @group treeIcons
    //<
    customIconDropProperty:"showDropIcon",

    // ---------------------------------
    // DEPRECATED ICON PROPERTIES:
    // 
            
    //>	@attr	treeGrid.folderOpenImage        (String : null : [IRW])
    //          The filename of the default icon for all open folder nodes in this treeGrid.
    //      @visibility external
    //  @deprecated as part of SmartClient release 5.5 in favor of +link{TreeGrid.folderIcon}
    //<

    //>	@attr	treeGrid.folderClosedImage		(string : null : [IRW])
    // The filename of the default icon for all closed folder nodes in this treeGrid. Use
    // the node.icon property (null by default) to specify a custom image for an individual
    // folder node. The same custom image will be used for both the open and closed folder
    // images.
    //      @visibility external
    //  @deprecated as part of SmartClient release 5.5 in favor of +link{TreeGrid.folderIcon}
    //<

    //>	@attr	treeGrid.folderDropImage       (String : null : [IRW])
    // The filename of the icon displayed for a folder node that will accept drag-and-drop
    // data when the mouse is released.
    //      @visibility external
    //  @deprecated as part of SmartClient release 5.5 in favor of +link{TreeGrid.folderIcon}    
    //<

    //>	@attr	treeGrid.fileImage             (SCImgURL : "[SKIN]file.gif" : [IRW])
    // The filename of the default icon for all leaf nodes in this treeGrid. Use the
    // node.icon property (null by default) to specify a custom image for an individual
    // node.
    //      @visibility external
    //  @deprecated as part of SmartClient release 5.5 in favor of +link{TreeGrid.nodeIcon}
    //<
    
    // --------------------

    //>	@attr	treeGrid.manyItemsImage        (SCImgURL : "[SKIN]folder_file.gif" : [IRW])
    // The filename of the icon displayed use as the default drag tracker when for multiple
    // files and/or folders are being dragged.
    // @group dragdrop
    //      @visibility external
    //<
	manyItemsImage:"[SKIN]folder_file.gif",
    
    //>	@attr	treeGrid.showConnectors (boolean : false : [IRW])
    //  Should this treeGrid show connector lines illustrating the trees hierachy?
    // @group treeIcons
    //      @visibility external
    // @example connectors
    //<
    // Current implementation handles only "sparse" hierachy lines - in other words we are not 
    // showing vertical continuation lines for each level of indenting within the tree - 
    // the hierachy lines are only shown for the most indented path.
    
    showConnectors : false,

    //>	@attr	treeGrid.openerImage        (SCImgURL : "[SKIN]opener.gif" : [IR])
    // The base filename of the opener icon for the folder node when 'showConnectors' is false
    // for this TreeGrid.<br>
    // The opener icon is displayed beside the folder icon in the Tree column for folder nodes.
    // Clicking on this icon will toggle the open state of the folder.<br>
    // The filenames for these icons are assembled from this base filename and the state of the
    // node, as follows:<br>
    // If the openerImage is set to <code>{baseName}.{extension}</code>, 
    // <code>{baseName}_opened.{extension}</code> will be displayed next to opened folders, and
    // <code>{baseName}_closed.{extension}</code> will be displayed next to closed folders, or
    // if this page is in RTL mode, <code>{baseName}_opened_rtl.{extension}</code> and
    // <code>{baseName}_closed_rtl.{extension}</code> will be used.
    //
    // @group treeIcons
    //      @visibility external
    //<
	openerImage:"[SKIN]opener.gif",
    

    //>	@attr	treeGrid.connectorImage        (SCImgURL : "[SKIN]connector.gif" : [IR])
    // The base filename of the opener icon for the folder node when 'showConnectors' is true
    // for this TreeGrid.<br>
    // The opener icon is displayed beside the folder icon in the Tree column for all nodes if
    // showConnectors is true, and can be used to display both folder-toggling controls and 
    // hierachy connector lines for the tree.
    // Clicking on this icon for a folder with child nodes will toggle the open state of the 
    // folder.<br>
    // The filenames for these icons are assembled from this base filename and the state of the
    // node, as follows:<br>
    // Assume the connectorImage is set to <code>{baseName}.{extension}</code><br>
    // The full set of images to be displayed is:
    // <ul>
    // <li><code>{baseName}_single[_rtl].{extension}</code>: node with no children, where the 
    //      previous row in the treeGrid doesn't contain a sibling or parent of this node, and
    //      the next row in the treeGrid doesn't contain a sibling of this node.
    // <li><code>{baseName}_start[_rtl].{extension}</code>:  node with no children, where the 
    //      previous row in the treeGrid doesn't contain a sibling or parent of this node.
    // <li><code>{baseName}_end[_rtl].{extension}</code>:  node with no children, where the 
    //      next row in the treeGrid doesn't contain a sibling of this node.
    // <li><code>{baseName}_middle[_rtl].{extension}</code>:  node with no children, where the 
    //      next row in the treeGrid does contain a sibling of this node, and the previous row
    //      in the treeGrid contains either this node's parent, or a sibling of this node.
    // <li><code>{baseName}_opened_single[_rtl].{extension}</code> opened folder node with 
    //      children where the previous row in the tree grid is not a sibling of this node, or
    //      this node's parent.
    // <li><code>{baseName}_opened_end[_rtl].{extension}</code> opened folder node with
    //      children where the previous row in the tree grid is either a sibling of this node, 
    //      or this node's parent.
    // <li><code>{baseName}_closed_single[_rtl].{extension}</code> closed folder node with
    //      children where the previous row in the treeGrid doesn't contain a sibling or parent 
    //      of this node, and the next row in the treeGrid doesn't contain a sibling of this node.
    // <li><code>{baseName}_closed_start[_rtl].{extension}</code> closed filder with children, where the 
    //      previous row in the treeGrid doesn't contain a sibling or parent of this node.      
    // <li><code>{baseName}_closed_end[_rtl].{extension}</code> closed folder with children, where the 
    //      next row in the treeGrid doesn't contain a sibling of this node.     
    // <li><code>{baseName}_closed_middle[_rtl].{extension}</code> closed folder with children, where the 
    //      next row in the treeGrid does contain a sibling of this node, and the previous row
    //      in the treeGrid contains either this node's parent, or a sibling of this node.    
    // </ul>           
    // (Note '[_rtl]' means that "_rtl" will be attached if isRTL() is true for this widget).
    // @group treeIcons
    //      @visibility external
    //<
	connectorImage:"[SKIN]connector.gif",
    
    // Disble groupBy for TreeGrids altogether - we're already showing data-derived hierachy!
    canGroupBy: false,
    
    // heavily used strings for templating
    _openIconIDPrefix: "open_icon_",
    _extraIconIDPreix:"extra_icon_",
    _iconIDPrefix: "icon_",
    _titleField: "nodeTitle"

});

isc.TreeGrid.addMethods({

initWidget : function () {
	this.invokeSuper(isc.TreeGrid, this._$initWidget);
    
    // if no dataSource is specified on this TG, pick up the dataSource off the data model
    if (!this.dataSource && this.data != null && this.data.dataSource) {
        this.dataSource = this.data.dataSource;
    }

	// if the fields are not set or of zero length, initialize with a single TREE_FIELD
    // NB: it is not safe to try to determine the tree field before setFields has been run,
    // since fields in this.fields might not be shown if they have a showIf:false
	if (!this.fields || this.fields.length == 0) {
		this.fields = [isc.TreeGrid.TREE_FIELD];
    }
},

// override setDataSource - if no fields were passed in, default to showing the tree field.
// This matches the behavior if a datbound treeGrid is initialized with no fields.
setDataSource : function (ds, fields) {

    if (fields == null || fields.length == 0) {
        fields = [isc.TreeGrid.TREE_FIELD];
    }
    return this.Super("setDataSource", [ds, fields]);
},

// make sure one of the fields has been set up as the special "tree field"
_initTreeField : function () {

	// if the fields are not set or of zero length, initialize with a single TREE_FIELD
	if (!this.fields || this.fields.length == 0) {
		this.fields = [isc.TreeGrid.TREE_FIELD];
	} else {
    
        // see which field is the tree field.  Note this handles both the case that the special
        // constant TreeGrid.TREE_FIELD was provided as a field, and the case that the caller
        // marked a field as a the treeField.
        
        // if none of the fields is specified as the treeField, we look for a "title" field,
        // then we default to the first field in the array; we use this.completeFields so that
        // the treeField property of hidden fields will be checked as well--otherwise we would
        // default another field to be the tree field, and end up with more than one treeField
        // if the hidden treeField became visible again.
        
        var completeFields = this.completeFields,
            fields = this.fields,
            treeFieldNum;
        
        for (var i = 0; i < completeFields.length; i++) {
            if (completeFields[i].treeField) {
                treeFieldNum = fields.indexOf(completeFields[i]);
                break;
            }
        }

        if (treeFieldNum == null) {
            // if autoAssignTreeField has been set false, don't assign a default tree field in 
            // the absence of an explicit marker
            if (!this.autoAssignTreeField) return;
        
    	    // if there is no explicit marker, look for the field that matches the
            // titleProperty declared on the Tree
    	    var titleProp = this.data.titleProperty,
                fieldNum = fields.findIndex(this.fieldIdProperty, titleProp);
            if (fieldNum != -1) treeFieldNum = fieldNum;
        }

        // use the first field if none were marked as the tree field
        if (treeFieldNum == null) treeFieldNum = 0;

        // store the chosen fieldNum
        this._treeFieldNum = treeFieldNum;

        // use the properties of TREE_FIELD as defaults for the field
        // Note: We're manipulating the field object in the fields array. 
        // this.completeFields also contains a pointer to this object.
        // We don't want to replace the slot in either array with a different object as
        // that would make them out of synch (causes errors sorting, etc.)
        // - instead just copy any unset properties across from the TREE_FIELD field.
        var treeField = fields[treeFieldNum],
            fieldDefaults = isc.TreeGrid.TREE_FIELD;
        for (var property in fieldDefaults) {
            if (treeField[property] == null) {
                treeField[property] = fieldDefaults[property]
            }
        }
    }
},

// because we store _treeFieldNum as a number, we need to recalc when fields are changed or
// their numbering changes.  This include setFields(), reorderFields(), showField() and hideField().
// 
// Note that the chosen treeField won't shift on reorder, because we install the TREE_FIELD
// properties into the chosen field, and the TREE_FIELD properties includes the treeField:true
// marker.
deriveVisibleFields : function (a,b,c,d) {
    this.invokeSuper(isc.TreeGrid, "deriveVisibleFields", a,b,c,d);
    this._initTreeField();
},

getEmptyMessage : function () {
    // can't just check for data != null because ListGrid initWidget sets data to [] if unset
    // and we must make sure we have a tree.
    if (isc.isA.Tree(this.data) && this.data.getLoadState(this.data.getRoot()) == isc.Tree.LOADING) 
        return this.loadingDataMessage;
    return this.emptyMessage;
},

isEmpty : function () {
    // can't just check for data != null because ListGrid initWidget sets data to [] if unset
    // and we must make sure we have a tree.
    if (!isc.isA.Tree(this.data)) return true;

    var root = this.data.getRoot();
    if (root == null) return true;

    var rootHasChildren = this.data.hasChildren(root);
    if (rootHasChildren || this.showRoot || this.data.showRoot) return false;
    return true;
},


// View state stuff
 
//> @type   treeGridOpenState  
// An object containing the open state for a treeGrid.
// Note that this object is not intended to be interrogated directly, but may be stored 
// (for example) as a blob on the server for state persistence across sessions.
// 
// @group viewState
// @visibility external
//<
// treeGridOpenState object is implemented as an array of strings, each of which is the path
// to a currently open folder (all other folders are closed)


//>	@method	treeGrid.getOpenState() 
// Returns a snapshot of the current open state of this grid's data as
// a +link{type:treeGridOpenState} object.<br>
// This object can be passed to +link{treeGrid.getOpenState()} to open the same set of folders
// within the treeGrid's data (assuming the nodes are still present in the data).
// @return (treeGridOpenState) current sort state for the grid.
// @group viewState
// @see treeGrid.getOpenState()
// @visibility external
//<
getOpenState : function () {
    var tree = this.data;
    if (tree == null) {
        this.logWarn("getOpenState() called for a treeGrid with no data");
        return [];