Create Custom Field Functions

• Introduction

• Conversion functions

  • Convert input value

  • Format output value

  • Examples

• Validation function

  • Examples

Introduction

Using custom fields it is possible to extend some of the tables in Websydian Express. 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.

Conversion functions

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.

Convert input value

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.

The file name for the function is used when registering the function in the Websydian Express administration interface. See more in Custom Field Functions.

Format output value

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 Websydian Express administration interface. See more in Custom Field Functions.

Examples

The following conversion functions are supplied with the Websydian Express 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 Websydian Express configuration, but stores the date as a date8 value.
CustomFieldFunctions.DateISOInput	CustomFieldFunctions.DateISOOutput	Displays the date as specified by the Websydian Express configuration, but stores the date as a dateISO value.
CustomFieldFunctions.PriceInput	CustomFieldFunctions.PriceOutput	Displays the numeric value formatted with 2 decimals.

Validation function

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 Websydian Express runtime will generate a generic error message.

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 Websydian Express administration interface. See more in Custom Field Functions.

Examples

The following validation functions are supplied with the Websydian Express 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 Websydian Express configuration.
CustomFieldFunctions.PriceValidate	Validates that the entered value is a valid numeric value.