com.smartgwt.client.widgets.form
Class ValuesManager

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

public class ValuesManager
extends BaseClass

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 setValues(java.util.Map) 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, id, scClassName
 
Constructor Summary
ValuesManager()
           
ValuesManager(JavaScriptObject jsObj)
           
 
Method Summary
 void addMember(DynamicForm member)
          Add a new member form to this valuesManager.
 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(String fieldName, boolean show)
          Clear all validation errors associated with some field in this form
 void clearValue(String fieldName)
          Clear the value for some field.
 void clearValues()
          Clear out all the values managed by this values manager.
 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(Map 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()
           
 void fetchData(Criteria criteria)
          Retrieve data that matches the provided criteria, and edit the first record returned
 void fetchData(Criteria criteria, DSCallback callback)
          Retrieve data that matches the provided criteria, and edit the first record returned
 void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
          Retrieve data that matches the provided criteria, and edit the first record returned
 void filterData(Criteria criteria)
          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, DSCallback callback)
          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, 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.
 DataSource getDataSource()
          The DataSource that this component should bind to for default fields and for performing DSRequest.
 Boolean getDisableValidation()
          If set to true, client-side validators will not run on the form when validate() is called.
 Map getErrors()
          Returns the set of errors for this valuesManager.
 String[] getFieldErrors(String fieldName)
          Returns any validation errors for some field in this valuesManager.
 FormItem getItem(String itemID)
          Retrieve a FormItem from this ValuesManager.
 DynamicForm[] getMembers()
          Returns an array of members in this ValuesManager.
static ValuesManager getOrCreateRef(JavaScriptObject jsObj)
           
 DSOperationType getSaveOperationType()
          Default DSOperationType to be performed when DynamicForm.saveData() is called.
 String getUnknownErrorMessage()
          The error message for a failed validator that does not specify its own errorMessage.
 String getValueAsString(String fieldName)
          Return the value as String
 Map getValues()
          Returns the current set of values for the values manager instance.
 Boolean hasErrors()
          Are there any errors associated with any fields in this valuesManager?
 Boolean hasFieldErrors(String fieldName)
          Are there any errors associated with a field in this valuesManager?
 Boolean isNewRecord()
          Returns true if saveOperationType is currently "add".
 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(String formID)
          Remove a member form from this valuesManager, so its values are no longer managed by this instance.
 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)
          Validate and then save the form's current values to the DataSource this form is bound to.
 void saveData(DSCallback callback, DSRequest requestProperties)
          Validate and then save the form's current values to the DataSource this form is bound to.
 void setDataSource(DataSource dataSource)
          The DataSource that this component should bind to for default fields and for performing DataSource requests
 void setDisableValidation(Boolean disableValidation)
          If set to true, client-side validators will not run on the form when validate() is called.
 void setErrors(Map errors, boolean showErrors)
          Setter for validation errors on this form.
 void setFieldErrors(String fieldName, String[] errors, boolean showErrors)
          Set field validation errors for some field.
 void setFieldErrors(String fieldName, String error, boolean showErrors)
          Set field validation error for some field.
 void setSaveOperationType(DSOperationType saveOperationType)
          Default DSOperationType to be performed when DynamicForm.saveData() is called.
 void setUnknownErrorMessage(String unknownErrorMessage)
          The error message for a failed validator that does not specify its own errorMessage.
 void setValue(String fieldName, boolean value)
          Set the value for some field.
 void setValue(String fieldName, DataClass value)
          Set the value for some field.
 void setValue(String fieldName, DataClass[] value)
          Set the value for some field.
 void setValue(String fieldName, double value)
          Set the value for some field.
 void setValue(String fieldName, JavaScriptObject value)
          Set the value for some field.
 void setValue(String fieldName, Map value)
          Set the value for some field.
 void setValue(String fieldName, Record value)
          Set the value for some field.
 void setValue(String fieldName, Record[] value)
          Set the value for some field.
 void setValue(String fieldName, String value)
          Set the value for some field.
 void setValues(Map values)
          Set the values for this values manager.
 void showErrors()
          Method to explicitly show the latest set of validation errors present on this ValuesManager.
