Class ValuesManager
- All Implemented Interfaces:
HasHandlers,HasAsyncValidationReplyHandlers,HasMemberSynchronizedHandlers,HasHiddenValidationErrorsHandlers
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.
-
Field Summary
Fields inherited from class com.smartgwt.client.core.BaseClass
config, configOnly, factoryCreated, factoryProperties, id, scClassName -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionAdd a asyncValidationReply handler.Add a hiddenValidationErrors handler.voidvoidaddMember(DynamicForm member) Add a new member to this valuesManager.voidAdd a new member to this valuesManager.Add a memberSynchronized handler.Add a submitValues handler.voidDeprecated.As of Smartclient version 13.0, due to the removal of Apache Struts.Performs silent validation of the value manager values, likevaluesAreValid().checkForValidationErrors(ValidationStatusCallback callback, boolean skipServerValidation) Performs silent validation of the value manager values, likevaluesAreValid().voidclearErrors(boolean showErrors) Clears all errors from member forms.voidclearFieldErrors(String fieldName, boolean show) Clear all validation errors associated with some field in this formvoidclearValue(String fieldName) Clear the value for some field.voidClear out all the values managed by this values manager.create()voidPrepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).voideditNewRecord(Record initialValues) Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).voideditNewRecord(Map initialValues) Prepare to edit a new record by clearing the current set of values (or replacing them with initialValues if specified).voideditRecord(Record record) Edit an existing record.voideditSelectedData(ListGrid selectionComponent) Edit the record selected in the specified selection component (typically aListGrid).voidRetrieve data that matches the provided criteria, and edit the first record returnedvoidvoidfetchData(Criteria criteria, DSCallback callback) voidfetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties) Retrieve data that matches the provided criteria, and edit the first record returnedvoidRetrieve data that matches the provided criteria, and edit the first record returned.
Differs fromDynamicForm.fetchData()in that a case insensitive substring match will be performed against the criteria to retrieve the data.voidfilterData(Criteria criteria) voidfilterData(Criteria criteria, DSCallback callback) voidfilterData(Criteria criteria, DSCallback callback, DSRequest requestProperties) Retrieve data that matches the provided criteria, and edit the first record returned.
Differs fromDynamicForm.fetchData()in that a case insensitive substring match will be performed against the criteria to retrieve the data.operationIdto use when performing add operations.If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members.static ValuesManagerRetrieve a ValuesManager by it's globalID.Returns all values within this DynamicForm that have changed sinceDynamicForm.rememberValues()last ran.The DataSource that this component should bind to for default fields and for performingDSRequest.When editing values in this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or byFormItem.dataPath.Before we start editing the values of this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of the underlying values.If set to true, client-side validators will not run on the form when validate() is called.Returns the set of errors for this valuesManager.operationIdto use when performing fetch operations.String[]getFieldErrors(String fieldName) Returns any validation errors for some field in this valuesManager.Retrieve aFormItemfrom this ValuesManager.Canvas[]Returns the members of this ValuesManager as an array of Canvas objects.getMemberForField(String fieldName) Given a fieldName or dataPath, this method will find the member responsible for interacting with that field's value.Returns an array of members in this ValuesManager.Returns the set of values last stored byDynamicForm.rememberValues().What operator should be used to combine sub-criteria from member forms whengetValuesAsCriteria()is called?static ValuesManagergetOrCreateRef(JavaScriptObject jsObj) This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode.operationIdto use when performing remove operations.DefaultDSOperationTypeto be performed whenDynamicForm.saveData()is called.When callingsaveData()on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired.operationIdto use when performing update operations.Return the value of the field.getValueAsString(String fieldName) Return the value as StringReturns the current set of values for the values manager instance.Return an AdvancedCriteria object based on the current set of values within memberForms.getValuesAsAdvancedCriteria(TextMatchStyle textMatchStyle) Return an AdvancedCriteria object based on the current set of values within memberForms.Retrieves the combined {@link com.smartgwt.client.widgets.form.DynamicForm#getValuesAsCriteria(),criteria values} for all member forms.Returns the current set of values for the values manager instance.Are there any errors associated with any fields in this valuesManager?hasFieldErrors(String fieldName) Are there any errors associated with a field in this valuesManager?Returns true ifsaveOperationTypeis currently "add".Is thisValuesManagerwaiting for an asynchronous validation to complete? This method will return true aftervalidate()is called on a component with server-side validators for some field(s), until the server responds.voiditemChanged(FormItem item, Object newValue) Handler fired whenever a change to a FormItem fires itemChanged() on one of the member forms.protected voidonInit()protected voidMake a snapshot of the current set of values, so we can reset to them later.voidremoveMember(Canvas member) voidremoveMember(DynamicForm member) Remove a member form from this valuesManager, so its values are no longer managed by this instance.voidremoveMember(String formID) Remove a member form from this valuesManager, so its values are no longer managed by this instance.voidremoveMembers(DynamicForm... members) Remove multiple member forms from this valuesManager.voidSame asDynamicForm.reset().voidsaveData()Validate and then save the form's current values to theDataSourcethis form is bound to.voidsaveData(DSCallback callback) voidsaveData(DSCallback callback, DSRequest requestProperties) Validate and then save the form's current values to theDataSourcethis form is bound to.setAddOperation(String addOperation) operationIdto use when performing add operations.setAutoSynchronize(Boolean autoSynchronize) If explicitly set to false, prevents the ValuesManager from automatically propagating data value changes to its members.voidsetDataSource(DataSource dataSource) The DataSource that this component should bind to for default fields and for performing
 DataSource requestssetDeepCloneNonFieldValuesOnEdit(Boolean deepCloneNonFieldValuesOnEdit) When editing values in this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or byFormItem.dataPath.setDeepCloneOnEdit(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.setDisableValidation(Boolean disableValidation) If set to true, client-side validators will not run on the form when validate() is called.voidSetter for validation errors on this form.setFetchOperation(String fetchOperation) operationIdto use when performing fetch operations.voidsetFieldErrors(String fieldName, String[] errors, boolean showErrors) Set field validation errors for some field.voidsetFieldErrors(String fieldName, String error, boolean showErrors) Set field validation error for some field.setOperator(OperatorId operator) What operator should be used to combine sub-criteria from member forms whengetValuesAsCriteria()is called?setRemoveOperation(String removeOperation) operationIdto use when performing remove operations.setSaveOperationType(DSOperationType saveOperationType) DefaultDSOperationTypeto be performed whenDynamicForm.saveData()is called.setSuppressValidationErrorCallback(Boolean suppressValidationErrorCallback) When callingsaveData()on a form or valuesManager, by default if the server returns an error code, any callback passed into saveData() will not be fired.setUpdateOperation(String updateOperation) operationIdto use when performing update operations.voidSet the value for some field.voidSet the value for some field.voidsetValue(String fieldName, JavaScriptObject value) Set the value for some field.voidSet the value for some field.voidSet the value for some field.voidSet the value for some field.voidSet the value for some field.voidSet the value for some field.voidSet the value for some field.voidSet the value for some field.voidReplaces the current values of the ValuesManager and all member components with the values passed in.voidIf this form has any outstanding validation errors, show them now.

 This method is called when the set of errors are changed byDynamicForm.setErrors(java.util.Map, boolean)or
DynamicForm.validate().voidMethod 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).voidsubmit()submit()is automatically called when aSubmitItemin a member form is clicked, or ifsaveOnEnteris set for some member form, when the "Enter" key is pressed in a text input.voidsubmit(DSCallback callback) voidsubmit(DSCallback callback, DSRequest requestProperties) submit()is automatically called when aSubmitItemin a member form is clicked, or ifsaveOnEnteris set for some member form, when the "Enter" key is pressed in a text input.voidsynchronizeMember(Canvas member) Update the parameter ValuesManager member to reflect the current values held by the ValuesManager.voidUpdate all of this ValuesManager's members to reflect the current values held by the ValuesManager.voidsynchronizeMembersOnDataPath(String dataPath) Update just those of this ValuesManager's members that have the parameterdataPath, to reflect the current values held by the ValuesManager.validate()Validate the current set of values for this values manager against validators defined in the member forms.booleanMethod to determine whether the current set of values for this values manager would pass validation by the validators defined in the member forms.Compares the current set of values with the values stored by the call to theDynamicForm.rememberValues()method.Methods inherited from class com.smartgwt.client.core.BaseClass
addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, 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, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isCreated, isFactoryCreated, onBind, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setID, setJavaScriptObject, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassNameMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Constructor Details
-
ValuesManager
public ValuesManager() -
ValuesManager
-
-
Method Details
-
getOrCreateRef
-
getPaletteDefaults
This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode. Use it when you need to work with PaletteNodes indirectly, such when setting upTileRecords that will be used in aTilePalette. Seethe dev tools overviewfor examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly -
create
-
setAddOperation
operationIdto use when performing add operations.- Parameters:
addOperation- New addOperation value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
getAddOperation
operationIdto use when performing add operations.- Returns:
- Current addOperation value. Default value is null
- See Also:
-
setAutoSynchronize
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 tosynchronizeMembers().Note : This is an advanced setting
- Parameters:
autoSynchronize- New autoSynchronize value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls
-
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 tosynchronizeMembers().- Returns:
- Current autoSynchronize value. Default value is null
-
setDeepCloneNonFieldValuesOnEdit
When editing values in this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or byFormItem.dataPath. If this value is not explicitly set, it defaults to the value ofDataSource.deepCloneNonFieldValuesOnEditif there is a dataSource, or to the value of the staticdeepCloneNonFieldValuesOnEditif there is no dataSource.Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.Note : This is an advanced setting
- Parameters:
deepCloneNonFieldValuesOnEdit- New deepCloneNonFieldValuesOnEdit value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
getDeepCloneNonFieldValuesOnEdit
When editing values in this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or byFormItem.dataPath. If this value is not explicitly set, it defaults to the value ofDataSource.deepCloneNonFieldValuesOnEditif there is a dataSource, or to the value of the staticdeepCloneNonFieldValuesOnEditif there is no dataSource.Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.- Returns:
- Current deepCloneNonFieldValuesOnEdit value. Default value is null
- See Also:
-
setDeepCloneOnEdit
Before we start editing the values of this ValuesManager in one or more DataBoundComponents, should we perform a deep clone of the underlying values. SeeDataSource.deepCloneOnEditfor details of what this means.If this value is not explicitly set, it defaults to the value of
DataSource.deepCloneOnEdit. This value can be overridden per-field withDataSourceField.deepCloneOnEdit.Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, usingdataPaths.Note : This is an advanced setting
- Parameters:
deepCloneOnEdit- New deepCloneOnEdit value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
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. SeeDataSource.deepCloneOnEditfor details of what this means.If this value is not explicitly set, it defaults to the value of
DataSource.deepCloneOnEdit. This value can be overridden per-field withDataSourceField.deepCloneOnEdit.Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, usingdataPaths.- Returns:
- Current deepCloneOnEdit value. Default value is null
- See Also:
-
setDisableValidation
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- New disableValidation value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
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:
- Current disableValidation value. Default value is null
- See Also:
-
setFetchOperation
operationIdto use when performing fetch operations.- Parameters:
fetchOperation- New fetchOperation value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
getFetchOperation
operationIdto use when performing fetch operations.- Returns:
- Current fetchOperation value. Default value is null
- See Also:
-
setOperator
What operator should be used to combine sub-criteria from member forms whengetValuesAsCriteria()is called?- Parameters:
operator- New operator value. Default value is "and"- Returns:
ValuesManagerinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getOperator
What operator should be used to combine sub-criteria from member forms whengetValuesAsCriteria()is called?- Returns:
- Current operator value. Default value is "and"
-
setRemoveOperation
operationIdto use when performing remove operations.- Parameters:
removeOperation- New removeOperation value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
getRemoveOperation
operationIdto use when performing remove operations.- Returns:
- Current removeOperation value. Default value is null
- See Also:
-
setSaveOperationType
DefaultDSOperationTypeto be performed whenDynamicForm.saveData()is called. This property is automatically set on a call toDynamicForm.editRecord()orDynamicForm.editNewRecord(), or may be set directly viaDynamicForm.setSaveOperationType().If
saveOperationTypeis 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 defaultDSOperationTypewhenDynamicForm.saveData()is called. Note that this property can also be set by callingDynamicForm.editRecord()orDynamicForm.editNewRecord()- Parameters:
saveOperationType- Operation type to use as a default. Valid values are"add"or"update". Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls
-
getSaveOperationType
DefaultDSOperationTypeto be performed whenDynamicForm.saveData()is called. This property is automatically set on a call toDynamicForm.editRecord()orDynamicForm.editNewRecord(), or may be set directly viaDynamicForm.setSaveOperationType().If
saveOperationTypeis 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
DSOperationTypeto be performed whenDynamicForm.saveData()orsaveData()is called.
Valid options are"add"or"update".If a
DSRequestconfiguration object is passed in containing an explicit operationType this will be returned. Otherwisethis.saveOperationTypewill be returned if set. Note thatsaveOperationTypeis automatically set via calls to data binding methods such asDynamicForm.editNewRecord(), or it may beset explicitly.If no explicit saveOperationType is present, the system will use the following heuristic to determine the save operationType:
- If the form has
no value for the
primaryKey fieldthis method will return "add". The assumption is that this is a new record, and the field will be populated when the record is created, (as with a "sequence" type field). - If,
when the form's values were populated, the form had value for theprimaryKey fieldbut it has subsequently be changed, this method will return "add". In this case the value has been changed, either by the user or programmatically so a different (new) record is assumed. This is determined by looking at theoldValuesfor the form. - If the
primaryKey fieldis editable and a value is now present for the primary key field, but was not present in theoldValuesfor the form, this method will return "add". In this case either no initial values were provided, or a 'sparse' set of values for a new record (with no primary key) were provided to the form and the user has subsequently explicitly entered a new primaryKey field value. - Otherwise this method will return "update". Either the primaryKey field is non editable, or the user has not changed it from its initial value.
- If the form has
no value for the
-
setSuppressValidationErrorCallback
When callingsaveData()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.willHandleErroron the DSRequest. In this case the callback passed in will be fired even if the server returns an error status code.If
suppressValidationErrorCallbackis set to true, if a save attempt returns a validation error code, the user-specified callback will not be fired even ifwillHandleError:truewas 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 earlierNote : This is an advanced setting
- Parameters:
suppressValidationErrorCallback- New suppressValidationErrorCallback value. Default value is false- Returns:
ValuesManagerinstance, for chaining setter calls
-
getSuppressValidationErrorCallback
When callingsaveData()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.willHandleErroron the DSRequest. In this case the callback passed in will be fired even if the server returns an error status code.If
suppressValidationErrorCallbackis set to true, if a save attempt returns a validation error code, the user-specified callback will not be fired even ifwillHandleError:truewas 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- Returns:
- Current suppressValidationErrorCallback value. Default value is false
-
setUpdateOperation
operationIdto use when performing update operations.- Parameters:
updateOperation- New updateOperation value. Default value is null- Returns:
ValuesManagerinstance, for chaining setter calls- See Also:
-
getUpdateOperation
operationIdto use when performing update operations.- Returns:
- Current updateOperation value. Default value is null
- See Also:
-
addMember
Add a new member to this valuesManager. AnyCanvascan be a member of a valuesManager, even components likeLayoutorTabSetthat 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 - seeDataPathfor more details.For components like
DynamicFormandListGrid, 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
DataSourceis 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
Deprecated.As of Smartclient version 13.0, due to the removal of Apache Struts.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. You must pass the appropriate params property in the request properties as required by your server framework.For example:
DSRequest requestProperties = new DSRequest(); Map params = new HashMap(); params.put("CANCEL", "cancel"); requestProperties.setParams(params);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, include the following request properties:DSRequest requestProperties = new DSRequest(); // other request property settings ... requestProperties.setIgnoreTimeout(true); requestProperties.setAttribute("target", null);- Parameters:
requestProperties- additional properties to set on the RPCRequest that will be issued- See Also:
-
checkForValidationErrors
Performs silent validation of the value manager values, likevaluesAreValid(). In contrast tovaluesAreValid(), this method allows checking for server-side errors, and finding out what the errors are.The callback must be passed unless server-side validation is being skipped, and If passed, it always fires, errors or not, firing synchronously if server validation is skipped.
- Parameters:
callback- callback to invoke after validation is complete- Returns:
- null if server-side validation is required, or no errors are present; otherwise, a Map of field names to the associated errors, for those fields that failed validation.
- See Also:
-
checkForValidationErrors
public Map checkForValidationErrors(ValidationStatusCallback callback, boolean skipServerValidation) Performs silent validation of the value manager values, likevaluesAreValid(). In contrast tovaluesAreValid(), this method allows checking for server-side errors, and finding out what the errors are.The callback must be passed unless server-side validation is being skipped, and If passed, it always fires, errors or not, firing synchronously if server validation is skipped.
- Parameters:
callback- callback to invoke after validation is completeskipServerValidation- whether to skip doing server-side validation- Returns:
- null if server-side validation is required, or no errors are present; otherwise, a Map of field names to the associated errors, for those fields that failed validation.
- See Also:
-
clearErrors
public void clearErrors(boolean showErrors) Clears all errors from member forms.- Parameters:
showErrors- If true, clear any visible error messages.- See Also:
-
clearFieldErrors
Clear all validation errors associated with some field in this form- Parameters:
fieldName- field for which errors should be clearedshow- if true, and the field is present in one of our member forms, redraw it to clear any currently visible validation errors- See Also:
-
clearValue
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. -
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 callDynamicForm.setSaveOperationType()to ensure subsequent calls tosaveData()will use anaddrather than anupdateoperation. -
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 callDynamicForm.setSaveOperationType()to ensure subsequent calls tosaveData()will use anaddrather than anupdateoperation.- Parameters:
initialValues- initial set of values for the editor as a map of field names to their corresponding values- See Also:
-
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 callDynamicForm.setSaveOperationType()to ensure subsequent calls tosaveData()will use anaddrather than anupdateoperation.- Parameters:
initialValues- initial set of values for the editor as a map of field names to their corresponding values- See Also:
-
editRecord
Edit an existing record. Updates this editors values to match the values of the record passed in, viasetValues().This method will also call
DynamicForm.setSaveOperationType()to ensure subsequent calls tosaveData()will use anupdaterather than anaddoperation.- Parameters:
record- the record to be edited as a map of field names to their corresponding values- See Also:
-
fetchData
public void fetchData()Retrieve data that matches the provided criteria, and edit the first record returned- See Also:
-
fetchData
- See Also:
-
fetchData
- See Also:
-
fetchData
Retrieve data that matches the provided criteria, and edit the first record returned- Parameters:
criteria- search criteriacallback- callback to invoke on completionrequestProperties- additional properties to set on the DSRequest that will be issued- See Also:
-
filterData
public void filterData()Retrieve data that matches the provided criteria, and edit the first record returned.
Differs fromDynamicForm.fetchData()in that a case insensitive substring match will be performed against the criteria to retrieve the data.- See Also:
-
filterData
- See Also:
-
filterData
- See Also:
-
filterData
Retrieve data that matches the provided criteria, and edit the first record returned.
Differs fromDynamicForm.fetchData()in that a case insensitive substring match will be performed against the criteria to retrieve the data.- Parameters:
criteria- search criteriacallback- callback to invoke on completionrequestProperties- additional properties to set on the DSRequest that will be issued- See Also:
-
getChangedValues
Returns all values within this DynamicForm that have changed sinceDynamicForm.rememberValues()last ran. Note thatDynamicForm.rememberValues()runs on dynamicForm initialization, and with every call toDynamicForm.setValues()so this will typically contain all values the user has explicitly edited since then.- Returns:
- changed values in the form
- See Also:
-
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.
- See Also:
-
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
Returns the set of values last stored byDynamicForm.rememberValues(). Note thatrememberValues()is called automatically byDynamicForm.setValues(), and on form initialization, so this typically contains all values as they were before the user edited them.- Returns:
- old values in the form
- See Also:
-
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 viasetValues().Note that modifying the returned object is not a supported way of adding or modifying values. Instead use
setValue()orsetValues().- Returns:
- a map of the values for this manager
- See Also:
-
getValuesAsAdvancedCriteria
Return an AdvancedCriteria object based on the current set of values within memberForms.Similar to
getValuesAsCriteria(), except the returned criteria object is guaranteed to be an AdvancedCriteria object, even if none of the form's fields has a specifiedFormItem.operator- Returns:
- a
AdvancedCriteriabased on the form's current values - See Also:
-
getValuesAsAdvancedCriteria
Return an AdvancedCriteria object based on the current set of values within memberForms.Similar to
getValuesAsCriteria(), except the returned criteria object is guaranteed to be an AdvancedCriteria object, even if none of the form's fields has a specifiedFormItem.operator- Parameters:
textMatchStyle- If specified the text match style will be used to generate the appropriateoperatorfor per field criteria.- Returns:
- a
AdvancedCriteriabased on the form's current values - See Also:
-
addAsyncValidationReplyHandler
Add a asyncValidationReply handler.Notification fired when an asynchronous validation completes.
- Specified by:
addAsyncValidationReplyHandlerin interfaceHasAsyncValidationReplyHandlers- Parameters:
handler- the asyncValidationReply handler- Returns:
HandlerRegistrationused to remove this handler
-
addHiddenValidationErrorsHandler
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. CallHiddenValidationErrorsEvent.cancel()from withinHiddenValidationErrorsHandler.onHiddenValidationErrors(com.smartgwt.client.widgets.form.events.HiddenValidationErrorsEvent)from this method to suppress that behavior.- Specified by:
addHiddenValidationErrorsHandlerin interfaceHasHiddenValidationErrorsHandlers- Parameters:
handler- the hiddenValidationErrors handler- Returns:
HandlerRegistrationused to remove this handler
-
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:
-
hasFieldErrors
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:
-
isNewRecord
Returns true ifsaveOperationTypeis currently "add". SeesaveOperationType.- Returns:
- whether this form will use an "add" operation when saving
-
isPendingAsyncValidation
Is thisValuesManagerwaiting for an asynchronous validation to complete? This method will return true aftervalidate()is called on a component with server-side validators for some field(s), until the server responds.Note that the notification method
ValuesManager.asyncValidationReply()will be fired when validation completes.- Returns:
- true if this widget has pending asynchronous validations in process
-
itemChanged
Handler fired whenever a change to a FormItem fires itemChanged() on one of the member forms. Fires after that event.- Parameters:
item- the FormItem where the change event occurrednewValue- new value for the FormItem
-
addMemberSynchronizedHandler
Add a memberSynchronized handler.Fires after a member component's values have been synchronized from the ValuesManager's values, upon completion of the
ValuesManager.synchronizeMember()call.- Specified by:
addMemberSynchronizedHandlerin interfaceHasMemberSynchronizedHandlers- Parameters:
handler- the memberSynchronized handler- Returns:
HandlerRegistrationused to remove this handler
-
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 viavaluesManager.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
Remove multiple member forms from this valuesManager.- Parameters:
members- array of forms to remove- See Also:
-
resetValues
public void resetValues()Same asDynamicForm.reset(). -
saveData
public void saveData()Validate and then save the form's current values to theDataSourcethis 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
DSRequestwill be sent, exactly as thoughDataSource.addData()orDataSource.updateData()had been called withthe form's valuesas data. TheDSRequest.operationTypewill be either "update" or "add", depending on the currentDynamicForm.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.hiddenValidationErrors()orValuesManager.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.willHandleErrorvia therequestPropertiesparameter 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 modesandDynamicForm.showErrors()may be a better place to put customizations. - for unrecoverable general errors (eg server is down),
central error handlingin invoked, so consider placing customizations there unless an unrecoverable error should be handled specially by this specific form.
upload field, have a chance to upload the file to the server.- See Also:
- if you are trying to customize display of validation errors, there are several
-
saveData
- See Also:
-
saveData
Validate and then save the form's current values to theDataSourcethis 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
DSRequestwill be sent, exactly as thoughDataSource.addData()orDataSource.updateData()had been called withthe form's valuesas data. TheDSRequest.operationTypewill be either "update" or "add", depending on the currentDynamicForm.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.hiddenValidationErrors()orValuesManager.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.willHandleErrorvia therequestPropertiesparameter 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 modesandDynamicForm.showErrors()may be a better place to put customizations. - for unrecoverable general errors (eg server is down),
central error handlingin invoked, so consider placing customizations there unless an unrecoverable error should be handled specially by this specific form.
upload field, have a chance to upload the file to the server.- Parameters:
callback- callback to invoke on completionrequestProperties- additional properties to set on the DSRequest that will be issued- See Also:
- if you are trying to customize display of validation errors, there are several
-
setValues
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 itemin one of the member forms, and each property value is the value to apply to that form item viaFormItem.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
FormItemfor which a value is not provided will revert to itsdefaultValue. To cause all FormItems to revert to default values, pass null.This method also calls
rememberValues()so that a subsequent later call toresetValues()will revert to the passed values.- Parameters:
values- new set of values for this values manager.
-
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). OtherwiseValuesManager.hiddenValidationErrors()will be fired to allow custom handling of hidden errors.- See Also:
-
submit
public void submit()submit()is automatically called when aSubmitItemin a member form is clicked, or ifsaveOnEnteris 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 ifsubmit()will be callingsaveData(). If you overridesubmit(), you can safely ignore the parameters as Smart GWT framework code does not pass them.- See Also:
-
com.smartgwt.client.widgets.form.ValuesManager#submitValuesDataBound Component Methods
-
submit
- See Also:
-
submit
submit()is automatically called when aSubmitItemin a member form is clicked, or ifsaveOnEnteris 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 ifsubmit()will be callingsaveData(). If you overridesubmit(), 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#submitValuesDataBound Component Methods
-
synchronizeMember
Update the parameter ValuesManager member to reflect the current values held by the ValuesManager. Note, it is not normally necessary to manually synchronize members- Parameters:
member- Member component to synchronize- See Also:
-
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 offautomatic synchronization. -
synchronizeMembersOnDataPath
Update just those of this ValuesManager's members that have the parameterdataPath, to reflect the current values held by the ValuesManager. Note, it is not normally necessary to manually synchronize members- Parameters:
dataPath- dataPath to synchronize- See Also:
-
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.If this form has any fields which require server-side validation (see
Validator.serverCondition) this will also be initialized. Such validation will occur asynchronously. Developers can useisPendingAsyncValidation()andValuesManager.asyncValidationReply()to detect and respond to asynchronous validation.Note that for silent validation,
valuesAreValid()(client-side) andcheckForValidationErrors()(client and server-side) can be used instead.- Returns:
- true if all validation passed
- See Also:
-
valuesAreValid
public boolean valuesAreValid()Method to determine whether the current set of values for this values manager would pass validation by the validators defined in the member forms. This method operates client-side, without contacting the server, running validators on the forms' values and returning a value indicating whether validation was successful.Note that, like
validate(), this method will perform value validation even 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
Unlike
validate()this method will not store the errors on the forms or display them to the user.- Returns:
- Boolean value indicating validation success, or if
returnErrorswas specified, a map of field names to the associated errors, for those fields that failed validation, or null if validation succeeded. - See Also:
-
valuesHaveChanged
Compares the current set of values with the values stored by the call to theDynamicForm.rememberValues()method.rememberValues()runs when the form is initialized and on every call toDynamicForm.setValues(). Returns true if the values have changed, and false otherwise.- Returns:
- true if current values do not match remembered values
- See Also:
-
getById
Retrieve a ValuesManager by it's globalID.- Parameters:
ID- global ID of the ValuesManager- Returns:
- the ValuesManager, or null if not found
-
onInit
protected void 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 byDynamicForm.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#handleHiddenValidationErrorsto
 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
