valuesmanager.js

javascript 很酷的类库

        
        return false;
    },

    //> @method ValuesManager.getValue
    // Returns the value for some field.
    // @param   fieldName   (string)    Which value to be returned
    // @return  (any)   current value of the appropriate field
    // @visibility external
    // @group formValues
    //< 
    getValue : function (fieldName) {
        return this.values[fieldName];
    },
    
    //> @method ValuesManager.setValue
    // Set the value for some field.
    // @param   fieldName   (string)    Which field to set the value for
    // @param   newValue    (any)       New value for the field.
    // @visibility external
    // @group formValues
    //< 
    setValue : function (fieldName, newValue) {
        var valueSet = false;
            
        if (this.members) {
    
            var undef;
            for (var i = 0; i < this.members.length; i++) {
                var member = this.members[i]
                if (member.getValues()[fieldName] !== undef || 
                    member.getItem(fieldName) != null) 
                {
                    member.setValue(fieldName, newValue);
                    valueSet = true;
                    break;
                }
            }
        }
        if (!valueSet) this.values[fieldName] = newValue;
    },
    
    // ========================================================================================
    //  Member Management
    // ========================================================================================
    
    //>@method  ValuesManager.addMember()   
    //
    // Add a new member form to this valuesManager.
    // This form's values will subsequently be available through this valuesManager.  <br>
    // Note on pre-existant values:
    // If the valuesManager has a value specified for some field, for which the member form has
    // an item, this value will be applied to the member form.  This is true whether the item
    // has a value or not.<br>
    // However if the member form has a value for some field, and the ValuesManager does not
    // have a specified value for the same field, we allow the valuesManager to pick up the 
    // value from the member form.    
    //
    // @param   member  (DynamicForm | String) form (or ID of form) to add to 
    //                                          this valuesManager as a member.
    // @visibility external
    // @group members
    // @see method:ValuesManager.addMembers
    //<    
    addMember : function (member) {
        // If passed an ID, assume it's a pointer to the form.
        if (isc.isA.String(member)) member = window[member];
        
        if (!isc.isA.DynamicForm(member)) {
            this.logWarn("addMember() passed invalid object: "+ isc.Log.echo(member) + 
                         " - this should be a DynamicForm instance");
            return;
        }
        
        if (member.valuesManager != null) member.valuesManager.removeMember(member);

        // If the member has a different dataSource specified, log a warning.
        // Different dataSources are a problem, as datasource field properties (including
        // specified validators) will not be reflected in the form.
        if (member.getDataSource() != this.getDataSource()) {
            this.logWarn("addMember(): new 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.
        if (this.getDataSource() != null && member.isMultipart()) {
            this.logWarn("addMember(): new 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."
            );
        }
        
        if (this.members == null) this.members = [];
        this.members.add(member);
        
        var values = member.getValues(),
            items = member.getItems(),
            undef;

        for (var field in values) {
            if (this.values[field] !== undef) {
                this.logWarn("ValuesManager member form " + member.getID() + 
                    " has specified value '" + field +  
                    "' which collides with an already specified value in this " +
                    "ValuesManager. Resetting the value on the form.");
                member.setValue(field, this.values[field]);
            } else {
                this.values[field] = values[field];
            }
        }
        // Go through any items without values, and update their values to come from the VM.
        for (var i = 0; i < items.length; i++) {
            
            var item = items[i],
                field = item[member.fieldIdProperty];

            // If values[field] from the member isn't empty, we've already set the form value 
            // above.
            if (this.values[field] !== undef && values[field] === undef) {
                item.setValue(this.values[field]);
            }
        }
        
        member.valuesManager = this;
        
        // We have directly manipulated the values object, so we should re remember it.
        this.rememberValues();
        
    },
    
    //>@method  ValuesManager.addMembers()   
    //  Add multiple new member forms to this valuesManager.
    // @param   members  (array) array of forms to add to this valuesManager as members.
    // @visibility external
    // @group members
    // @see method:ValuesManager.addMember
    //<        
    addMembers : function (members) {
        if (!isc.isAn.Array(members)) this.addMember(members);
        else {
            for (var i = 0; i< members.length; i++) {
                this.addMember(members[i]);
            }
        }
    },
    
    //>@method  ValuesManager.removeMember()   
    //  Remove a member form from this valuesManager, so its values are no longer managed
    //  by this instance.
    //  This does not clear the values associated with the form from the valuesManager - they
    //  will still be available via <code>valuesManager.getValues()</code>, but will not be
    //  updated as the form is manipulated.
    // @param   member  (DynamicForm | string)   form (or ID of form) to remove from this valuesManager
    // @visibility external
    // @group members
    // @see method:ValuesManager.removeMembers()
    //<    
    removeMember : function (member) {
        
        if (isc.isA.String(member)) {
            member = isc.Class.getArrayItem(member, this.members);
            if (member == null) return;
        } else if (!this.members.contains(member)) return;
        
        this.members.remove(member);
        delete member.valuesManager;
    },
    
    //>@method  ValuesManager.removeMembers()   
    //  Remove multiple member forms from this valuesManager.
    // @param   members  (array)   array of forms to remove
    // @visibility external
    // @group members
    // @see method:ValuesManager.removeMember()
    //<    
    removeMembers : function (members) {
        if (!isc.isAn.Array(members)) this.removeMember(members);
        else {
            for (var i = 0; i< members.length; i++) {
                this.removeMember(members[i]);
            }
        }    
    },

    
    //>@method  ValuesManager.getMembers()   
    //  Retrieves an array of pointers to all the member forms for this valuesManager.
    // @return (array)   array of member forms
    // @visibility external
    // @group members
    //<    
    getMembers : function () {
        return this.members;
    },
    
    //>@method  ValuesManager.getMember()
    //  Returns a pointer to a specific member form.
    // @param   ID  (string)    ID of the form to retrieve
    // @return (DynamicForm)   member form (or null if unable to find a member with the 
    // specified ID).
    // @visibility external
    // @group members
    //<    
    getMember : function (ID) {
        // Since the members are all DynamicForm instances, their IDs are global
        var member = window[ID];
        // sanity check
        if (this.members && this.members.contains(member)) return member;
        return null;
    },
    
    //>@method  ValuesManager.getMemberForField()
    // Given a fieldName, this method will find the member form containing an item for that
    // field. If no member form is found, returns null.
    // @param fieldName (string) fieldName to check
    // @return (DynamicForm) member form containing an item for the fieldName, or null.
    // @group members
    // @visibility external
    //<
    getMemberForField : function (fieldName) {
        if (!this.members) return null;
        for (var i = 0; i < this.members.length; i++) {
            if (this.members[i].getItem(fieldName)) return this.members[i];
        }
        return null;
    },

    
    // Getting pointers to actual items
    //>@method ValuesManager.getItem()
    // Takes an item name (specified via the form.fieldIdProperty value, or retrieved via
    // item.getFieldName()) returns a reference to the appropriate item in this valuesManager.
    // <br>Note: Unlike the <code>DynamicForm</code> class, this method will not return an 
    // item by index
    // @visibility external
    //<
    getItem : function (name) {
        if (this.members) {
            for (var i = 0; i < this.members.length; i++) {
                var form = this.members[i],
                    items = this.members[i].getItems();
                for (var j = 0; j < items.length; j++) {
                    if (items[j].getFieldName() == name) return items[j];
                }
            }
        }
        return null;
    },
    
    // ----------------------------------------------------------------------------------------
    // Display
    // ----------------------------------------------------------------------------------------
    // valuesManagers don't usually display their values directly - but support
    // getPrintHTML() so we can build reports from them.
    getPrintHTML : function () {
        var values = this.getValues(),
            printHTML = isc.StringBuffer.create();

        printHTML.append("<TABLE border=1><TR><TD align='center' style='font-weight:bold;'>Field</TD>",
                         "<TD align='center' style='font-weight:bold;'>Value</TD>");
        for (var fieldName in values) {
            printHTML.append("<TR><TD>",fieldName,"</TD><TD>", values[fieldName], "</TD></TR>");
        }
        printHTML.append("</TABLE>");
        return printHTML.toString();
    }
    
        
});



isc.ValuesManager.registerStringMethods ({

     //> @method valuesManager.handleHiddenValidationErrors (A)
    // Method to display validation error messages for a valuesManager when there is not
    // currently visible form item displaying the errors.
    // This will be called when validation fails for<br>
    // - a field in a hidden or undrawn member form<br>
    // - a hidden field in a visible member form<br>
    // - for databound ValuesManagers, a datasource field with specified validators, but not
    //   associated item in any member.<br>
    // Implement this to provide custom validation error handling for these fields.<br>
    // By default hidden validation errors will be logged as warnings in the developerConsole.
    // Return false from this method to suppress that behavior.
    // @param   errors (object) The set of errors returned - this is an object of the form<br>
    //                      &nbsp;&nbsp;<code>{fieldName:errors}</code><br>
    //                      Where the 'errors' object is either a single string or an array
    //                      of strings containing the error messages for the field.
    // @visibility external
    //<
    handleHiddenValidationErrors:"errors"
});

//!<Deferred