Will redraw all member forms to display (or clear) currently visible errors, and fire com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors to allow custom handling of hidden errors.
 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 included in the form is clicked, or, if saveOnEnter is set, when the "Enter" key is pressed in a text input.
 void submit(DSCallback callback)
          submit() is automatically called when a SubmitItem included in the form is clicked, or, if saveOnEnter is set, when the "Enter" key is pressed in a text input.
 void submit(DSCallback callback, DSRequest requestProperties)
          submit() is automatically called when a SubmitItem included in the form is clicked, or, if saveOnEnter is set, when the "Enter" key is pressed in a text input.
 Boolean validate()
          Validate the current set of values for this values manager against validators defined in the member forms.
 Boolean valuesHaveChanged()
          Compares the current set of values with the values stored by the call to the rememberValues() method.
 
Methods inherited from class com.smartgwt.client.core.BaseClass
destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getConfig, getHandlerCount, getID, getJsObj, getOrCreateJsObj, getRef, isCreated, onInit, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, setProperty, setProperty, setProperty, setProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ValuesManager

public ValuesManager()

ValuesManager

public ValuesManager(JavaScriptObject jsObj)
Method Detail

getOrCreateRef

public static ValuesManager getOrCreateRef(JavaScriptObject jsObj)

create

public JavaScriptObject create()
Specified by:
create in class BaseClass

setUnknownErrorMessage

public void setUnknownErrorMessage(String unknownErrorMessage)
The error message for a failed validator that does not specify its own errorMessage.

Parameters:
unknownErrorMessage - unknownErrorMessage Default value is "Invalid value"

getUnknownErrorMessage

public String getUnknownErrorMessage()
The error message for a failed validator that does not specify its own errorMessage.

Returns:
String

setDisableValidation

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

Note : This is an advanced setting

Parameters:
disableValidation - disableValidation Default value is null

getDisableValidation

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

Returns:
Boolean

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(com.smartgwt.client.data.Record) or DynamicForm.editNewRecord(), or may be set directly via DynamicForm.setSaveOperationType(com.smartgwt.client.types.DSOperationType).

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. Setter for the default DSOperationType when DynamicForm.saveData() is called. Note that this property can also be set by calling DynamicForm.editRecord(com.smartgwt.client.data.Record) 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(com.smartgwt.client.data.Record) or DynamicForm.editNewRecord(), or may be set directly via DynamicForm.setSaveOperationType(com.smartgwt.client.types.DSOperationType).

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.


validate

public 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 com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors will be called. This can occur if:
- A datasource field has no correspending 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

clearErrors

public void clearErrors(boolean showErrors)
Clears all errors from member forms.

Parameters:
showErrors - If true, clear any visible error messages.

clearFieldErrors