The DataSource that this component should bind to for default fields and for performing
 DataSource requests- Parameters:
dataSource- dataSource Default value is null
-
getDataSource
The DataSource that this component should bind to for default fields and for performingDSRequest.Can be specified as either a DataSource instance or the String ID of a DataSource.
- Returns:
- DataSource
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
setValue
Set the value for some field.- Parameters:
fieldName- Name of the field being updatedvalue- New value.
-
getValueAsString
Return the value as String- Parameters:
fieldName- the field name- Returns:
- the value
-
getValue
Return the value of the field.- Parameters:
fieldName- the field name- Returns:
- the value
-
editSelectedData
Edit the record selected in the specified selection component (typically aListGrid).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 aListGridwhose currently selected record(s) is/are to be edited
-
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). SeegetMemberCanvases()- Returns:
- the members
-
getMemberCanvases
Returns the members of this ValuesManager as an array of Canvas objects. See alsogetMembers()- Returns:
- the members
-
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.- Parameters:
formID- ID of the form to remove from this valuesManager
-
removeMember
-
addMember
Add a new member to this valuesManager. AnyCanvascan be a member of a valuesManager, even components likeLayoutorTabSetthat 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 - seeDataPathfor more details.For components like
DynamicFormandListGrid, 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
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
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 keysshowErrors- If true redraw form to display errors now. Otherwise errors can be displayed by callingshowErrors()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 toDynamicForm.showFieldErrors(java.lang.String)will display the errors for this field.- Parameters:
fieldName- field to apply the new errors toerror- error to apply to the field in questionshowErrors- 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 toDynamicForm.showFieldErrors(java.lang.String)will display the errors for this field.- Parameters:
fieldName- field to apply the new errors toerrors- errors to apply to the field in questionshowErrors- If true this method will fall through to DynamicForm.showFieldErrors() to update the display
-
getFieldErrors
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
Retrieve aFormItemfrom this ValuesManager.Takes a field
'name'orDataType, 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 theDynamicFormclass, 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
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:
HandlerRegistrationused to remove this handler
-
getValuesAsCriteria
Retrieves the combined {@link 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 {@link com.smartgwt.client.widgets.form.ValuesManager#setOperator,operator} is set to
"or"rather than"and", and whether any member forms return AdvancedCriteria.Note that developers can also use
DataSource.combineCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)to combine sub-criteria from various sources, including member forms of a ValuesManager, into a combined criteria object.- Returns:
- the criteria
-
getValuesAsRecord
Returns the current set of values for the values manager instance.- Returns:
- a Record object containing the values for this manager
-