com.smartgwt.client.widgets.form

## Class ValuesManager

- java.lang.Object
- - com.smartgwt.client.core.BaseClass
  - - com.smartgwt.client.widgets.form.ValuesManager

- All Implemented Interfaces:
    com.google.gwt.event.shared.HasHandlers, HasHiddenValidationErrorsHandlers

      public class ValuesManager
      extends BaseClass
      implements HasHiddenValidationErrorsHandlers

  The ValuesManager manages data from multiple member forms.

  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.

  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 `members` at init) or add and remove member forms dynamically.

  Calling `ValuesManager.setValues` on a ValuesManager will automatically route new field values to whichever member form is showing an editor for that field. Likewise, calling `ValuesManager.validate` will validate all member forms, and `ValuesManager.saveData` will initiate a save operation which aggregates values from all member forms.

  Like a DynamicForm, a ValuesManager can be databound by setting `dataSource`. In this case all member forms must also be bound to the same DataSource.

  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.

  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.

- - ### Field Summary

    - ### Fields inherited from class com.smartgwt.client.core.BaseClass

      `config, id, scClassName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ValuesManager()`
    `ValuesManager(com.google.gwt.core.client.JavaScriptObject jsObj)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `com.google.gwt.event.shared.HandlerRegistration` | `addHiddenValidationErrorsHandler(HiddenValidationErrorsHandler handler)` Add a hiddenValidationErrors handler.
    `void` | `addMember(DynamicForm member)` Add a new member to this valuesManager.
    `com.google.gwt.event.shared.HandlerRegistration` | `addSubmitValuesHandler(SubmitValuesHandler handler)` Add a submitValues handler.
    `void` | `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.
    `void` | `cancel(DSRequest requestProperties)` This method exists for clean integration with existing server frameworks that have a 'cancel' feature which typically clears session state associated with the form.
    `void` | `clearErrors(boolean showErrors)` Clears all errors from member forms.
    `void` | `clearFieldErrors(java.lang.String fieldName, boolean show)` Clear all validation errors associated with some field in this form
    `void` | `clearValue(java.lang.String fieldName)` Clear the value for some field.
    `void` | `clearValues()` Clear out all the values managed by this values manager.
    `com.google.gwt.core.client.JavaScriptObject` | `create()`
    `void` | `editNewRecord()` Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).
    `void` | `editNewRecord(java.util.Map initialValues)` Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).
    `void` | `editNewRecord(Record initialValues)` Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).
    `void` | `editRecord(Record record)` Edit an existing record.
    `void` | `editSelectedData(ListGrid selectionComponent)` Edit the record selected in the specified selection component (typically a `ListGrid`).
    `void` | `fetchData()` Retrieve data that matches the provided criteria, and edit the first record returned
    `void` | `fetchData(Criteria criteria)`
    `void` | `fetchData(Criteria criteria, DSCallback callback)`
    `void` | `fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)` Retrieve data that matches the provided criteria, and edit the first record returned
    `void` | `filterData()` Retrieve data that matches the provided criteria, and edit the first record returned. Differs from `DynamicForm.fetchData` in that a case insensitive substring match will be performed against the criteria to retrieve the data.
    `void` | `filterData(Criteria criteria)`
    `void` | `filterData(Criteria criteria, DSCallback callback)`
    `void` | `filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)` Retrieve data that matches the provided criteria, and edit the first record returned. Differs from `DynamicForm.fetchData` in that a case insensitive substring match will be performed against the criteria to retrieve the data.
    `java.lang.String` | `getAddOperation()` `operationId` to use when performing add operations.
    `java.lang.Boolean` | `getAutoSynchronize()` If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members.
    `static ValuesManager` | `getById(java.lang.String ID)` Retrieve a ValuesManager by it's global `ID`.
    `java.util.Map` | `getChangedValues()` Returns all values within this ValuesManager that have changed since `rememberValues` last ran.
    `DataSource` | `getDataSource()` The DataSource that this component should bind to for default fields and for performing `DSRequest`.
    `java.lang.Boolean` | `getDisableValidation()` If set to true, client-side validators will not run on the form when validate() is called.
    `java.util.Map` | `getErrors()` Returns the set of errors for this valuesManager.
    `java.lang.String[]` | `getFieldErrors(java.lang.String fieldName)` Returns any validation errors for some field in this valuesManager.
    `FormItem` | `getItem(java.lang.String itemID)` Retrieve a `FormItem` from this ValuesManager.
    `Canvas[]` | `getMemberCanvases()` Returns the members of this ValuesManager as an array of Canvas objects.
    `Canvas` | `getMemberForField(java.lang.String fieldName)` Given a fieldName or dataPath, this method will find the member responsible for interacting with that field's value.
    `DynamicForm[]` | `getMembers()` Returns an array of members in this ValuesManager.
    `java.util.Map` | `getOldValues()` Returns the set of values last stored by `ValuesManager.rememberValues`.
    `static ValuesManager` | `getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `DSOperationType` | `getSaveOperationType()` Default `DSOperationType` to be performed when `DynamicForm.saveData` is called.
    `java.lang.Boolean` | `getSuppressValidationErrorCallback()` When calling `ValuesManager.saveData` on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired.
    `java.lang.String` | `getUpdateOperation()` `operationId` to use when performing update operations.
    `java.lang.Object` | `getValue(java.lang.String fieldName)` Return the value of the field.
    `java.lang.String` | `getValueAsString(java.lang.String fieldName)` Return the value as String
    `java.util.Map` | `getValues()` Returns the current set of values for the values manager instance.
    `java.lang.Boolean` | `hasErrors()` Are there any errors associated with any fields in this valuesManager?
    `java.lang.Boolean` | `hasFieldErrors(java.lang.String fieldName)` Are there any errors associated with a field in this valuesManager?
    `java.lang.Boolean` | `isNewRecord()` Returns true if `saveOperationType` is currently "add".
    `protected void` | `onInit_ValuesManager()`
    `protected void` | `onInit()`
    `com.google.gwt.core.client.JavaScriptObject` | `rememberValues()` Make a snapshot of the current set of values, so we can reset to them later.
    `void` | `removeMember(DynamicForm member)` Remove a member form from this valuesManager, so its values are no longer managed by this instance.
    `void` | `removeMember(java.lang.String formID)` Remove a member form from this valuesManager, so its values are no longer managed by this instance.
    `void` | `removeMembers(DynamicForm... members)` Remove multiple member forms from this valuesManager.
    `void` | `resetValues()` Same as `DynamicForm.reset`.
    `void` | `saveData()` Validate and then save the form's current values to the `DataSource` this form is bound to.
    `void` | `saveData(DSCallback callback)`
    `void` | `saveData(DSCallback callback, DSRequest requestProperties)` Validate and then save the form's current values to the `DataSource` this form is bound to.
    `void` | `setAddOperation(java.lang.String addOperation)` `operationId` to use when performing add operations.
    `void` | `setAutoSynchronize(java.lang.Boolean autoSynchronize)` If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members.
    `void` | `setDataSource(DataSource dataSource)` The DataSource that this component should bind to for default fields and for performing DataSource requests
    `void` | `setDisableValidation(java.lang.Boolean disableValidation)` If set to true, client-side validators will not run on the form when validate() is called.
    `void` | `setErrors(java.util.Map errors, boolean showErrors)` Setter for validation errors on this form.
    `void` | `setFieldErrors(java.lang.String fieldName, java.lang.String[] errors, boolean showErrors)` Set field validation errors for some field.
    `void` | `setFieldErrors(java.lang.String fieldName, java.lang.String error, boolean showErrors)` Set field validation error for some field.
    `void` | `setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `void` | `setSaveOperationType(DSOperationType saveOperationType)` Default `DSOperationType` to be performed when `DynamicForm.saveData` is called.
    `void` | `setSuppressValidationErrorCallback(java.lang.Boolean suppressValidationErrorCallback)` When calling `ValuesManager.saveData` on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired.
    `void` | `setUpdateOperation(java.lang.String updateOperation)` `operationId` to use when performing update operations.
    `void` | `setValue(java.lang.String fieldName, boolean value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, DataClass value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, DataClass[] value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, java.util.Date value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, double value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, com.google.gwt.core.client.JavaScriptObject value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, java.util.Map value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, Record value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, Record[] value)` Set the value for some field.
    `void` | `setValue(java.lang.String fieldName, java.lang.String value)` Set the value for some field.
    `void` | `setValues(java.util.Map values)` Set the values for this values manager.
    `void` | `showErrors()` If this form has any outstanding validation errors, show them now. This method is called when the set of errors are changed by `DynamicForm.setErrors(java.util.Map, boolean)` or `DynamicForm.validate(boolean)`.
    `void` | `showFieldErrors()` Method to explicitly show the latest set of validation errors present on some field within this ValuesManager. If the field in question is present as a visible item in a member form, the form item will be redrawn to display the error message(s).
    `void` | `submit()` `submit()` is automatically called when a `SubmitItem` in a member form is clicked, or if `saveOnEnter` is set for some member form, when the "Enter" key is pressed in a text input.
    `void` | `submit(DSCallback callback)`
    `void` | `submit(DSCallback callback, DSRequest requestProperties)` `submit()` is automatically called when a `SubmitItem` in a member form is clicked, or if `saveOnEnter` is set for some member form, when the "Enter" key is pressed in a text input.
    `void` | `synchronizeMembers()` Update all of this ValuesManager's members to reflect the current values held by the ValuesManager.
    `java.lang.Boolean` | `validate()` Validate the current set of values for this values manager against validators defined in the member forms.
    `java.lang.Boolean` | `valuesHaveChanged()` Compares the current set of values with the values stored by the call to the `DynamicForm.rememberValues` method.

    - ### Methods inherited from class com.smartgwt.client.core.BaseClass

      `asSGWTComponent, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getJsObj, getOrCreateJsObj, getRef, getScClassName, internalSetID, internalSetID, isCreated, onBind, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, setProperty, setProperty, setProperty, setProperty, setScClassName`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

      `fireEvent`

