|
|
Using custom fields it is possible to extend some of the tables in WebsydianExpress. When a custom field is defined various properties can be set including functions to convert between an internal and external format and a validation function.
For more information about custom fields please look in Custom Fields.
The rest of this document describes how to develop custom field functions in Plex.
In some cases it might be desirable to use different formats for a custom field for when the custom field is displayed for the user, and when the custom field is stored in the database.
A common example is a date value. If the date value must be used by other programs, then the preferred format might be yyyymmdd (without any separators), but when the date is displayed for the user the format should be mm/dd/yyyy.
In most cases these functions comes in pairs; that is when you develop an input conversion function for a custom field then you will also need a corresponding output format function.
To convert the input value create a function that inherits from WSYAPI/CustomFieldFormatValueForInput. The function has the following interface:
| Field | Variable | ...as | Description |
|---|---|---|---|
| APIFields.Value | Input | Dual | When called this field contains the value entered by the user.
When the function terminates the field should contain the converted value that will be written to the database. |
If a validation function is defined for the custom field, then the input conversion function will only be called if the validation succeeds.
The file name for the function is used when registering the function in the WebsydianExpress administration interface. See more in Custom Field Functions.
To format an output value create a function that inherits from WSYAPI/CustomFieldFormatValueForOutput. The function has the following interface:
| Field | Variable | ...as | Description |
|---|---|---|---|
| APIFields.Value | Input | Dual | When called this field contains the value read from the
database.
When the function terminates the field should contain the formatted value that will be displayed on the web page. |
The file name for the function is used when registering the function in the WebsydianExpress administration interface. See more in Custom Field Functions.
The following conversion functions are supplied with the WebsydianExpress runtime, so they can be used when creating custom fields, but are also defined in the WSYAPI model.
| Input conversion | Output format | Description |
|---|---|---|
| CustomFieldFunctions.Date8Input | CustomFieldFunctions.Date8Output | Displays the date as specified by the WebsydianExpress configuration, but stores the date as a date8 value. |
| CustomFieldFunctions.DateISOInput | CustomFieldFunctions.DateISOOutput | Displays the date as specified by the WebsydianExpress configuration, but stores the date as a dateISO value. |
| CustomFieldFunctions.PriceInput | CustomFieldFunctions.PriceOutput | Displays the numeric value formatted with 2 decimals. |
In many cases you need to validate custom fields before they are written to the database; e.g. that a date values does contain a valid date.
To create a validation function inherit from WSYAPI/CustomFieldValidateValue. The function has the following interface:
| Field | Variable | ...as | Description |
|---|---|---|---|
| APIFields.Value | Input | Input | Contains the value that must be validated. |
| APIFields.CustomFieldValidationError | Output | Output | Used to specify an error message if the validation fails. If no error message is specified the WebsydianExpress runtime will generate a generic error message. |
The validation function is only called if the user enters a value in the custom field.
If the validation fails set *Returning status to a value different from *Successful.
The file name for the function is used when registering the function in the WebsydianExpress administration interface. See more in Custom Field Functions.
The following validation functions are supplied with the WebsydianExpress runtime, so they can be used when creating custom fields, but are also defined in the WSYAPI model.
| Validation function | Description |
|---|---|
| CustomFieldFunctions.DateValidate | Validates that the entered value is a valid date as specified by the WebsydianExpress configuration. |
| CustomFieldFunctions.PriceValidate | Validates that the entered value is a valid numeric value. |
Online documentation - WebsydianExpress v3.5