|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.smartgwt.client.core.BaseClass
com.smartgwt.client.widgets.form.ValuesManager
public class ValuesManager
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 |
---|
public ValuesManager()
public ValuesManager(JavaScriptObject jsObj)
Method Detail |
---|
public static ValuesManager getOrCreateRef(JavaScriptObject jsObj)
public JavaScriptObject create()
create
in class BaseClass
public void setUnknownErrorMessage(String unknownErrorMessage)
unknownErrorMessage
- unknownErrorMessage Default value is "Invalid value"public String getUnknownErrorMessage()
public void setDisableValidation(Boolean disableValidation)
Note : This is an advanced setting
disableValidation
- disableValidation Default value is nullpublic Boolean getDisableValidation()
public void setSaveOperationType(DSOperationType saveOperationType)
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()
saveOperationType
- Operation type to use as a default. Valid values are "add"
or "update"
.. Default value is nullpublic DSOperationType getSaveOperationType()
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.
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.
public Boolean validate()
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.
public void clearErrors(boolean showErrors)
showErrors
- If true, clear any visible error messages.public void clearFieldErrors(String fieldName, boolean show)
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 errorspublic Boolean hasErrors()
public Boolean hasFieldErrors(String fieldName)
fieldName
- field to check for errors
public void showErrors()
com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors
to allow custom handling of hidden errors.
public void showFieldErrors()
com.smartgwt.client.widgets.form.ValuesManager#handleHiddenValidationErrors
will be fired
to allow custom handling of hidden errors.
public void clearValues()
public void resetValues()
DynamicForm.reset()
.
public Boolean valuesHaveChanged()
rememberValues()
method. Returns true if the values have changed, and false otherwise.
public void clearValue(String fieldName)
fieldName
- Which field to set the value forpublic Boolean isNewRecord()
saveOperationType
is
currently "add". See saveOperationType
.
public void cancel()
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});
public void cancel(DSRequest requestProperties)
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});
requestProperties
- additional properties to set on the RPCRequest that will be issuedpublic void setDataSource(DataSource dataSource)
dataSource
- dataSource Default value is nullpublic DataSource getDataSource()
DSRequest
. Can be specified as either a DataSource instance or the String ID of a DataSource.
public void setValues(Map values)
values
- the valuespublic void setValue(String fieldName, String value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, double value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, boolean value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, JavaScriptObject value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, Map value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, Record value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, DataClass value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, Record[] value)
fieldName
- Name of the field being updatedvalue
- New value.public void setValue(String fieldName, DataClass[] value)
fieldName
- Name of the field being updatedvalue
- New value.public String getValueAsString(String fieldName)
public Map getValues()
public void editSelectedData(ListGrid selectionComponent)
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.
selectionComponent
- the ListGrid or ID of a ListGrid
whose
currently selected record(s) is/are to be editedpublic void editRecord(Record record)
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.
record
- the record to be edited as a map of field names to their corresponding valuespublic void editNewRecord()
public void editNewRecord(Map initialValues)
initialValues
- initial set of values for the editor as a map of field names to their corresponding valuespublic void addMember(DynamicForm member)
member
- form (or ID of form) to add to this valuesManager as a
member.public void removeMember(DynamicForm member)
member
- form to remove from this valuesManagerpublic DynamicForm[] getMembers()
public void removeMember(String formID)
formID
- ID of the form to remove from this valuesManagerpublic void fetchData()
public void fetchData(Criteria criteria)
criteria
- search criteriapublic void fetchData(Criteria criteria, DSCallback callback)
criteria
- search criteriacallback
- callback to invoke on completionpublic void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest
that will be issuedpublic void filterData(Criteria criteria)
DynamicForm.fetchData()
in that a case insensitive substring match will be
performed against the criteria to retrieve the data.
criteria
- search criteriapublic void filterData(Criteria criteria, DSCallback callback)
DynamicForm.fetchData()
in that a case insensitive substring match will be
performed against the criteria to retrieve the data.
criteria
- search criteriacallback
- callback to invoke on completionpublic void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
DynamicForm.fetchData()
in that a case insensitive substring match will be
performed against the criteria to retrieve the data.
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest
that will be issuedpublic void saveData()
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.
public void saveData(DSCallback callback)
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.
callback
- callback to invoke on completionpublic void saveData(DSCallback callback, DSRequest requestProperties)
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.
callback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest
that will be issuedpublic 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.
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.
callback
- callback to invoke on completion. [Ignored if
this.canSubmit is true]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.
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]public JavaScriptObject rememberValues()
public void setErrors(Map errors, boolean showErrors)
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 calling
showErrors()
Note: When the errors are shown, handleHiddenValidationErrors() will be fired for errors
on hidden fields, or with no associated formItem.public Map getErrors()
public void setFieldErrors(String fieldName, String error, boolean showErrors)
DynamicForm.showFieldErrors(java.lang.String)
will display the errors for this field.
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 displaypublic void setFieldErrors(String fieldName, String[] errors, boolean showErrors)
DynamicForm.showFieldErrors(java.lang.String)
will display the errors for this field.
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 displaypublic String[] getFieldErrors(String fieldName)
fieldName
- the field name
public FormItem getItem(String itemID)
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
itemID
- item fieldName or dataPath identifier
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |