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 setValues() on a ValuesManager
will automatically route new field values to whichever member form is showing an editor for that field. Likewise,
calling validate() will validate all member forms, and
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.

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.

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.

Is this ValuesManager waiting for an asynchronous validation to complete? This method will return true
after validate() is called on a component with
server-side validators for some field(s), until the server responds.

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).

ValuesManager

Method Detail

getOrCreateRef

getPaletteDefaults

public java.util.Map getPaletteDefaults()

This method returns a Map of config properties suitable for use as the "defaults"
attribute of a PaletteNode. Use it when you need to
work with PaletteNodes indirectly, such when setting up
TileRecords that will be used in a
TilePalette. See
the dev tools overview for examples of how to
assemble and acquire a suitable defaults object when you are creating a PaletteNode
indirectly

getAddOperation

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 synchronizeMembers().

Note : This is an advanced setting

Parameters:

autoSynchronize - New autoSynchronize value. 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 synchronizeMembers().

Returns:

Current autoSynchronize value. Default value is null

setDeepCloneOnEdit

public void setDeepCloneOnEdit(java.lang.Boolean deepCloneOnEdit)

Before we start editing the values of this ValuesManager in one or more DataBoundComponents, should we perform a deep
clone of the underlying values. See DataSource.deepCloneOnEdit for details of what this means.

getDeepCloneOnEdit

public java.lang.Boolean getDeepCloneOnEdit()

Before we start editing the values of this ValuesManager in one or more DataBoundComponents, should we perform a deep
clone of the underlying values. See DataSource.deepCloneOnEdit for details of what this means.

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. Default value is null

setSuppressValidationErrorCallback

When calling 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 dsRequest.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 willHandleError is specified on the
request. Note that this is the historical behavior for SmartGWT builds 4.0 and earlier

getSuppressValidationErrorCallback

public java.lang.Boolean getSuppressValidationErrorCallback()

When calling 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 dsRequest.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 willHandleError is specified on the
request. Note that this is the historical behavior for SmartGWT builds 4.0 and earlier

addMember

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.

Caution: If
a DynamicForm without a DataSource is passed to this method, DataBoundComponent.setDataSource() will be called on that
form, recreating the items from copies of the item configuration stored at the time the form was created. This means
that any properties or handlers added to the items after form creation will be lost. When in doubt, set the DataSource
in the form as soon as possible.

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
DynamicForm.cancelParamName with the value
DynamicForm.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:

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

clearValue

clearValues

public void clearValues()

Clear out all the values managed by this values manager.

editNewRecord

public void editNewRecord()

Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).
This method will also call DynamicForm.setSaveOperationType() to ensure 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).
This method will also call DynamicForm.setSaveOperationType() to ensure 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

Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).
This method will also call DynamicForm.setSaveOperationType() to ensure 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

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.

filterData

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.

Parameters:

criteria - search criteria

callback - callback to invoke on completion

requestProperties - additional properties to set on the DSRequest that will be issued

getErrors

public java.util.Map getErrors()

Returns the set of errors for this valuesManager. Errors will be returned as an object of the format {field1:errors, field2:errors} Where each errors object is either a single error message or an array of
error message strings.

Returns:

Object containing mapping from field names to error strings. Returns null if there are no errors for
this valuesManager.

getMemberForField

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).

getOldValues

public java.util.Map getOldValues()

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

isNewRecord

isPendingAsyncValidation

public java.lang.Boolean isPendingAsyncValidation()

Is this ValuesManager waiting for an asynchronous validation to complete? This method will return true
after validate() is called on a component with
server-side validators for some field(s), until the server responds.

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
valuesManager.getValues(), but will not be updated as the form is manipulated.

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.hiddenValidationErrors() or
ValuesManager.hiddenValidationErrors().

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 RPCRequest.willHandleError via the requestProperties parameter to force your callback to be invoked.
However, first consider:

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.

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.hiddenValidationErrors() or
ValuesManager.hiddenValidationErrors().

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 RPCRequest.willHandleError via the requestProperties parameter to force your callback to be invoked.
However, first consider:

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

setValues

public void setValues(java.util.Map values)

Replaces the current values of the ValuesManager and all member components with the values passed in.

Values should
be provided as an Object containing the new values as properties, where each propertyName is the name of a form item in one of the member forms, and each property value is the value to apply to
that form item via FormItem.setValue().

Values
with no corresponding form item may also be passed, will be tracked by the valuesManager and returned by subsequent
calls to getValues().

Any FormItem for which a value is not provided will revert to its defaultValue. To cause all FormItems to revert to
default values, pass null.

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.hiddenValidationErrors() will be fired to allow custom handling of hidden errors.

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, saveData() will be called to handle saving via Smart GWT databinding.

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

submit

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, saveData() will be called to handle saving via Smart GWT databinding.

The parameters to submit()
apply only if submit() will be calling 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

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.

synchronizeMembersOnDataPath

public void synchronizeMembersOnDataPath(java.lang.String dataPath)

Update just those of this ValuesManager's members that have the parameter dataPath, to reflect the current values held by the ValuesManager. Note,
it is not normally necessary to manually synchronize members

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.hiddenValidationErrors()
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.

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.

onInit

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().
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.

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()

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

removeMember

addMember

public void addMember(java.lang.String 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

addMember

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.

setFieldErrors

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

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

Takes a field 'name' or DataType,
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.

getValuesAsCriteria

Retrieves the combined com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria(),criteria values
for all member forms.

As with the DynamicForm getValuesAsCriteria, this method may return
AdvancedCriteria or simple Criteria depending on whether
the com.smartgwt.client.widgets.form.ValuesManager#setOperator,operator
is set to "or" rather than "and", and whether any member
forms return AdvancedCriteria.