listgrid.js

javascript 很酷的类库

    // data : [
    //     {field1: "foo", field2: "bar", customProperty:5},
    //     {field1: "field1 value", field2: "field2 value", enabled:false}
    // ]
    // </pre>
    // Each line of code in the <code>data</code> array above creates one JavaScript Object via
    // JavaScript {type:ObjectLiteral,object literal} notation.  These JavaScript Objects are
    // used as ListGridRecords.
    // <P>
    // Both records shown above have properties whose names match the name property of a
    // ListGridField, as well as additional properties.  The second record will be disabled due to
    // <code>enabled:false</code>; the first record has a property "customProperty" which will
    // have no effect by default but which may accessed by custom logic.
    // <P>
    // After a ListGrid is created and has loaded data, records may be accessed via
    // +link{listGrid.data}, for example, listGrid.data.get(0) retrieves the first record.
    // ListGridRecords are also passed to many events, such as
    // +link{ListGrid.cellClick,cellClick()}.
    // <P>
    // A ListGridRecord is always an ordinary JavaScript Object regardless of how the grid's
    // dataset is loaded (static data, java server, XML web service, etc), and so supports the
    // normal behaviors of JavaScript Objects, including accessing and assigning to properties
    // via dot notation:
    // <pre>
    //     var fieldValue = record.<i>fieldName</i>;
    //     record.<i>fieldName</i> = newValue;
    // </pre>
    // <P>
    // Note however that simply assigning a value to a record won't cause the display to be
    // automatically refreshed - +link{listGrid.refreshCell()} needs to be called.  Also,
    // consider +link{group:editing,editValues vs saved values} when directly modifying
    // ListGridRecords.
    // <P>
    // See the attributes in the API tab for the full list of special properties on
    // ListGridRecords that will affect the grid's behavior.
    //
    // @treeLocation Client Reference/Grids/ListGrid
    // @see ListGrid.data
    // @visibility external
    //<
    

    //> @attr listGridRecord.enabled (boolean : null : IR)
    //
    // Affects the visual style and interactivity of the record.  If set to <code>false</code>
    // the record (row in a +link{ListGrid} or +link{TreeGrid}) will not highlight when the
    // mouse moves over it, nor will it respond to mouse clicks.
    //
    // @visibility external
    // @example disabledRows
    //<

    //> @attr listGridRecord.isSeparator (boolean : null : IR)
    //
    // Default property name denoting a separator row.<br>
    // When set to <code>true</code>, defines a horizontal separator in the listGrid
    // object. Typically this is specified as the only property of a record object, since a
    // record with <code>isSeparator:true</code> will not display any values.<br>
    // Note: this attribute name is governed by +link{ListGrid.isSeparatorProperty}.
    // @visibility external
    //<
    
    //>@attr    listGridRecord.singleCellValue (HTML : null : IRW)
    // Default property name denoting the single value to display for all fields of this row.
    // If this property is set for some record, the record will be displayed as a single 
    // cell spanning every column in the grid, with contents set to the value of this
    // property.<br>
    // Note: this attribute name is governed by +link{ListGrid.singleCellValueProperty}.
    // @visibility external
    //<


    //> @attr listGridRecord.canDrag (boolean : null : IR)
    //
    // When set to <code>false</code>, this record cannot be dragged. If canDrag is false for
    // any record in the current selection, none of the records will be draggable.
    //
    // @visibility external
    //<

    //> @attr listGridRecord.canAcceptDrop (boolean : null : IR)
    //
    // When set to <code>false</code>, other records cannot be dropped on (i.e., inserted
    // via drag and drop) immediately before this record.
    //
    // @visibility external
    //<

	//> @attr   listGridRecord.linkText  (string : null : IRW)
    //
    //  The HTML to display in this row for fields with fieldType set to link. This overrides
    //  +link{attr:listGridField.linkText}.
    //
    //  @see type:ListGridFieldType
    //  @see type:FieldType
    //  @see attr:listGridField.linkText
	//  @group  display_values
	//  @visibility external
	//<
    
	// Animation
    // ---------------------------------------------------------------------------------------
    
    //> @attr treeGrid.animateFolders (boolean : true : IRW)
    // If true, when folders are opened / closed children will be animated into view.
    // @group animation
    // @visibility animation
    // @example animateTree
    //<
    animateFolders:true,
    
    //> @attr treeGrid.animateFolderTime (number : 300 : IRW)
    // When animating folder opening / closing, if +link{treeGrid.animateFolderSpeed} is not
    // set, this property designates the duration of the animation in ms.
    // @group animation
    // @visibility animation
    // @see treeGrid.animateFolderSpeed
    //<
    animateFolderTime:300,

    //> @attr treeGrid.animateFolderSpeed (number : 500 : IRW)
    // When animating folder opening / closing, this property designates the speed of the
    // animation in pixels shown (or hidden) per second. Takes presidence over the 
    // +link{treeGrid.animateFolderTime} property, which allows the developer to specify a
    // duration for the animation rather than a speed.
    // @group animation
    // @visibility animation
    // @see treeGrid.animateFolderTime
    // @example animateTree
    //<    
    animateFolderSpeed:500,
    
    //> @attr treeGrid.animateFolderEffect (AnimationAcceleration : null : IRW)
    // When animating folder opening / closing, this property can be set to apply an
    // animated acceleration effect.designates the speed of the
    // animation in pixels shown (or hidden) per second.
    // @group animation
    // @visibility animation
    //<    

    //> @attr treeGrid.animateRowsMaxTime (number : 1000 : IRW)
    // If animateFolderSpeed is specified as a pixels / second value, this property will cap
    // the duration of the animation.
    // @group animation
    // @visibility animation_advanced
    //<    
    animateRowsMaxTime:1000,
	
	// DataBinding
	// ----------------------------------------------------------------------------------------

	//>	@attr	listGrid.fields		(Array of ListGridField : null : [IRW])
	// An array of field objects, specifying the order, layout, formatting, and
	// sorting behavior of each field in the listGrid object.  In ListGrids, the fields
	// array specifies columns.  Each field in the fields array is a ListGridField object.
    // <p>
    // If +link{ListGrid.dataSource} is also set, this value acts as a set of overrides as
    // explained in +link{attr:DataBoundComponent.fields}.
    //
	// @see    ListGridField
	// @see    setFields()
    // @group databinding
	// @visibility external
    // @example listGridFields
    // @example mergedFields
	//<

	//>	@attr	listGrid.dataSource		(DataSource or ID : null : IRW)
    // @include dataBoundComponent.dataSource
	//<
    
	//> @attr   listGrid.autoFetchDisplayMap (boolean : true : [IRW])
	// If true, automatically fetches a valueMap if an +link{listGridField.optionDataSource} is
    // set for this field.
    // <P>
    // Can be disabled on a per-field basis with +link{listGridField.autoFetchDisplayMap}.
    //
	//  @group  display_values
	//  @see listGridField.autoFetchDisplayMap
	//  @see listGridField.optionDataSource
	//<
    autoFetchDisplayMap:true,

    //> @attr ListGrid.saveLocally  (boolean : null : IRA)
    // For grids with a specified +link {ListGrid.datasource}, this property can be set to 
    // <code>true</code> to avoid the grid from attempting to save / retrieve data from the
    // server.  In this case data will be saved locally as +link {ListGrid.data}, and the
    // datasource will simply act as a schema to describe the set of fields visible in the
    // grid.
    // @group databinding
    //<
    

	//>	@attr	listGrid.useAllDataSourceFields (boolean : null : IRW)
    // @include dataBoundComponent.useAllDataSourceFields
    // @group databinding
	//<

	//>	@attr	listGrid.showDetailFields (boolean : true : IR)
    // Whether to include fields marked <code>detail:true</code> from this component's 
    // <code>DataSource</code>.<br>
    // Fields may also be included directly in this component's <code>fields</code> array in
    // which case they will be present regardless of the <code>detail</code> attribute.
    // <p>
    // When this property is <code>true</code>, <code>ListGrid</code>s will include all 
    // detail fields, but they will be initially hidden. To override the visibility of
    // a detail field, use the standard +link{listGrid.showField()}, +link{listGrid.hideField()}
    // and +link{listGridField.showIf} APIs.<br>
    // The user may show these fields via the default header context menu 
    // (+link{listGrid.showHeaderContextMenu}).<br>
    // Setting this property to false will completely exclude all detail fields from the list
    // grid's fields array.
    // @group databinding
    // @visibility external
    //<
    showDetailFields:true,
    
    //> @attr ListGrid.titleField (string : see below : IRW)
    // Best field to use for a user-visible title for an individual record from this grid.
    // If +link{ListGrid.dataSource} is non null, this property may be specified on the 
    // dataSource instead.
    // <p>
    // If not explicitly set, titleField looks for fields named "title", "name", and "id" 
    // in that order.  If a field exists with one of those names, it becomes the titleField.  
    // If not, then the first field is designated as the titleField.
    //  @visibility external
    //<

    
    //>@attr    listGrid.dataProperties (object : null :IRWA)
    // For databound ListGrids, this attribute can be used to customize the +link{ResultSet}
    // object created for this grid when data is fetched
    // @group databinding
    // @visibility external
    //<
    
    // Grouping
    // ---------------------------------------------------------------------------------------
    
    //> @object groupNode
    //
    // An auto-generated subclass of +link{TreeNode} representing the group nodes
    // in a grouped listgrid. 
    //
    // @see listGrid.groupBy
    // @treeLocation Client Reference/Grids/ListGrid
    // @visibility external    
    //< 
    
    //> @attr groupNode.groupMembers (Array of ListGridRecord or GroupNode : see below : R)
    // Array of ListGridRecord that belong to this group, or, for multi-field grouping, array
    // of groupNodes of subgroups under this groupNode.
    // 
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    
    //> @attr groupNode.groupTitle (HTML : see below : R)
    // The computed title for the group, which results from +link{listGridField.getGroupTitle()}
    // 
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    
    //> @attr groupNode.groupValue (any : see below : R)
    // The value from which groups are computed for a field, 
    // which results from +link{listGridField.getGroupValue()}
    // 
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    
    //> @attr listGrid.originalData (List of ListGridRecord : null : R)
    // When grouped, a copy of the original ungrouped data.
    //
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    
    //> @attr listGrid.groupTree (AutoChild : null : R)
    // The data tree that results from a call to  +link{listGrid.groupBy()}.
    // This will be a +link{ResultTree} if +link{listGrid.dataSource} is
    // present, otherwise it will be a +link{Tree}.
    //
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    
    //> @attr listGrid.groupStartOpen (String : null : IRW)
    // Describes the default state of ListGrid groups when groupBy is called. 
    // Possible values are:
    //     "all": open all groups
    //     "first": open the first group
    //     "none": start with all groups closed 
    //
    // @group   grouping
    // @see listGrid.groupBy
    // @visibility external
    //<
    groupStartOpen:"first",
    
    //> @method listGridField.getGroupValue()
    // Return the value within which records with the same value will be grouped.
    // Default is the result of +link{listGrid.getCellValue}.
    // <P>
    // While any type of value may be returned, avoiding the use of string values may
    // result in improved performance. In this case, +link{listGridField.getGroupTitle()}
    // may be implemented to map an enumerated group value into a legible string.
    // @group display_values
    //
    // @param   value (any)   raw value for the cell, from the record for the row
    // @param   record   (ListGridRecord) 
    //   Record object for the cell. Note: If this is a new row that has not been saved, in an 
    //   editable grid, it has no associated record object. In this case the edit values will
    //   be passed in as this parameter (see +link{listGrid.getEditValues()})
    // @param   field  (Ob