valuesmanager.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 


//>	@class	ValuesManager
//
// The ValuesManager manages data from multiple member forms.
// <P>
// If a single logical form needs to be separated into multiple DynamicForm instances for
// Layout purposes (for example, spanning one logical form across multiple Tabs), a
// ValuesManager can be used to make the forms act as one logical form, supporting all
// value-related APIs otherwise called on DynamicForm directly.
// <P>
// A ValuesManager has no visual representation - it is strictly a logical entity, and the
// member forms provide the user interface.  You can initialize a ValuesManager with a set of
// member forms (by setting +link{ValuesManager.members} at init) or add and remove member
// forms dynamically.
// <P>
// Calling +link{ValuesManager.setValues()} on a ValuesManager will automatically route new
// field values to whichever member form is showing an editor for that field.  Likewise,
// calling +link{ValuesManager.validate()} will validate all member forms, and
// +link{ValuesManager.saveData()} will initiate a save operation which aggregates values from
// all member forms.
// <P>
// Like a DynamicForm, a ValuesManager can be databound by setting
// +link{valuesManager.dataSource}.  In this case all member forms must also be bound to the
// same DataSource.
// <P>
// In general, when working with a ValuesManager and its member forms, call APIs on the
// ValuesManager whenever you are dealing with values that span multiple forms, and only call
// APIs on member forms that are specific to that form or its fields.
// <P>
// Note that, just as a DynamicForm can track values that are not shown in any FormItem, a
// ValuesManager may track values for which there is no FormItem in any member form.  However,
// when using a ValuesManager these extra values are only allowed on the ValuesManager itself.
// Member forms will not track values for which they do not have FormItems.
//
// @treeLocation Client Reference/Forms
// @visibility external
// @example formSplitting
//<
isc.ClassFactory.defineClass("ValuesManager");

isc.ValuesManager.addProperties({

    //>@attr  valuesManager.dataSource  (DataSource | string : null : [IRWA])
    // Specifies a dataSource for this valuesManager.  This dataSource will then be used for
    // validation and client-server flow methods.  Can be specified as a dataSource object or
    // an identifier for the dataSource.<br>
    // Note that member forms should have the same dataSource applied to them to allow their
    // items to inherit properties from the DataSource fields.
    // @visibility external
    // @see valuesManager.setDataSource()
    // @see valuesManager.getDataSource()
    //<
    //dataSource : null,
    
    //>@attr  valuesManager.members (Array : null : [IRW])
    // The set of member forms for this valuesManager.  These can be specified at init time via
    // the <code>members</code> property, or updated at runtime via <code>addMember()</code> and
    // <code>removeMember()</code>.<br>
    // Note: Alternatively a form can be initialized as a member of a valuesManager by setting
    // the <code>valuesManager</code> property of the form to a pre-defined valuesManager
    // instance.
    // @visibility external
    // @see valuesManager.addMember()
    // @see valuesManager.removeMember()
    //<
    //members : null,    
    
    //>	@attr	valuesManager.unknownErrorMessage	(string : "Invalid value" : [IRW])
    // @include DynamicForm.unknownErrorMessage
    //<
	unknownErrorMessage : "Invalid value"
    
    //> @attr valuesManager.disableValidation   (boolean : null : [IRWA])
    // @include DynamicForm.disableValidation
    //<

});

