Custom Fields
Overview
Custom fields are used to extend the core tables in Websydian Express with additional information. E.g. if you want to assign a phone number field to all users, then create a custom field named Phone number and assign it to the user table. The field will then be visible through the administration interface when maintaining users.
Currently only the user and role entities can be extended with custom fields.
Basic information
Custom fields
Each custom field has some properties which determines the appearance of the field when it is displayed in the administration interface.
| Custom field property | Description |
|---|---|
| Extending | The extended entity. Currently the role and user entities can be extended. |
| Name | Used by the custom field APIs when setting and retrieving custom field values. The name must be unique within the extended entity. |
| Label | The label for the custom field when displayed in the web administration interface. |
| Length of input field | Determines the length of the text box control when the custom field appears as an input field in the administration interface. |
| Mode | Can be either Edit or ReadOnly. Read only custom fields can only be modified programmatically whereas an edit custom field also can be modified through the administration interface. |
| Max length of entered value | The maximum length of the value stored in the custom field. |
| Optionality | Can be Optional or Mandatory. For mandatory custom fields a value must be specified when the field is used on an insert or update page for the entity associated with the field. |
Custom field functions
Custom field functions is used to specify the display format or validation functionality for custom fields.
Input/output format
In some cases it is necessary to control the format of a custom field when displaying values on a page. To support this it is possible to specify input and output format functions for a custom field.
E.g. if you have created a custom field containing a date value in the format yyyy-mm-dd, then in most cases you would like to format the date according to the users local settings. This can be done by creating a output format function and specify it for the custom field.
If the date is an edit field, then you must also specify an input format function which converts the date value from the external format to the internal format.
For information on how to create a custom field function please read Creating custom field functions.
Validation
In many cases it is useful to validate a custom field value entered by a user before the value is written to the database so the consistency and integrity of the database is preserved. To accomplish this it is possible to define a validation function for a custom field.
The validation function is called as part of the validation of the other fields in the extended entity. If the validation fails none of the fields are updated and a standard error message will be returned to the user. Alternatively the validation function can return a more descriptive error message, which then will be returned to the end user instead of the standard error message.
The validation function is only called when a value is entered by a user in the administration interface, but not when custom field values are set using the custom field API functions.
Access custom field values
There are two ways to access custom field values.
- By using the administration interface.
- Using the custom field API functions to query and update custom field values.
Administration interface
When extending an entity with a custom field the custom field will appear on the maintenance pages for that entity. That is the insert, update, and delete pages. Thus the custom field is maintained as part of the entity which the custom field belongs to.
Programmatically
The custom field API functions can be used to get and set custom field values, but there are also some more advanced API functions as retrieving all defined custom fields and their values for a specific instance (record) in an entity.
More information can be found here:
Predefined custom field functions
For an overview of the predefined custom field functions that is included with Websydian Express please look in the tables below.
Input/output format
| Description | Output | Input | Comment |
|---|---|---|---|
| Date 8 to formatted date | WSD82FD | WSFD2D8 | Stores the date in the format YYYYMMDD, but when displayed on pages the date will be formatted as defined by the Websydian Express configuration(1). |
| Date ISO to formatted date | WSDI2FD | WSFD2DI | Stores the date in the format YYYY-MM-DD(2), but when displayed on pages the date will be formatted as defined by the Websydian Express configuration(1). |
| Format price | WSFORMP | WSPARSP | Formats a numeric field with 2 decimals using the decimal seperator defined by the Websydian Express configuration(1). |
(1) The format of date values are specified during the Websydian Express installation.
(2) On an iSeries installation the format will be the same as for Date8 fields (YYYYMMDD)
Validation
| Description | Function | Comment |
|---|---|---|
| Validate formatted date | WSVALFD | Validates that the date is a valid date. The format of the date is defined by the Websydian Express configuration(1). |
| Validate price | WSVALP | Validates that the number is a valid number; e.g. does not contain any non-numeric characters except for the negative sign and the decimal separator. |
(1) The format of date values are specified during the Websydian Express installation.
Related information
- Creating custom field functions
- Find information on how to create custom field functions using Plex Developer.
- Single sign-on example
- This example uses a custom field to implement single sign-on functionality in Websydian Express.