IDataBoundProps<T>

Interface

The IDataBoundProps<T> interface is used to define the properties that are required for data binding in a generic way. This interface is designed to work with objects that may include validation errors and allows for transforming data between the model and view layers.

Data access

In a databound component data will be read and written using the props object and property.

Example

Suppose we have a form with employee data:

First we define the interface:

interface IEmployee {
  id: number
  fullname: string
  dob?: string
  salary: number
}

Then we create the form variable as reactive:

const form = reactive<IEmployee>({ 
    id: 1, 
    fullname: 'Picasso Pablo', 
    dob: null, 
    salary: 3650.0 
})

Now we are going to use the property (or attribute) fullname for editing in a TextBox component (as it implements the IDataBoundProps<T> interface).

<template>
<TextBox :object="form" 
          property="fullname" />
</template>

This way each time the component modifies the data (i.e. by an input or a changed event) the form will also change and trigger an update due to its reactivity. In the above example, as fullname is just a string, it doesn't need conversion at all. For that reason MVVM methods are not there but that's not always the case. When dealing with numbers or dates (that should be localized or changed to match what's expected on the backend) they need some sort of transformation or conversion. That is when the MVVM (model-to-view and view-to-model) strategy comes into place.

Data transform/conversion

Generally data consumed and sent by APIs are in JSON format (or any other). Some values come in a certain format that is supposed to be valid (as it is directly got from the backend) but when those values are modified on the frontend, we need methods that transform the data back and forth so it remains valid.

Example

In this example we have the next JSON that is an employee record returned by the backend:

{
  "name": "Parker Peter",
  "height": 1.3,
  "age": 17,
  "dob": "2000-07-02",
  "address": null
}

Types are:

• name: string
• height: float
• age: integer
• dob: date in ISO format
• address: nullable string

When we edit that data, it is important that the format and data structure matches the original.

For instance, the dob (date of birth) attribute should be a valid ISO date, for that is the format handled by the backend code. The thing is that when we need to edit it, it should display in the current locale's format. Also we wouldn't want to end with something like this:

{
  "name": "Parker Peter",
  "height": "1.3",
  "age": "17",
  "dob": "02/07/2024",
  "address": null
}

Note that the height attribute was converted to a string and so was age. Not to mention that dob MUST BE converted to ISO format before sending to the backend (such as when creating or modifying data).

The IDataBoundProps interface has two methods for converting that data back and forth so each databound component MUST implement it in order to maintain data consistency.

Type Parameters

• T: The type of the object to which the properties belong.

Properties

object

• Type: T & DataTypes.IWithValidationError
• Description: The object that contains the property to be bound. This object can include validation error information via the IWithValidationError interface.

property

• Type: keyof T
• Description: The property of the object that is being bound. This is a key from the object of type T.

modelToView

• Type: (value: any) => any
• Optional: Yes
• Description: A function that transforms the value from the model layer to the view layer. This function takes a value of any type and returns a transformed value that will be used in the view.
• Example: to transform "2007-09-05" (model value in ISO formato) to 09/05/2007 (view value in english locale format)

viewToModel

• Type: (valueWrapper: DataTypes.ITransformValueInfo) => boolean
• Optional: Yes
• Description: A function that transforms the value from the view layer back to the model layer. It takes a value wrapper of type ITransformValueInfo and returns a boolean indicating whether the transformation was successful.
• Example: following the previous example, to transform "09/05/2007" (view value in english locale format) to 2007-09-05 (model value in ISO format)

INFO

This library has several built-in MVVM converters (for numbers, dates, etc.) but the developer can implement a custom solution too.

nullable

• Type: boolean
• Optional: Yes
• Default: false
• Description: Indicates whether the bound property is nullable. If true, the property can accept null values.

defaultValue

• Type: any
• Optional: Yes
• Description: The default value to be used if the bound property is null or undefined and the component tries to edit the value. The idea is to have a default value to return from null. This value can be of any type.