Data In- and Output

Intro

There are four ways to populate the form with data:

  1. Providing a javascript object to use as initial data for the whole form
  2. Providing a javascript object to use as current data for the whole form
  3. Providing a single value for an individual property to use as initial value
  4. Providing a single value for an individual property to use as current value

Providing data for the form and retrieving data from the form

This example uses:

  • setting data
    • initData(data) (equals populateRecord(data) and populate(data, true))
    • data(data) (equals populateData(data) and populate(data, false))
  • getting data
    • initData()
    • data()
    • modifiedData()

The following example shows how to populate the whole form with data from javascript. The data is provided as a javascript object with a simple (string number, boolean) or complex (array) value per property.
As you can see, providing the data as initial data does not lead in a modified state of any property or the form although you are changing the content of the form fields. This is because we use our existing html structure to present a new untouched record (that currently comes from a pre-defined javascript object but might be the result of an ajax call when requesting a new record).
If we choose to insert the javascript data as current data this will leave the initial data untouched and therefore lead in a a modified state of the properties and the form. You would hardly need to pass a dataset as current data (by using the data-method) to the form. Normally you would want to present new recordsets as initial data (by using the initData-method) and let the user modify these records. Only if you want to provide some template-data or want to offer a way to restore defaults for certain kind of records it makes sense to override a complete recordset with a new set of data and therefore using the data()-method.
To show the data that are passed to the form, I put their json-representation just beneath the form. Please keep in mind that uicForm3 expects real javascript and not a json-string.

If you are editing the field manually after setting initial data you again get your “modified” indicators and the reset buttons. You can go back to the recent initial values per property by clicking on their reset buttons just as if you had loaded the complete form with pre-filled.

If you are passing values as current data to the form it is like entering these data manually. The initial values remain but the current values do change. Therefore you will get the modified indicators showing you that you are still on the same record but with modified data.

If you are skipping through the records until you reach “Ron Wood” you will see that the javascript object holds two values in the array for the property “band” (“The Faces”, “Rolling Stones”) but the form does not contain a checkbox for “The Faces”. uicForm3 assings the “Rolling Stones” but ignores “The Faces”. If you were in debug-mode you would get a notification in the console that some values of the property “band” could not have been assigned. It is up to you to ensure that the form provides appropriate form elements to represent all possible data that can be provided.

Setting data for individual properties / reset, wipe, clear

This example uses:

  • setting data
    • initVal(key,va)
    • val(key, val)
  • getting data
    • initVal(key)
    • val(key)
  • others
    • resetFields()
    • wipe()
    • clear()

The following example shows how to set data for individual properties. I think you’ll never need to set the initial value of an individual property as this would mean to to change the current recordset partially and pretend that the now modified dataset equals the initial recordset what simply is not true. But sometimes it can be useful to change a properties current value programmatically, i. e. when this modification should be triggered by another user action. For this it is important to use the uicForm3s val()-method otherwise uicForm3 would not fire any event and the state is not correctly represented.

The resetFields()-method resets all properties (and therefore all fields) to it’s initial values.
The wipe()-method clears all property’s current values and empties all form fields. You should do this if you want to wipe current data from the form to make a clean start for updating the current recordset.
The clear()-method clears all property’s initial values and empties all form fields. If you want to prepare your HTML form for inserting a new recordset you should do this.