The first thing I have to say is:
uicForm3 does not validate your data! This should be done on the server.
Certainly it is possible to validate your data on the client but as it is necessary to validate on the server no matter if you do so on the client (to avoid any manipulation of the validation process) I do prefer not to validate on the client at all.
Validating the submitted data on the server means that you get back information about the valid state of your data at least if your data is not valid. So what you probably get back from the server is the submitted data and some metadata concerning the valid state of your properties. So instead of getting a simple data object as you would when simply requesting data from the server (as we have seen in the previous examples) you would get a different response that contain metadata.
uicForm3 has defined a structure that contains data and metadata. If you are lucky or can define the output of the data server by yourself you can use the data directly. Otherwise you have to create the appropriate data structure from the server’s data and metadata.
Fortunately the structure of the data/metadata object is very easy to understand and to create.
When you normally provide the form’s data as plain or nested javascript object structure where the properties of this structure conform to the form’s properties, the values of these properties were primitive (string, number boolean) or complex (array) values that are used directly to be populated into the form. We’ve seen that in the previous examples where we used among others the following data structure:
{
"title": "mr",
"firstname": "John",
"lastname": "Lennon",
"birthday": "1940-10-09",
"nationality": "gb",
"bands": [
"The Beatles",
"Plastic Ono Band"
]
}
As the properties contain the values directly, uicForm3 consideres these values as valid. We’ve used this in all previous examples where we did not care about validation.
To make metadata available to uicForm3, the properties must not contain their values directly. Instead they need to contain a value-object that in turn holds at least two mandatory properties: value and valid. value holds the property’s value and valid says if the value was considered valid or not.
According to the previous and the new valid state of any property uicForm3 is calling the onPropertyValidStateChange() callback method and if needed the onFormValidStateChange() callback method. This works pretty much the same as the onPropertyModifiedStateChange() and the onFormModifiedStateChange() callbacks.
Although uicForm3 does not need any further meta data to deal with validation, it is a good idea to provide more data. As long as your value object provides the value and the valid property you can provide any other kind of data within this object. So you could pass error code, error message etc. with that object to not only highlight the invalid properties but also give further information like “The entry must contain at least four characters” to provide a better user experience.
So our code example from above enriched with metadata would look something like that:
{
"title": {
value:"mr",
valid:true
},
"firstname": {
value:"John",
valid:true
},
"lastname": {
value:"",
valid:false
},,
"birthday": {
value:"1940-10-09",
valid:true
},,
"nationality": {
value:"gb",
valid:true
},
"bands": {
value:[
"The Beatles",
"Plastic Ono Band"
],
valid:true
}
}
As I said before, uicForm3 understands both kinds of property value assignments. If a property contains a primitive value or an array than it is a direct assignment, if a property contains an object (with the two mandatory properties) than it is a value object with a non-direct assignment and metadata.
The following example simulates entering the data into the form (therefore using the data-method to change current data) and submitting them. Whenever a property is empty the value is considered as invalid in this example.
As you can see, entering the data into the initially blank form makes the properties’ modified state true. If you leave one or more fields blank and then submit the form these properties would be considered as invalid properties. As you can see the resulting data/metadata response now contains value objects instead of values.
If the returned data is not valid at all you should pass the data as current data to the form because your form still contains unsaved data. uicForm3 will recognize the valid state of every property and fire the onPropertyValidStateChanged method and if needed the onFormValidStateChanged method.
If your data is valid at all you should pass the response data from the server as initial data to the form indicating that this data represents a saved recordset (as this is done on button “submit and stay”). Alternatively you could dismiss the valid data and clear the form to prepare it for a new data entry (as this is done on button “submit and clear”).
As you can pass value objects instead of “simple” values to individual properties you can also perform a server-side validation on the fly where the data of a property is send to server each time it is modified. Try it!