- - ### Constructor Detail

    - #### ValuesManager

          public ValuesManager()

    - #### ValuesManager

          public ValuesManager(com.google.gwt.core.client.JavaScriptObject jsObj)

  - ### Method Detail

    - #### getOrCreateRef

          public static ValuesManager getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### setJavaScriptObject

          public void setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### create

          public com.google.gwt.core.client.JavaScriptObject create()

      Specified by:
        `create` in class `BaseClass`

    - #### setAddOperation

          public void setAddOperation(java.lang.String addOperation)

      `operationId` to use when performing add operations.
      Parameters:
        `addOperation` - . See `String`. Default value is null
      See Also:
        `Operations overview and related methods`

    - #### getAddOperation

          public java.lang.String getAddOperation()

      `operationId` to use when performing add operations.
      Returns:
        . See `String`
      See Also:
        `Operations overview and related methods`

    - #### setAutoSynchronize

          public void setAutoSynchronize(java.lang.Boolean autoSynchronize)

      If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members. You can manually synchronize member data values at any time with a call to `ValuesManager.synchronizeMembers`.

      Note : This is an advanced setting

      Parameters:
        `autoSynchronize` - autoSynchronize Default value is null

    - #### getAutoSynchronize

          public java.lang.Boolean getAutoSynchronize()

      If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members. You can manually synchronize member data values at any time with a call to `ValuesManager.synchronizeMembers`.
      Returns:
        Boolean

    - #### setDisableValidation

          public void setDisableValidation(java.lang.Boolean disableValidation)

      If set to true, client-side validators will not run on the form when validate() is called. Server-side validators (if any) will still run on attempted save.

      Note : This is an advanced setting

      Parameters:
        `disableValidation` - disableValidation Default value is null
      See Also:
        `DynamicForm.saveData()`, `DynamicForm.submit()`, `Validation overview and related methods`

    - #### getDisableValidation

          public java.lang.Boolean getDisableValidation()

      If set to true, client-side validators will not run on the form when validate() is called. Server-side validators (if any) will still run on attempted save.
      Returns:
        Boolean
      See Also:
        `DynamicForm.saveData()`, `DynamicForm.submit()`, `Validation overview and related methods`

    - #### setSaveOperationType

          public void setSaveOperationType(DSOperationType saveOperationType)

      Default `DSOperationType` to be performed when `DynamicForm.saveData` is called. This property is automatically set on a call to `DynamicForm.editRecord` or `DynamicForm.editNewRecord`, or may be set directly via `DynamicForm.setSaveOperationType`.

      If `saveOperationType` is unset, the form will heuristically determine whether an "add" or "update" operation is intended based on whether the primaryKey field is present and editable.
      If this method is called after the component has been drawn/initialized: Setter for the default `DSOperationType` when `DynamicForm.saveData` is called. Note that this property can also be set by calling `DynamicForm.editRecord` or `DynamicForm.editNewRecord`

      Parameters:
        `saveOperationType` - Operation type to use as a default. Valid values are `"add"` or `"update"`.. Default value is null

    - #### getSaveOperationType

          public DSOperationType getSaveOperationType()

      Default `DSOperationType` to be performed when `DynamicForm.saveData` is called. This property is automatically set on a call to `DynamicForm.editRecord` or `DynamicForm.editNewRecord`, or may be set directly via `DynamicForm.setSaveOperationType`.

      If `saveOperationType` is unset, the form will heuristically determine whether an "add" or "update" operation is intended based on whether the primaryKey field is present and editable.

      Returns:
        Returns the `DSOperationType` to be performed when `DynamicForm.saveData` is called. Valid options are `"add"` or `"update"`.

        If a `DSRequest` configuration object is passed in containing an explicit operationType this will be returned. Otherwise `saveOperationType` will be returned. This attribute is automatically set via calls to data binding methods such as `DynamicForm.editNewRecord`, or it may be set explicitly.

        If no explicit saveOperationType is specified for this form, the system will look at the current values for the form. If the form has no value for the `primaryKey field`, or that field is editable and has been modified we assume an add operation, otherwise an update. If the form is a member of a `ValuesManager`, the primary key field value will be derived from the valuesManager's values object.

    - #### setSuppressValidationErrorCallback

          public void setSuppressValidationErrorCallback(java.lang.Boolean suppressValidationErrorCallback)

      When calling `ValuesManager.saveData` on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired. If the error code returned by the server indicates a validation error, it will be displayed to the user by updating the form items to show the error messages, and firing any specified hiddenValidationErrors handler, otherwise the standard RPCManager error handling logic would be invoked.

      Developers who want to handle errors themselves can override this default by specifying willHandleError on the DSRequest. In this case the callback passed in will be fired even if the server returns an error status code.

      If `suppressValidationErrorCallback` is set to true, if a save attempt returns a validation error code, the user-specified callback will not be fired even if `willHandleError:true` was specified on the dsRequest - though for other error codes, the callback would be fired if willHandle error is specified on the request. Note that this is the historical behavior for Smart GWT builds 8.0 and earlier SmartGWT builds 4.0 and earlier

      Note : This is an advanced setting

      Parameters:
        `suppressValidationErrorCallback` - suppressValidationErrorCallback Default value is false

    - #### getSuppressValidationErrorCallback

          public java.lang.Boolean getSuppressValidationErrorCallback()

      When calling `ValuesManager.saveData` on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired. If the error code returned by the server indicates a validation error, it will be displayed to the user by updating the form items to show the error messages, and firing any specified hiddenValidationErrors handler, otherwise the standard RPCManager error handling logic would be invoked.

      Developers who want to handle errors themselves can override this default by specifying willHandleError on the DSRequest. In this case the callback passed in will be fired even if the server returns an error status code.

      If `suppressValidationErrorCallback` is set to true, if a save attempt returns a validation error code, the user-specified callback will not be fired even if `willHandleError:true` was specified on the dsRequest - though for other error codes, the callback would be fired if willHandle error is specified on the request. Note that this is the historical behavior for Smart GWT builds 8.0 and earlier SmartGWT builds 4.0 and earlier

      Returns:
        Boolean

    - #### setUpdateOperation

          public void setUpdateOperation(java.lang.String updateOperation)

      `operationId` to use when performing update operations.
      Parameters:
        `updateOperation` - . See `String`. Default value is null
      See Also:
        `Operations overview and related methods`

    - #### getUpdateOperation

          public java.lang.String getUpdateOperation()

      `operationId` to use when performing update operations.
      Returns:
        . See `String`
      See Also:
        `Operations overview and related methods`

    - #### addMember

          public void addMember(DynamicForm member)

      Add a new member to this valuesManager. Any `Canvas` can be a member of a valuesManager, even components like `Layout` or `TabSet` that do not actually have any values to manage. When "valueless" components like these bind to a ValuesManager, it is in order to provide their own child components with a shared valuesManager so that complex data can be displayed and edited - see `dataPath` for more details.

      For components like `DynamicForm` and `ListGrid`, which do have a set of values to manage, the component's values will subsequently be available through this valuesManager.

      Note on pre-existent values when the member component is a `DynamicForm`:
      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.
      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.

      Parameters:
        `member` - component (or ID of component) to add to this valuesManager as a member.
      See Also:
        `com.smartgwt.client.widgets.form.ValuesManager#addMembers`

    - #### cancel

          public void 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 `cancelParamName` with the value `cancelParamValue`.

      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:

            dynamicFormInstance.cancel({ignoreTimeout: true, target: null});

      See Also:
        `DynamicForm.cancelEditing()`, `Submitting overview and related methods`

    - #### cancel

          public void cancel(DSRequest requestProperties)

      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 `cancelParamName` with the value `cancelParamValue`.

      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:

            dynamicFormInstance.cancel({ignoreTimeout: true, target: null});

      Parameters:
        `requestProperties` - additional properties to set on the RPCRequest that will be issued
      See Also:
        `DynamicForm.cancelEditing()`, `Submitting overview and related methods`

    - #### clearErrors

          public void clearErrors(boolean showErrors)

      Clears all errors from member forms.
      Parameters:
        `showErrors` - If true, clear any visible error messages.
      See Also:
        `Errors overview and related methods`

    - #### clearFieldErrors

          public void clearFieldErrors(java.lang.String fieldName,
                              boolean show)

      Clear all validation errors associated with some field in this form
      Parameters:
        `fieldName` - field for which errors should be cleared
        `show` - if true, and the field is present in one of our member forms, redraw it to clear any currently visible validation errors
      See Also:
        `Errors overview and related methods`

    - #### clearValue

          public void clearValue(java.lang.String fieldName)

      Clear the value for some field.
      Parameters:
        `fieldName` - Which field to set the value for

    - #### clearValues

          public void clearValues()

      Clear out all the values managed by this values manager.

    - #### fetchData

          public void fetchData()

      Retrieve data that matches the provided criteria, and edit the first record returned
      See Also:
        `DataBoundComponentMethods overview and related methods`

    - #### fetchData

          public void fetchData(Criteria criteria)

      See Also:
        `ValuesManager#fetchData()}`

    - #### fetchData

          public void fetchData(Criteria criteria,
                       DSCallback callback)

      See Also:
        `ValuesManager#fetchData()}`

    - #### fetchData

          public void fetchData(Criteria criteria,
                       DSCallback callback,
                       DSRequest requestProperties)

      Retrieve data that matches the provided criteria, and edit the first record returned
      Parameters:
        `criteria` - search criteria
        `callback` - callback to invoke on completion
        `requestProperties` - additional properties to set on the DSRequest that will be issued
      See Also:
        `DataBoundComponentMethods overview and related methods`

    - #### filterData

          public void filterData()

      Retrieve data that matches the provided criteria, and edit the first record returned.
      Differs from `DynamicForm.fetchData` in that a case insensitive substring match will be performed against the criteria to retrieve the data.
      See Also:
        `DataBoundComponentMethods overview and related methods`

    - #### filterData

          public void filterData(Criteria criteria)

      See Also:
        `ValuesManager#filterData()}`

    - #### filterData

          public void filterData(Criteria criteria,
                        DSCallback callback)

      See Also:
        `ValuesManager#filterData()}`

    - #### filterData

          public void filterData(Criteria criteria,
                        DSCallback callback,
                        DSRequest requestProperties)

      Retrieve data that matches the provided criteria, and edit the first record returned.
      Differs from `DynamicForm.fetchData` in that a case insensitive substring match will be performed against the criteria to retrieve the data.
      Parameters:
        `criteria` - search criteria
        `callback` - callback to invoke on completion
        `requestProperties` - additional properties to set on the DSRequest that will be issued
      See Also:
        `DataBoundComponentMethods overview and related methods`

    - #### getMemberForField

          public Canvas getMemberForField(java.lang.String fieldName)

      Given a fieldName or dataPath, this method will find the member responsible for interacting with that field's value. If no form is found, returns null.
      Parameters:
        `fieldName` - fieldName or dataPath to check
      Returns:
        member responsible for displaying this field (may be null).

    - #### addHiddenValidationErrorsHandler

          public com.google.gwt.event.shared.HandlerRegistration addHiddenValidationErrorsHandler(HiddenValidationErrorsHandler handler)

      Add a hiddenValidationErrors handler.

      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
      - a field in a hidden or undrawn member form
      - a hidden field in a visible member form
      - for databound ValuesManagers, a datasource field with specified validators, but not associated item in any member.
      Implement this to provide custom validation error handling for these fields.
      By default hidden validation errors will be logged as warnings in the developerConsole. Call `HiddenValidationErrorsEvent.cancel()` from within `HiddenValidationErrorsHandler#onHiddenValidationErrors` from this method to suppress that behavior.

      Specified by:
        `addHiddenValidationErrorsHandler` in interface `HasHiddenValidationErrorsHandlers`
      Parameters:
        `handler` - the hiddenValidationErrors handler
      Returns:
        `HandlerRegistration` used to remove this handler

    - #### hasErrors

          public java.lang.Boolean hasErrors()

      Are there any errors associated with any fields in this valuesManager?
      Returns:
        returns true if there are any outstanding validation errors, false otherwise.
      See Also:
        `Errors overview and related methods`

    - #### hasFieldErrors

          public java.lang.Boolean hasFieldErrors(java.lang.String fieldName)

      Are there any errors associated with a field in this valuesManager?
      Parameters:
        `fieldName` - field to check for errors
      Returns:
        returns true if there are any outstanding validation errors, false otherwise.
      See Also:
        `Errors overview and related methods`

    - #### isNewRecord

          public java.lang.Boolean isNewRecord()

      Returns true if `saveOperationType` is currently "add". See `saveOperationType`.
      Returns:
        whether this form will use an "add" operation when saving

    - #### removeMember

          public void removeMember(DynamicForm member)

      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 `valuesManager.getValues()`, but will not be updated as the form is manipulated.
      Parameters:
        `member` - form (or ID of form) to remove from this valuesManager
      See Also:
        `removeMembers(com.smartgwt.client.widgets.form.DynamicForm...)`

    - #### removeMembers

          public void removeMembers(DynamicForm... members)

      Remove multiple member forms from this valuesManager.
      Parameters:
        `members` - array of forms to remove
      See Also:
        `removeMember(com.smartgwt.client.widgets.form.DynamicForm)`

    - #### resetValues

          public void resetValues()

      Same as `DynamicForm.reset`.

    - #### saveData

          public void saveData()

      Validate and then save the form's current values to the `DataSource` this form is bound to.

      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.

      If client-side validation passes, a `DSRequest` will be sent, exactly as though `DataSource.addData` or `DataSource.updateData` had been called with ${isc.DocUtils.linkForRef('method:DynamicForm.getValues','the form's values')} as data. The `operationType` will be either "update" or "add", depending on the current `saveOperationType`.

      On either a client-side or server-side validation failure, validation errors will be displayed in the form. Visible items within a DynamicForm will be redrawn to display errors. Validation failure occurring on hidden items, or DataSource fields with no associated form items may be handled via `DynamicForm.handleHiddenValidationErrors` or `ValuesManager.handleHiddenValidationErrors`.

      In the case of a validation error, the callback will not be called by default since the form has already handled the failed save by displaying the validation errors to the user. If you need to do something additional in this case, you can set `willHandleError` via the `requestProperties` parameter to force your callback to be invoked. However, first consider:

      - if you are trying to customize display of validation errors, there are several `built-in modes` and `DynamicForm.showErrors` may be a better place to put customizations.
      - for unrecoverable general errors (eg server is down), `central error handling` in invoked, so consider placing customizations there unless an unrecoverable error should be handled specially by this specific form.
      See Also:
        `DataBoundComponentMethods overview and related methods`, Add Example

    - #### saveData

          public void saveData(DSCallback callback)

      See Also:
        `ValuesManager#saveData()}`

    - #### saveData

          public void saveData(DSCallback callback,
                      DSRequest requestProperties)

      Validate and then save the form's current values to the `DataSource` this form is bound to.

      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.

      If client-side validation passes, a `DSRequest` will be sent, exactly as though `DataSource.addData` or `DataSource.updateData` had been called with ${isc.DocUtils.linkForRef('method:DynamicForm.getValues','the form's values')} as data. The `operationType` will be either "update" or "add", depending on the current `saveOperationType`.

      On either a client-side or server-side validation failure, validation errors will be displayed in the form. Visible items within a DynamicForm will be redrawn to display errors. Validation failure occurring on hidden items, or DataSource fields with no associated form items may be handled via `DynamicForm.handleHiddenValidationErrors` or `ValuesManager.handleHiddenValidationErrors`.

      In the case of a validation error, the callback will not be called by default since the form has already handled the failed save by displaying the validation errors to the user. If you need to do something additional in this case, you can set `willHandleError` via the `requestProperties` parameter to force your callback to be invoked. However, first consider:

      - if you are trying to customize display of validation errors, there are several `built-in modes` and `DynamicForm.showErrors` may be a better place to put customizations.
      - for unrecoverable general errors (eg server is down), `central error handling` in invoked, so consider placing customizations there unless an unrecoverable error should be handled specially by this specific form.
      Parameters:
        `callback` - callback to invoke on completion
        `requestProperties` - additional properties to set on the DSRequest that will be issued
      See Also:
        `DataBoundComponentMethods overview and related methods`, Add Example

    - #### showFieldErrors

          public void showFieldErrors()

      Method to explicitly show the latest set of validation errors present on some field within this ValuesManager.
      If the field in question is present as a visible item in a member form, the form item will be redrawn to display the error message(s). Otherwise `ValuesManager.handleHiddenValidationErrors` will be fired to allow custom handling of hidden errors.
      See Also:
        `Errors overview and related methods`

    - #### submit

          public void submit()

      `submit()` is automatically called when a `SubmitItem` in a member form is clicked, or if `saveOnEnter` is set for some member form, when the "Enter" key is pressed in a text input. Submit can also be manually called.

      If `valuesManager.submitValues()` exists, it will be called, and no further action will be taken.

      Otherwise, `ValuesManager.saveData` will be called to handle saving via Smart GWT databinding.

      The parameters to `submit()` apply only if `submit()` will be calling `ValuesManager.saveData`. If you override `submit()`, you can safely ignore the parameters as Smart GWT framework code does not pass them.

      See Also:
        `com.smartgwt.client.widgets.form.ValuesManager#submitValues`, `DataBoundComponentMethods overview and related methods`

    - #### submit

          public void submit(DSCallback callback)

      See Also:
        `ValuesManager#submit()}`

    - #### submit

          public void submit(DSCallback callback,
                    DSRequest requestProperties)

      `submit()` is automatically called when a `SubmitItem` in a member form is clicked, or if `saveOnEnter` is set for some member form, when the "Enter" key is pressed in a text input. Submit can also be manually called.

      If `valuesManager.submitValues()` exists, it will be called, and no further action will be taken.

      Otherwise, `ValuesManager.saveData` will be called to handle saving via Smart GWT databinding.

      The parameters to `submit()` apply only if `submit()` will be calling `ValuesManager.saveData`. If you override `submit()`, you can safely ignore the parameters as Smart GWT framework code does not pass them.

      Parameters:
        `callback` - callback to invoke on completion.
        `requestProperties` - additional properties to set on the DSRequest that will be issued
      See Also:
        `com.smartgwt.client.widgets.form.ValuesManager#submitValues`, `DataBoundComponentMethods overview and related methods`

    - #### synchronizeMembers

          public void synchronizeMembers()

      Update all of this ValuesManager's members to reflect the current values held by the ValuesManager. It is not normally necessary to manually synchronize members, but you will need to do so if you switch off `automatic synchronization`.

    - #### validate

          public java.lang.Boolean validate()

      Validate the current set of values for this values manager against validators defined in the member forms. For databound valuesManagers, also perform validation against any validators defined on datasource fields.

      Note that if validation errors occur for a value that is not shown in any member forms, those errors will cause a warning and `ValuesManager.handleHiddenValidationErrors` will be called. This can occur if:
      - A datasource field has no corresponding item in any member form
      - The item in question is hidden
      - The member form containing the item is hidden.

      Returns:
        true if all validation passed
      See Also:
        Splitting Example

    - #### valuesHaveChanged

          public java.lang.Boolean valuesHaveChanged()

      Compares the current set of values with the values stored by the call to the `DynamicForm.rememberValues` method. `rememberValues()` runs when the form is initialized and on every call to `DynamicForm.setValues`. Returns true if the values have changed, and false otherwise.
      Returns:
        true if current values do not match remembered values
      See Also:
        `getChangedValues()`, `getOldValues()`

    - #### getById

          public static ValuesManager getById(java.lang.String ID)

      Retrieve a ValuesManager by it's global `ID`.
      Parameters:
        `ID` - global ID of the ValuesManager
      Returns:
        the ValuesManager, or null if not found

    - #### onInit

          protected void onInit()

      Overrides:
        `onInit` in class `BaseClass`

    - #### onInit_ValuesManager

          protected void onInit_ValuesManager()

    - #### showErrors

          public void showErrors()

      If this form has any outstanding validation errors, show them now.
      This method is called when the set of errors are changed by `DynamicForm.setErrors(java.util.Map, boolean)` or `DynamicForm.validate(boolean)`.
      Default implementation will redraw the form to display error messages and call `com.smartgwt.client.widgets.form.DynamicForm#handleHiddenValidationErrors` to display errors with no visible field.

      Note: This is an override point. This method may be overridden to perform custom display of validation errors.

    - #### setDataSource

          public void setDataSource(DataSource dataSource)

      The DataSource that this component should bind to for default fields and for performing DataSource requests

      Parameters:
        `dataSource` - dataSource Default value is null

    - #### getDataSource

          public DataSource getDataSource()

      The DataSource that this component should bind to for default fields and for performing `DSRequest`.

      Can be specified as either a DataSource instance or the String ID of a DataSource.

      Returns:
        DataSource

    - #### setValues

          public void setValues(java.util.Map values)

      Set the values for this values manager. Member forms will be updated as required by this change. Note that pre-existant values in other fields are cleared out by this.
      Parameters:
        `values` - the values

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      java.lang.String value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      double value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      boolean value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      java.util.Date value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      com.google.gwt.core.client.JavaScriptObject value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      java.util.Map value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      Record value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      DataClass value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      Record[] value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### setValue

          public void setValue(java.lang.String fieldName,
                      DataClass[] value)

      Set the value for some field.
      Parameters:
        `fieldName` - Name of the field being updated
        `value` - New value.

    - #### getValueAsString

          public java.lang.String getValueAsString(java.lang.String fieldName)

      Return the value as String
      Parameters:
        `fieldName` - the field name
      Returns:
        the value

    - #### getValue

          public java.lang.Object getValue(java.lang.String fieldName)

      Return the value of the field.
      Parameters:
        `fieldName` - the field name
      Returns:
        the value

    - #### getValues

          public java.util.Map getValues()

      Returns the current set of values for the values manager instance. This includes the values from any form managed by this manager, as well as any values explicitly applied via ValuesManager.setValues().
      Returns:
        the values

    - #### getChangedValues

          public java.util.Map getChangedValues()

      Returns all values within this ValuesManager that have changed since `rememberValues` last ran. Note that `rememberValues` runs on valuesManager initialization, and with every call to `ValuesManager.setValues` so this will typically contain all values the user has explicitly edited since then.
      Returns:
        the values

    - #### getOldValues

          public java.util.Map getOldValues()

      Returns the set of values last stored by `ValuesManager.rememberValues`. Note that `rememberValues()` is called automatically by `ValuesManager.setValues`, and on form initialization, so this typically contains all values as they were before the user edited them.
      Returns:
        the values

    - #### editSelectedData

          public void editSelectedData(ListGrid selectionComponent)

      Edit the record selected in the specified selection component (typically a `ListGrid`).

      Updates the values of this editor to match the selected record's values.

      If this form has a dataSource, then saving via `saveData()` will use the "update" operation type.

      Parameters:
        `selectionComponent` - the ListGrid or ID of a `ListGrid` whose currently selected record(s) is/are to be edited

    - #### editRecord

          public void editRecord(Record record)

      Edit an existing record. Updates this editors values to match the values of the record passed in, via `setValues(java.util.Map)`.

      This method will also call `DynamicForm.setSaveOperationType(com.smartgwt.client.types.DSOperationType)` to ensure subsequent calls to `saveData()` will use an `update` rather than an `add` operation.

      Parameters:
        `record` - the record to be edited as a map of field names to their corresponding values

    - #### editNewRecord

          public void editNewRecord()

      Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified). Subsequent calls to saveData() will use an add rather than an update operation.

    - #### editNewRecord

          public void editNewRecord(java.util.Map initialValues)

      Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified). Subsequent calls to saveData() will use an add rather than an update operation.
      Parameters:
        `initialValues` - initial set of values for the editor as a map of field names to their corresponding values

    - #### editNewRecord

          public void editNewRecord(Record initialValues)

      Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified). Subsequent calls to saveData() will use an add rather than an update operation.
      Parameters:
        `initialValues` - initial set of values for the editor as a `Record` of attributes whose names correspond to values.

    - #### getMembers

          public DynamicForm[] getMembers()

      Returns an array of members in this ValuesManager. Note that this is a convenience method: it returns an array of DynamicForm, and so can only be validly used if all the ValuesManager's members are DynamicForms (a ValuesManager's members are traditionally DynamicForms, but they can be any kind of Canvas). See `getMemberCanvases()`
      Returns:
        the members

    - #### getMemberCanvases

          public Canvas[] getMemberCanvases()

      Returns the members of this ValuesManager as an array of Canvas objects. See also `getMembers()`
      Returns:
        the members

    - #### removeMember

          public void removeMember(java.lang.String formID)

      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 valuesManager.getValues(), but will not be updated as the form is manipulated.
      Parameters:
        `formID` - ID of the form to remove from this valuesManager

    - #### rememberValues

          public com.google.gwt.core.client.JavaScriptObject rememberValues()

      Make a snapshot of the current set of values, so we can reset to them later. Creates a new object, then adds all non-method properties of values to the new object. Use resetValues() to revert to these values. Note that this method is automatically called when the values for this form are set programmatically via a call to DynamicForm.setValues().
      Returns:
        copy of current form values

    - #### setErrors

          public void setErrors(java.util.Map errors,
                       boolean showErrors)

      Setter for validation errors on this form. Errors passed in should be a Map in the format {fieldName1:errors, fieldName2:errors}

      Where the errors value may be either a string (single error message) or an array of strings (if multiple errors should be applied to the field in question).
      Parameters:
        `errors` - list of errors as a map with the field names as keys
        `showErrors` - If true redraw form to display errors now. Otherwise errors can be displayed by calling `showErrors()` Note: When the errors are shown, handleHiddenValidationErrors() will be fired for errors on hidden fields, or with no associated formItem.

    - #### getErrors

          public java.util.Map getErrors()

      Returns the set of errors for this valuesManager.
      Returns:
        errors. key is field name, value is error. Returns null if no errors

    - #### setFieldErrors

          public void setFieldErrors(java.lang.String fieldName,
                            java.lang.String error,
                            boolean showErrors)

      Set field validation error for some field. The showErrors parameter allows the errors to be displayed immediately. Alternatively, an explicit call to `DynamicForm.showFieldErrors(java.lang.String)` will display the errors for this field.
      Parameters:
        `fieldName` - field to apply the new errors to
        `error` - error to apply to the field in question
        `showErrors` - If true this method will fall through to DynamicForm.showFieldErrors() to update the display

    - #### setFieldErrors

          public void setFieldErrors(java.lang.String fieldName,
                            java.lang.String[] errors,
                            boolean showErrors)

      Set field validation errors for some field. The showErrors parameter allows the errors to be displayed immediately. Alternatively, an explicit call to `DynamicForm.showFieldErrors(java.lang.String)` will display the errors for this field.
      Parameters:
        `fieldName` - field to apply the new errors to
        `errors` - errors to apply to the field in question
        `showErrors` - If true this method will fall through to DynamicForm.showFieldErrors() to update the display

    - #### getFieldErrors

          public java.lang.String[] getFieldErrors(java.lang.String fieldName)

      Returns any validation errors for some field in this valuesManager. If no errors are present, will return null.
      Parameters:
        `fieldName` - the field name
      Returns:
        error messages for the field.

    - #### getItem

          public FormItem getItem(java.lang.String itemID)

      Retrieve a `FormItem` from this ValuesManager.

      Takes a field `'name'` or ${isc.DocUtils.linkForRef('dataPath')}, and searches through the members of this valuesManager for an editor for that field. If found the appropriate formItem will be returned. Note that if a dataPath is passed in, it should be the full data path for the item, including any canvas level `'dataPath'` specified on the member form containing this form item.
      Note: Unlike the `DynamicForm` class, this method will not return an item by index

      Parameters:
        `itemID` - item fieldName or dataPath identifier
      Returns:
        form item for editing/displaying the appropriate field, or null if no formItem can be found for the field.

    - #### addSubmitValuesHandler

          public com.google.gwt.event.shared.HandlerRegistration addSubmitValuesHandler(SubmitValuesHandler handler)

      Add a submitValues handler.

      Triggered when a `submit()` is called on this valuesManager (or any form included in this valuesManager).

      Parameters:
        `handler` - the submitValues handler
      Returns:
        `HandlerRegistration` used to remove this handler