public void clearFieldErrors(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

hasErrors

public Boolean hasErrors()
Are there any errors associated with any fields in this valuesManager?

Returns:
returns true if there are any oustanding validation errors, false otherwise.

hasFieldErrors

public Boolean hasFieldErrors(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 oustanding validation errors, false otherwise.

showErrors

public void showErrors()
Method to explicitly show the latest set of validation errors present on this ValuesManager.
Will redraw all member forms to display (or clear) currently visible errors, and fire com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors to allow custom handling of hidden errors.


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 com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors will be fired to allow custom handling of hidden errors.


clearValues

public void clearValues()
Clear out all the values managed by this values manager.


resetValues

public void resetValues()
Same as DynamicForm.reset().


valuesHaveChanged

public Boolean valuesHaveChanged()
Compares the current set of values with the values stored by the call to the rememberValues() method. Returns true if the values have changed, and false otherwise.

Returns:
true if current values do not match remembered values

clearValue

public void clearValue(String fieldName)
Clear the value for some field.

Parameters:
fieldName - Which field to set the value for

isNewRecord

public Boolean isNewRecord()
Returns true if saveOperationType is currently "add". See saveOperationType.

Returns:
whether this form will use an "add" operation when saving

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});
 


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

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(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(String fieldName,
                     String value)
Set the value for some field.

Parameters:
fieldName - Name of the field being updated
value - New value.

setValue

public void setValue(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(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(String fieldName,
                     JavaScriptObject value)
Set the value for some field.

Parameters:
fieldName - Name of the field being updated
value - New value.

setValue

public void setValue(String fieldName,
                     Map value)
Set the value for some field.

Parameters:
fieldName - Name of the field being updated
value - New value.

setValue

public void setValue(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(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(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(String fieldName,
                     DataClass[] value)
Set the value for some field.

Parameters:
fieldName - Name of the field being updated
value - New value.

getValueAsString

public String getValueAsString(String fieldName)
Return the value as String

Returns:
the value

getValues

public 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

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

addMember

public void addMember(DynamicForm member)
Add a new member form to this valuesManager. This form's values will subsequently be available through this valuesManager.
Note on pre-existant values: If the valuesManager has a value specified for some field, for which the member form has an item, this value will be applied to the member form. This is true whether the item has a value or not.
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 - form (or ID of form) to add to this valuesManager as a member.

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 to remove from this valuesManager

getMembers

public DynamicForm[] getMembers()
Returns an array of members in this ValuesManager.

Returns:
the members

removeMember

public void removeMember(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

fetchData

public void fetchData()

fetchData

public void fetchData(Criteria criteria)
Retrieve data that matches the provided criteria, and edit the first record returned

Parameters:
criteria - search criteria

fetchData

public void fetchData(Criteria criteria,
                      DSCallback callback)
Retrieve data that matches the provided criteria, and edit the first record returned

Parameters:
criteria - search criteria
callback - callback to invoke on completion

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

filterData

public void filterData(Criteria criteria)
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

filterData

public void filterData(Criteria criteria,
                       DSCallback callback)
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

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

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(com.smartgwt.client.data.Record) or DataSource.updateData(com.smartgwt.client.data.Record) had been called with DynamicForm.getValues() as data. The operationType will be either "update" or "add" depending on whether values were initially provided via editRecord() or editNew().

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

validationURL can be set to do validation against a different URL from where the form will ultimately save, as part of an incremental upgrade strategy for Struts and Struts-like applications.


saveData

public void saveData(DSCallback callback)
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(com.smartgwt.client.data.Record) or DataSource.updateData(com.smartgwt.client.data.Record) had been called with DynamicForm.getValues() as data. The operationType will be either "update" or "add" depending on whether values were initially provided via editRecord() or editNew().

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

validationURL can be set to do validation against a different URL from where the form will ultimately save, as part of an incremental upgrade strategy for Struts and Struts-like applications.

Parameters:
callback - callback to invoke on completion

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(com.smartgwt.client.data.Record) or DataSource.updateData(com.smartgwt.client.data.Record) had been called with DynamicForm.getValues() as data. The operationType will be either "update" or "add" depending on whether values were initially provided via editRecord() or editNew().

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

validationURL can be set to do validation against a different URL from where the form will ultimately save, as part of an incremental upgrade strategy for Struts and Struts-like applications.

Parameters:
callback - callback to invoke on completion
requestProperties - additional properties to set on the DSRequest that will be issued

submit

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

If com.smartgwt.client.widgets.form.DynamicForm#submitValues exists, it will be called, then immediately return.

Otherwise, default behavior varies based on canSubmit: if canSubmit is false, DynamicForm.saveData() will be called to handle saving via Smart GWT databinding.

If canSubmit is true, the form will be submitted like an ordinary HTML form via DynamicForm.submitForm().

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

public void submit(DSCallback callback)
submit() is automatically called when a SubmitItem included in the form is clicked, or, if saveOnEnter is set, when the "Enter" key is pressed in a text input. Submit can also be manually called.

If com.smartgwt.client.widgets.form.DynamicForm#submitValues exists, it will be called, then immediately return.

Otherwise, default behavior varies based on canSubmit: if canSubmit is false, DynamicForm.saveData() will be called to handle saving via Smart GWT databinding.

If canSubmit is true, the form will be submitted like an ordinary HTML form via DynamicForm.submitForm().

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. [Ignored if this.canSubmit is true]

submit

public void submit(DSCallback callback,
                   DSRequest requestProperties)
submit() is automatically called when a SubmitItem included in the form is clicked, or, if saveOnEnter is set, when the "Enter" key is pressed in a text input. Submit can also be manually called.

If com.smartgwt.client.widgets.form.DynamicForm#submitValues exists, it will be called, then immediately return.

Otherwise, default behavior varies based on canSubmit: if canSubmit is false, DynamicForm.saveData() will be called to handle saving via Smart GWT databinding.

If canSubmit is true, the form will be submitted like an ordinary HTML form via DynamicForm.submitForm().

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. [Ignored if this.canSubmit is true]
requestProperties - additional properties to set on the DSRequest that will be issued [Ignored if this.canSubmit is true]

rememberValues

public 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(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 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(String fieldName,
                           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(String fieldName,
                           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 String[] getFieldErrors(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(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.