picklist.js

javascript 很酷的类库

    // @visibility external
    //<
    getPickListFilterCriteria : function () {
        return this.pickListCriteria || {};
    },

    // This is a helper method to return the set of 'local' options.
    // default implementation returns null for databound pickLists, or the array of values for
    // non databound picklists.
    // Used by logic to navigate around via keyboard
    // Overridden on the Select item to handle databound pickLists with all rows cached
    getAllLocalOptions : function () {
        return this._getOptionsFromDataSource() ? null : this.getClientPickListData();
    },
    
    //> @method PickList.getValueFieldName()
    // @include FormItem.getValueFieldName()
    //<
    
    // Display fields -----------------------------------------------------------------
    
    //> @method   pickList.getDisplayFieldName()
    // @include FormItem.getDisplayFieldName()
    //<
 
    
    // For databound items, an explicitly specified displayField means we'll be displaying
    // values from one field of our dataSource, and returning data values from a different field.
    // (Something like a valueMap using the resultSet from the server as a mapping object)
    // This helper method will perform the conversion between display and data values based
    // on the pickList's data set, if necessary.
    // Retriving the display value directly from the pickList dataSet often avoids us having to 
    // run the fetchMissingValues logic in setValue() whereby we perform a fetch against the
    // dataSource when setValue() is called
    // Note that in contrast if this is a freeform data entry type field (EG a combobox)
    // and the user enters a value that is not present in the data-set, it will be stored as
    // the data value for the item, even though the user is theoretically setting the
    // display value.
    // Form items that use the pickList interface will typically call this method from
    // mapValueToDisplay() and mapDisplayToValue()
    _translateValueFieldValue : function (value, toValueField) {
        // If we were not passed a defaultValue (value to return if no match was found),
        // return 
        // This method is only for use with databound pickLists.
        var ods = this.getOptionDataSource();
        if (ods == null) {
            
            return;
        }
        
        var resultSet = this.pickList && !this.pickList.destroyed ? this.pickList.data : null;
        if (!resultSet || !(resultSet.localData || resultSet.allRows)) return;
        
            
        var toField = (toValueField ? this.getValueFieldName() : this.getDisplayFieldName()),
            fromField = (toValueField ? this.getDisplayFieldName() : this.getValueFieldName());

        if (toField == fromField) return value;
        // If we have a complete cache use it - this enables us to map data values that don't
        // match the current filter criteria.
        var cache = resultSet.allRows || resultSet.localData,
            record = cache.find(fromField, value);
        if (record != null) return record[toField];
    },
    
    setUpPickListFields : function () {
        var fields = this.getPickListFields(),
            currentFields = this.pickList.fields;
        
        // Verify that the fields are not already up to date. If so just bail.
        var fieldsChanged = !currentFields || (currentFields.length != fields.length);
        if (!fieldsChanged) {
            for (var i= 0; i < fields.length; i++) {
                var field = fields[i], plField = currentFields[i];
                for (var prop in field) {
                    if (field[prop] != plField[prop]) {
                        fieldsChanged = true;
                        break;
                    }
                }
                if (fieldsChanged) break;
            }
        }

        if (!fieldsChanged) return;
        
        // For the display field (which will display the valueIcons specified for this item)
        // pick up valueIcon sizing etc from this item unless it was explicitly overridden
        if (this.valueIcons != null || this.getValueIcon != null) {
            for (var i = 0; i < fields.length; i++) {
                var field = fields[i];
                if (field[this.form.fieldIdProperty] == this.getValueFieldName()) {
                    if (field.valueIconHeight == null) 
                        field.valueIconHeight = this.valueIconHeight;
                    if (field.valueIconWidth == null) 
                        field.valueIconWidth = this.valueIconWidth;
                    if (field.valueIconSize == null) 
                        field.valueIconSize = this.valueIconSize;
                    if (field.imageURLPrefix == null) 
                        field.imageURLPrefix = this.imageURLPrefix || this.baseURL || this.imgDir;
                    if (field.imageURLSuffix == null) 
                        field.imageURLSuffix = this.imageURLSuffix;
                }
            }
        }
        
        this.pickList.setFields(fields);

        // Show the header if there are multiple fields.
        if (fields.length > 1) {
            // we are likely to be sharing a pickList across items, each of which may have a
            // different header height, so reset each time the header is shown
            // (No ops if no change anyway)
            this.pickList.setHeaderHeight(this.pickListHeaderHeight);
            this.pickList.setShowHeader(true);
            this.pickList.fixedFieldWidths = true; // can't autoSize with a header
        } else {
            this.pickList.setShowHeader(false);
            // always set fixedFieldWidths in case we're reusing a pickList from another item
            // with different settings
            this.pickList.fixedFieldWidths = !this.autoSizePickList;
        }
    },
    
    // If we have an explicitly specified optionDataSource for the field, we will databind the
    // list to that dataSource.
    // Otherwise, we'll use the valueMap to get a set of client-only options if we have one
    // - or attempt to derive an optionDataSource if not.
    _getOptionsFromDataSource : function () {
        // explicit datasource
        if (this.optionDataSource) return true;
        // derived datasource [For Comboboxes this will be non-null if the field has a foreignKey]
        if ((this.showOptionsFromDataSource || !this.valueMap) && 
            this.getOptionDataSource() != null) return true;
        return false;
    },
    

    
    
    filterPickList : function (show, queueFetches, request) {
        if (!queueFetches) 
            this._filterPickList(show, request);
        else {
            this._showOnDelayedFilter = show;
            this.fireOnPause("fetch", 
                             {target:this, methodName:"_filterPickList", 
                              args:[null, request, true]}, 
                             this.fetchDelay);
        }        
    },
    
    _filterPickList : function (show, request, delayed) {
        if (delayed) show = this._showOnDelayedFilter;
        delete this._showOnDelayedFilter;
        this._showOnFilter = show;
        
        var useDS = this._getOptionsFromDataSource();        
        if (useDS) {
            var ds = this.getOptionDataSource();

            // Pass the (already set up) fields into the 'setDataSource' method.
            if (this.pickList.getDataSource() != ds) {
                this.pickList.setDataSource(ds, this.pickList.fields);
            }

            // Will fall through to filterComplete() when the filter op. returns.        
            this.filterDataBoundPickList(request);
        } else {
            // Ignore any requestProperties passed in for a client-only filter.
            
            var records = this.filterClientPickListData();
            
            if (this.pickList.data != records) this.pickList.setData(records);

            // explicitly fire filterComplete() as we have now filtered the data for the 
            // pickList
            this.filterComplete();
        }
        
        
    },
    
    
    // getFirstOptionValue - used by SelectItem / ComboBoxItem if defaultToFirstOption is true
    getFirstOptionValue : function (fetch, fetchCallback) {
        
        var value;
        if (this._getOptionsFromDataSource()) {
            if (this.pickList && this.pickList.formItem == this && this.pickList.data) {
                var data = this.pickList.data;
                // if length is known to be zero - nothing to default to
                if (data.getLength() == 0) {
                } else if (data.rowIsLoaded(0)) {
                    value = data.get(0)[this.getValueFieldName()];
                } else {
                    if (fetch) {
                        this.fetchData(fetchCallback);
                    }
                }
                
            } else {
                if (fetch) {
                    this.fetchData(fetchCallback);
                }
            }
        } else {
            var map = this.valueMap;
            if (isc.isAn.Array(map)) value = map[0];
            else if (isc.isAn.Object(map)) {
                // use for...in to pick up first defined property on the object
                for (var field in map) {
                    value = field;
                    break;
                }
            }
        }
        return value;
    },
    
    //>@method pickList.getClientPickListData() [A]
    // Returns the set of data to be displayed in this item's PickList.
    // <P>
    // This method will be called for non-databound form items implementing the PickList
    // interface.  The default implementation will derive data from the item's valueMap - 
    // can be overridden to allow a custom set of options to be displayed.
    // <P>
    // Note that for PickLists that filter data based on user input
    // (+link{ComboBoxItem,ComboBox}), this method should return the data <b>before
    // filtering</b>.  To customize the data returned after filtering, override
    // +link{filterClientPickListData()} instead.
    // <P>
    // As an example, for a formItem with +link{valueField} set to "valueFieldName", the
    // default implementation would take a valueMap like the following:
    // <pre>
    //     valueMap: { value1: "display 1", value2: "display 2" }
    // </pre>
    // .. and returning the following set of records: 
    // <pre>
    //     [
    //          { valueFieldName : "value1" },
    //          { valueFieldName : "value2" }
    //     ]
    // </pre>
    // Due to the valueMap, these records will appear as a two row pickList displayed as
    // "display 1" and "display 2".
    //
    // @return (Array of ListGridRecord) Array of record objects to be displayed in the
    //           pickList. Note that when a user picks a record from the list, the value of the
    //           field matching <code>item.valueField</code> will be picked. Also note that the
    //           fields to be displayed can be customized via <code>item.pickListFields</code>
    //                  
    // @visibility external
    //<
    getClientPickListData : function () {
        return isc.PickList.optionsFromValueMap(this);
    },
    
    // Override point to notify the item that the pickList has been shown / hidden
    _pickListHidden : function () {
        if (this.pickListHidden) this.pickListHidden();
    },
    
    _pickListShown : function () {
        if (this.pickListShown) this.pickListShown();
    },

    // selectDefaultItem
    // When the pickList is initally shown / re-filtered update the selection.
    // For select items the current value will be selected.  
    // [Overridden by the comboBox class to always select the first record].
    
    selectDefaultItem : function () {
        // Select the value currently displayed in the form item
        return this.selectItemFromValue(this.getValue());        
    },
    
    selectItemFromValue : function (value) {
        // If the value is already selected we can just return. This is much quicker for most
        // cases since we don't have to iterate through the pickList data array
        var record = this.pickList.getSelectedRecord(),
            valueField = this.getValueFieldName();
        if (record && (record[valueField] == value)) return true;
        
        var data = this.pickList.getData(),
            dataSource = this._getOptionsFromDataSource() ? this.getOptionDataSource() : null;
        if (dataSource != null) {
            
            var cache = data.localData;
            if (cache) record = cache.find(valueField, value);
        } else {
            record = data.find(valueField, value);            
        }

        if (record) {
            this.pickList.selection.selectSingle(record);
            this.pickList.scrollRecordIntoView(data.indexOf(record));
        }
        // Return a boolean to indicate whether we successfully found and selected a record