actionmethods.js

javascript 很酷的类库

    //
    // Resets values to the state it was the last time <code>setValues()</code> or
    // <code>rememberValues()</code> was called. If neither of those methods has been called,
    // values will be set back to their inital values at init time.
    //
    // @group formValues
    // @visibility external
    //<
    reset : function () {
        this.resetValues();
    },

    //> @method dynamicForm.cancel() ([])
    //
    // This method exists for clean integration with existing server frameworks that have a 'cancel'
    // feature which typically clears session state associated with the form.  When this method is
    // called, an RPC is sent to the server with a parameter named
    // +link{attr:DynamicForm.cancelParamName} with the value
    // +link{attr:DynamicForm.cancelParamValue}.<p>
    //
    // Note that no other form data is sent.  By default the current top-level page is replaced with the
    // reply.  If you wish to ignore the server reply instead, call this method like this:
    // <pre>
    // dynamicFormInstance.cancel({ignoreTimeout: true, target: null});
    // </pre>
    //
    // @param [requestProperties] (DSRequest)   additional properties to set on the RPCRequest
    //                                          that will be issued
    // @group submitting
    // @visibility external
    //<
    cancel : function (requestProps) {
        var cancelRPC = {
            actionURL: this.action,
            target: window,
            sendNoQueue: true,
            ignoreTimeout: true,
            useXmlHttpRequest: false,
            params: { }, // set below
            useSimpleHttp: true
        };
        cancelRPC.params[this.cancelParamName] = this.cancelParamValue;

        //>DEBUG
        if (!cancelRPC.actionURL) {
            this.logWarn("No actionURL defined for the cancel RPC - set 'action' on your form or"
                         + "provide an actionURL in the requestProperties to cancel()");
            return;
        }
        //<DEBUG

        isc.addProperties(cancelRPC, requestProps);
        
        isc.rpc.sendRequest(cancelRPC);
    },

    //>	@method	dynamicForm.submit()
    // <code>submit()</code> is automatically called when a +link{SubmitItem} included in the
    // form is clicked, or, if +link{dynamicForm.saveOnEnter,saveOnEnter} is set, when the
    // "Enter" key is pressed in a text input.  Submit can also be manually called.
    // <P>
    // If +link{dynamicForm.submitValues(),form.submitValues()} exists, it will be called, then
    // immediately return.
    // <P>
    // Otherwise, default behavior varies based on +link{dynamicForm.canSubmit,form.canSubmit}: if
    // <code>canSubmit</code> is false, +link{method:dynamicForm.saveData()} will be called to
    // handle saving via SmartClient databinding.  
    // <P>
    // If <code>canSubmit</code> is true, the form will be submitted like an ordinary HTML
    // form via +link{dynamicForm.submitForm()}.
    // <P>
    // The parameters to <code>submit()</code> apply only if <code>submit()</code> will be
    // calling +link{saveData()}.  If you override <code>submit()</code>, you can safely
    // ignore the parameters as SmartClient framework code does not pass them.
    // 
    // @param [callback]          (DSCallback)  callback to invoke on completion.
    //                                          [Ignored if this.canSubmit is true]
    // @param [requestProperties] (DSRequest)   additional properties to set on the DSRequest
    //                                          that will be issued
    //                                          [Ignored if this.canSubmit is true]    
    // @group dataBoundComponentMethods
    // @see method:dynamicForm.submitValues()
    // @visibility external
    //<
    submit : function (callback, requestProps) {
        if (this.submitValues != null) {
            return this.submitValues(this.getValues(), this);
        }
        if (this.canSubmit) return this.submitForm();
        else return this.saveData(callback, requestProps);
    },

    // returns true if calling saveData() will perform the add operation, false otherwise.
    // Note that the operationType can be overridden by the optional requestProperties arg to
    // saveData.
    saveOperationIsAdd : function () {
        if (this.saveOperationType) return this.saveOperationType == "add";
    
        if (this.dataSource) {
            var ds = isc.DataSource.getDataSource(this.dataSource);
            return !ds.recordHasAllKeys(this.getValues());
        }
        return false;
    },

    //>	@method dynamicForm.saveData()
    //
    // Validate and then save the form's current values to the +link{DataSource} this form is
    // bound to.
    // <p>
    // If client-side validators are defined, they are executed first, and if any errors are
    // found the save is aborted and the form will show the errors.
    // <p>
    // If client-side validation passes, a +link{DSRequest} will be sent, exactly as though
    // +link{dataSource.addData()} or +link{dataSource.updateData()} had been called with 
    // +link{dynamicForm.getValues(),the form's values} as data.  The
    // +link{dsRequest.operationType} will be either "update" or "add" depending
    // on whether values were initially provided via <code>editRecord()</code> or
    // <code>editNew()</code>.
    // <P>
    // On either a client-side or server-side validation failure, validation errors will be
    // displayed in the form.  Visible items within a DynamicForms will be redrawn to display
    // errors. Validation failure occuring on hidden items, or DataSource fields with no 
    // associated form items may be handled via +link{DynamicForm.handleHiddenValidationErrors}
    // or +link{ValuesManager.handleHiddenValidationErrors}.
    // <P>
    // +link{dynamicForm.validationURL,validationURL} can be set to do validation against a
    // different URL from where the form will ultimately save, as part of an incremental
    // upgrade strategy for Struts and Struts-like applications.
    //
    // @param [callback]          (DSCallback)  callback to invoke on completion
    // @param [requestProperties] (DSRequest)   additional properties to set on the DSRequest
    //                                            that will be issued
    //
    // @group dataBoundComponentMethods
    // @visibility external
    // @example addOperation
    //<
    // NOTE: not documenting direct submit (If the editor is a multi-part encoded dynamicForm,
    // a direct submit will be performed.)
    saveData : function (callback, requestProperties, noValidation) {
        if (this.dataSource == null) {
            
            this.logWarn("saveData() called on a non-databound DynamicForm. This is not supported. " +
                       " for information on databinding of components look at the documentation" +
                       " for the DataSource class.  " +
                       "If this was intended to be a native HTML form submission, set the " +
                       "canSubmit property to true on this form.");
            return;
        }
       
        //>!BackCompat 2005.3.21 old signature: criteria, requestProperties
        if (requestProperties == null && isc.isAn.Object(callback) && 
            callback.methodName == null) 
        {
            // old style call, second param (callback) is really requestParams
            requestProperties = callback;
            callback = requestProperties.afterFlowCallback;
        } //<!BackCompat

        // do server validation if validationURL is specified            
        if (this.validationURL && !noValidation) {
            var validateProps = {};
            isc.addProperties(validateProps, requestProperties);
            isc.addProperties(validateProps, {
                actionURL: this.validationURL,
                valuesAsParams: true,
                sendNoQueue: true
            });
            validateProps._userProps = requestProperties;
            validateProps._userCallback = callback;            

            // set a special flag to prevent the validation run called by saveData() from
            // clearing any validation errors currently visible in the form if client-side
            // validation succeeds.  When we're in validationURL mode, typically the server
            // will be supplying these errors and it looks lame when the form redraws between
            // validation submits.
            this.performingServerValidation = true;

            this.validateData(this.getID()+"._saveFormValidateCallback(rpcRequest,rpcResponse,data)",
                              validateProps);
            return;
        }
        // If we're showing a fileItem, we'll have to perform a native commit of the fileItemForm
        // rather than submitting our values in the normal way
        var fileItemForm = this.getFileItemForm();
        if (fileItemForm) {
            // copy values across
            var vals = this.getValues(),
                uploadField = fileItemForm.getItem(0).getFieldName();
            delete vals[uploadField]; 
            for (var fieldName in vals) {
                fileItemForm.setValue(fieldName, vals[fieldName]);
            }
            
            // ensure action / target match
            fileItemForm.action = this.action;
            fileItemForm.target = this.target;
            fileItemForm.dataSource = this.dataSource;
            
            // validators are not duplicated on the fileItem form so explicitly validate now
            if (!this.validate()) return false;
            
            return fileItemForm.saveData(callback, requestProperties, noValidation);
        }
        
        var operationType = this.getSaveOperationType(requestProperties);

        // hold on to end user callback, and pass our own to the RPC layer.  We do this to
        // provide the formSaved() mechanism that fires before the end user callback.
        this._userCallback = callback;
      
        callback = this.getID()+"._saveDataReply(dsRequest, dsResponse, data)";
		requestProperties = this.buildRequest(requestProperties, operationType, callback);

        // send oldValues to allow long transactions
        requestProperties.oldValues = this._oldValues;

        // if the form specified an action different from the default, use it as the RPC target
        var doSubmit = false;
        
        if (this.submitParamsOnly) requestProperties.useSimpleHttp = true;

        // DynamicForm-specific code (does not apply to ValuesManager)
        if (isc.DynamicForm && isc.isA.DynamicForm(this)) {
            if (this.action != isc.DynamicForm.getInstanceProperty("action")) {
                requestProperties.actionURL = this.action;
                requestProperties.target = this.target ? this.target : window;
                doSubmit = true;
            }   
    
            // override the httpMethod on the request if the user specified a custom 'method'
            if (this.method != isc.DynamicForm.getInstanceProperty("method")) {
                requestProperties.httpMethod = this.method;
            }
        }
        
        if (!this.validate()) return false
        var values = this.getValues();        
        
        // perform a direct submit if the form is multipart-encoded
        
        if ((isc.DynamicForm && isc.isA.DynamicForm(this) && this.isMultipart())
            || this.canSubmit || doSubmit)
        {
            return this.submitEditorValues(values, requestProperties.operation, 
                                           requestProperties.callback, requestProperties);
        } else {
            return this.saveEditorValues(values, requestProperties.operation,
                                         requestProperties.callback, requestProperties);
        }

	},
    
    
    getSaveOperationType : function (requestProperties) {
        var operationType;
        // If no operation was passed in, we're going to have to auto generate one.
        if (!requestProperties || !requestProperties.operation) {
            // Insert or Update?
            // If the operationType is not passed in, use this.saveOperationType (set by
            // editNew et al)
            operationType = (requestProperties && requestProperties.operationType)  
                             ? requestProperties.operationType 
                             : this.saveOperationType;
            // If the saveOperatonType wasn't explicitly provided base it on whether the
            // primary keys for the record are present and whether they've been modified
            
            if (!operationType) {
            
                var pkFields = isc.DataSource.getDataSource(this.dataSource).getPrimaryKeyFieldNames(),
                    values = this.getValues(),
                    undef;
                for (var i = 0; i < pkFields.length; i++) {
                    var key = pkFields[i],
                        value = values[pkFields];
                    if (value == null) {
                        //this.logWarn('saveData(): has no value for a primary key field:' + key 
                        //              + ', assuming this is an add (pk will be genereated by server)');                    
                        operationType = "add";
                        break;
                    }
                    
                    if (this._oldValues[key] !== undef && this._oldValues[key] != value) {
                        //this.logWarn("saveData(): primary key field:" + key + " has been modified" +
                        //             " assuming this is an add operation");
                        operationType = "add";
                    }
                    
                    var item = this.getItem(key);
                    if (item && (item.shouldSaveValue && item.isEditable())) {
                        //this.logWarn("saveData(): value for primary key is editable - assuming this is an add");
                        operationType = "add" 
                        break;
                    }
                }
                // In this case, every primary key is present and either
                // - doesn't have a form item
                // - the form item is not editable (or not being saved out)
                // So we assume it's unchanged, making this an update of an existing record
                if (operationType == null) {
                    //this.logWarn("saveData(): all primary key fields are present for the record, " + 
                    //             "and not editable / edited, so assuming this is an update operation");        
                    operationType = "update";
                }
            }
        }
        
        
        return operationType;
    },
    
    // form.saveData() internal callback
    _saveDataReply : function (request, response, data) {
        // this var keeps the index of the next formItem that we need to call formSaved() on.
        this._formSavedIndex = 0;
        
        // If 'data' is passed back from the server, update this.values with the saved data, except
        // for fields that have subsequently been further updated      
        if (data != null) {
            if (isc.isAn.Array(data)) data = data[0];
            // Note: if request.originalData is present, use this rather than request.data
            // This handles the case where request.data may have been reformatted / modified before
            // sending to the server
            // [For example see restDataSource / postMessage dataProtocol where request.data will
            //  be a serialized block of XML]
            // request.originalData matches the values as it was retrieved from the form when
            // the save was kicked off.
            // For iscServer operations use request.data
            // - this object will already be in the "standard" format, and we don't save off
            //   request.originalData in this code-path 
            var submittedValues =(request.originalData || request.data),
                currentValues = this.getValues();
            for (var i in data) {
                // We're making the assumption that any fields not present in the data object are
                // unchanged
                var field = this.getField(i);
                if (!this.fieldValuesAreEqual(field, submittedValues[i],data[i]) &&