//!>Deferred
isc.ValuesManager.addMethods({
    // Allow a V.M to be initialized with member form(s)
    init : function () {
        // get a global ID so we can be called in the global scope
        this.ns.ClassFactory.addGlobalID(this);
        
        if (this.dataSource) this.bindToDataSource(this.dataSource);

        // Set up values based on members / init values.
        if (this.members != null) {
            // Initialize this.values [and ensure it's a new object, so it can't be manipulated
            // externally]
            this.values = isc.addProperties({}, this.values);
            
            if (!isc.isAn.Array(this.members)) this.members = [this.members];

            this._updateValuesFromMembers();
            for (var i = 0; i < this.members.length; i++) {
                var member = this.members[i];
                if (member.valuesManager != null) member.valuesManager.removeMember(member);
                member.valuesManager = this;
        
                // For databinding all member forms are expected to have the same 
                // datasource as this ValuesManager. This ensures they inherit validators,
                // field properties, etc.
                if (member.getDataSource() != this.getDataSource()) {
                    this.logWarn("Member form '"+ member.getID() + "' does not have " 
                         + "the same dataSource property specified as this valuesManager.");
                }          
                
                // If any member forms are multipart, warn the developer - this implies that
                // they need direct submission.
                // (We also log this warning on addMember)
                if (this.getDataSource() != null && member.isMultipart()) {
                    this.logWarn("Member form '" + member.getID() + 
                        "' is flagged as using multipart encoding. Multipart forms require direct form " +
                        "submission to transfer uploaded files to the server - any uploaded files from " +
                        "this member form will be dropped when saving values from this ValuesManager to " +
                        "the server."
                    );
                }
                      
            }
        }
        
        // initialize this.values
        this.values = this.values || {};
                
        // remember the current values for resetting
        this.rememberValues();
    },
    
    // on destroy
    // - disconnect from member forms (Don't destroy - they may want to be re-used in a 
    //   different VM)
    // - clear global ID
    destroy : function () {
        var members = this.members;
        if (members) {
            // iterate backwards so the changing length of the members array doesn't mess up
            // our loop
            for (var i = members.length-1; i >= 0; i--) {
                this.removeMember(members[i]);
            }
        }
        // clear the global ID
        window[this.getID()] = null;

    },
    
    // Helper method to retrieve all the values from the member forms, and apply them to
    // this.values.
    _updateValuesFromMembers : function () {
        for (var i = 0; i < this.members.length; i++) {
            var form = this.members[i],
                values = form.getValues(),
                undef;
                
            if (!isc.isA.DynamicForm(form)) {
                this.logWarn("ValuesManager member object:" + isc.Log.echo(form) 
                             + " is not a DynamicForm.  Removing from members array.");
                this.members.remove(form);
                i -= 1;
                continue;
            }

            for (var j in values) {
                if (this.members[i].getItem(j) == null) {
                    this.logWarn("Member Form:" + this.members[i].getID() + 
                         " Has explicitly specified value for fieldName " + j + ", but has" +
                         " no item associated with this fieldName. Ignoring this value. " +
                         "Values may be set for fields with no associated form item directly " + 
                         "on the valuesManager via valuesManager.setValues(), but not on " +
                         "member forms. See ValuesManager documentation for more info.");
                    continue;
                }
                // catch collisions of values - earlier values win, as they may be explicitly
                // specified at init time.
                
                if (this.values[j] !== undef && this.values[j] != values[j]) {
                    this.logWarn("ValuesManager member form " + form.getID() + 
                        " has specified value '" + j +  
                        "' which collides with an already specified value in this " +
                        "ValuesManager. Resetting the value on the form.");
                    form.setValue(j, this.values[j]);
                } else {
                    this.values[j] = values[j];
                }
            }
        }
        // Note - in order to keep the values up to date we need to be notified when they
        // change in the form.
        // This is done via code embedded in DynamicForm.setItemValue()
        
    },
    
    // _updateValue and _clearValue() -- called by member forms to notify us of field value 
    // changes
    _updateValue : function (field, value, form) {
        if (form.getItem(field) == null) {
            this.logWarn("Member Form:" + form.getID() + 
                 " Has explicitly specified value for fieldName " + field + ", but has" +
                 " no item associated with this fieldName. Ignoring this value. " +
                 "Values may be set for fields with no associated form item directly " + 
                 "on the valuesManager via valuesManager.setValues(), but not on " +
                 "member forms. See ValuesManager documentation for more info.");
            return;
        }
        this.values[field] = value;
    },
    _clearValue : function (field, form) {
        
        delete this.values[field];
    },
    
    // ----------------------------------------------------------------------------------------
    // Databound functionality
    // ----------------------------------------------------------------------------------------
    
    //> @method ValuesManager.bindToDataSource() ([A])
    //   Associate this ValuesManager with a DataSource.  Allows the developer to inherit 
    //   properties from the DataSource fields to be applied to these values, such as validators,
    //   and to call data flow methods using this ValuesManager's data.
    // @param (dataSource)  Datasource object, or identifier
    // @visibility internal
    //<
    // For the public version of this method use 'setDataSource'
    bindToDataSource : function (ds) {

        
        if (!isc.isA.DataSource(ds)) ds = isc.DataSource.getDataSource(ds);
        if (ds != null) this.dataSource = ds;
    },
  
    //>@method  valuesManager.setDataSource() (A)
    // Specifies a dataSource for this valuesManager.  This dataSource will then be used for
    // validation and client-server flow methods.
    // @visibility external
    // @param dataSource (string | DataSource)  Datasource object or identifier to bind to.
    //<
    setDataSource : function (dataSource, fields) {
        // we don't use 'fields'
        this.bindToDataSource(dataSource);
    },
    
    //>@method  valuesManager.getDataSource() (A)
    // Returns the dataSource for this valuesManager.  Will return null if this is not a 
    // data-bound valuesManager instance.
    // @visibility external
    // @return (DataSource)  Datasource object for this valuesManager.
    //<
    getDataSource : function () {
        return this.dataSource;
    },
    
    
    //>@method valuesManager.getItems()
    // Retrieves all form items contained within this valuesManager's member forms
    // @return (array of FormItems) form items present in this valuesManager
    //<
    getItems : function () {
        var items = [];
        for (var i = 0; i < this.members.length; i++) {
            var form = this.members[i];
            items.addList(form.getItems());
        }
        return items;
    },
    // getFields() synonym of getItems
    getFields : function () {
        return this.getItems();
    },
    
    getItem : function (id) {
        for (var i = 0; i < this.members.length; i++) {
            var form = this.members[i],
                item = form.getItem(id);
            if (item) return item; 
        }
    },
    
    getField : function (id) {
        return this.getItem(id);
    },
    
    // How to handle fileItems?