How To - User-Defined Forms


With version 2 of OES it is now possible to set up multiple entry forms and structure them with user-defined content and layout.

In order to facilitate the flexibility required, some maintenance functions update the structure of the underlying database and, as such, special care should be taken.

To avoid confusion with the facility to specify the column on the form where data is shown, the word 'field' is sometimes used in this manual to describe what are, technically, database columns.

Defining New Fields

OES v2 is delivered with one standard form, for Road Running Races. To accommodate other event types and specialized races, it is to be expected that additional fields will be required to store data from their differing entry forms. Before the form itself can be tackled, it is necessary to add the additional fields to the database.

As the database maintenance functions update the database structure, it is strongly recommended that you set all sites to 'down for maintenance' during the use of the admin functions discussed here.

Database Groups

The data stored in the database for all entries is defined in structured groups called database groups. The data for the standard entry form is defined under the 'Base Group' database group. This group cannot be changed. Further groups can be added and the structure of these groups is under user control. The group itself has no function apart from grouping together additional database fields into logical structures, allowing database restructuring to the made in a single update and for preventing changes to the mandatory 'Base Group' fields.

Database Columns

Within the Database Groups Maintenance in the admin area of the system, you can maintain the underlying database fields using the 'Edit Database Columns' action listed to the right of all database groups.

The following information can be maintained for each database column:-

Name: This is the name of the underlying database column that will be created. Although it isn't strictly necessary, it is recommended that you use names that begin with an alphabetic character and that do not contain special characters like asterisks or commas etc. It is the OES convention to use purely lowercase names.

Description: You can enter here free-format text to describe the column. The text has no function and is not part of the database update.

Type: This describes the type or data that will be stored in the underlying database:-

Length: This entry only appears when the 'Text' type is selected and is used to allocate the maximum text length allowed.

Entry/Entrant/Transfer Relevant: These checkboxes are used to determine whether the database column is added to the entries, entrants and transfers tables.
Transfer/Change Persist: These checkboxes display if the database column is marked as not transfer relevant. Normally, if a database column isn't transfer relevant it will get cleared during a transfer or change. These checkboxes can be used to specify that the data in these columns is not cleared during either a change, transfer or both.

Updating the Database

Adding and updating user-defined database columns is carried out using the Database Column Maintenance through the relevant Database Group. The underlying database is not updated immediately, it is only updated when the 'Enable' action is used (within the Database Group Maintenance). Hence a whole Database Group of database columns is enabled in one step and the number of atomic database updates is kept to a minimum. Once the database group is enabled, it is only possible to update a very small subset of the information on database columns and it is not possible to remove or reverse the database update.

Structure of a Form

Forms are constructed from nine different types of form fields: Section Headings, Text Boxes, Free-Format Text, Check Boxes, Radio Buttons, a Race List, Dates, Date and Time and, finally, Charge Summary Amounts. In addition to describing the content of the form itself, each element has additional attributes associated with it that describe:- A full description of these attributes appears in the Validation and Formatting, Layout and Control sections later in this document.

Form Field Types

These are described below (the internal name of each element - which corresponds to the 'Type' shown on the Form Field List page - is shown in brackets):-

Validation and Formatting

Simple validation rules can be applied to text and radio button elements on a form (dates and times are obviously validated as well, but this validation is not under administrator control). Text and radio buttons can be defined as mandatory by ticking the 'Mandatory' attribute on the form field.

Valid values for numeric fields can be defined using the 'Minimum/Maximum Value' settings.

The values associated with radio buttons are defined in the 'Values' attribute of the form field. Individual radio buttons are defined separated by a semi-colon. Each radio button definition is made up of two elements separated by a colon. The first element is the caption that will display on the form, the second element is the data that will be stored in the database when that radio button is selected.

Optionally, the text entered into text boxes can be forced into a suitable format using the 'Format' attribute on the form field. This specifies whether the text will be forced to 'All Uppercase', 'All Lowercase' or 'Proper Name' (meaning the first character of every word is capitalised and all other characters are lowercase).

In addition to the user-defined validation, there are a number of built-in validations which occur and which are not under the control of the administrator.


The layout of the form shown on the entry form page is constructed, at run time, from the attributes and entries on the form field database table. There are four form field attributes which directly control the way the form fields are shown on the form:-


There are some attributes of the form which are dependent on what the entrant selects during online entry. For example, the display of the t-shirt field depends on the configuration of the races chosen by the entrant in the 'Race List', in that it only displays if a selected race has t-shirts enabled. This is controlled by the 'control' attribute. There are currently 19 different control attributes and these are described below:-

Special Functions

Club affiliation and the charging of affiliation fees is controlled by a combination of the affiliation setting on the club table and the race licence number entered on the entry form. If a club is marked as affiliated, the affiliation fee (if present on the race) is not charged. If the club is not marked as affiliated, the individual can indicate their own affiliation status by entering their race licence number. Under these circumstances, if a race licence number is entered, the affiliation fee is not charged and the entry is marked as affiliated. If the race licence number is left blank, the affiliation fee is charged and the entry is marked as unaffiliated.

Likewise, the Chip-Rental fee is only charged if the own-chip number is left blank and, like online charges, the chip-rental fee is only charged once for an entry (so if the entrant elects to enter multiple races, only one fee is charged).

As previously mentioned, there are a number of fields which, although set up on the base form, appear only on the admin entry form. There are:- There are a number of internally-calculated database fields which show in the 'database name' attribute list of form fields. There are:-

Defining a New Form

Once all the database fields have been set up, the layout of the entry form can be configured. The best way to start is to copy an existing form and update the resultant copy.

New form fields can be inserted into the sequence, taking care not to throw-out the layout by switching columns too often.

Any form fields not required on the form should be hidden by unticking their 'Show on Form' attributes rather then deleting them.

Multi-Form Mode

When there are more than one active races with different forms set up in a site, a new step is introduced into the public and admin entry processes. Once the terms and conditions are accepted, the user will be presented with a list of the forms. The form chosen will be used to limit the races shown on the entry form (i.e. only races with the chosen form will be displayed). The name that is used on the form is therefore important and should describe the type of event rather than the form. For example, if you had three road running races set up on the system and two rowing races, the forms would be best named 'Road Running' and 'Rowing' respectively rather than 'Form for Road Running' and 'Form for Rowing'.

Multi-Form Mode can be avoided if races are split into separate sites. See the 'How-To: Multiple Sites' for more information on this.

Special Considerations

The race options section of the entry form contains all those items which are configurable as optional entries for each race. Options show if at least one race is selected at the top of the form with those options configured. As such, the race options that appear might not be relevant to all races selected. For example you may have two races set up where one race has a race t-shirt and the other doesn't. If both these races are selected for entry at the top of the form, the t-shirt radio buttons display, even though they are only relevant for the first race. Under these circumstances, it is wise to add some memo text to the form explaining that t-shirts may not be included for all races.

A problem can arise if you set up more than one race with differing chip rental or online charge fees. As these fees are only charged once per entry, if you have differing amounts on each race, the calculation of these fees will have a differing basis depending on the order in which the races are selected and/or deselected. This may result in negative charges. In general it is advisable to keep online charges and chip rental fees the same on all races. If it is necessary to have different charges, consider setting up a different form. This will activate the 'Multi-Form Mode' described above and this can be used to ensure that it is not possible to concurrently enter races with differing pricing structures.

The captions for the configurable race options 1 & 2 should now be configured through the form fields. In versions of OES prior to v2 these captions were configurable on each race.

If race transfers/changes are permitted, there are potential problems where the transfer or change affects the total fee charged. For example if an entrant decides to change their unaffiliated entry to affiliated, the reconciliation reports will highlight a difference as the affiliation fee was paid, but the entry fee shown on the entry now reflects the affiliated status where the affiliation fee was not required. In this particular case, it is necessary to manually fix the entry by entering a surcharge (i.e. a negative discount) in the discount field of the entry in question to reflect the higher amount paid. The system currently prevents an entrant from changing their entry from affiliated to unaffiliated where an extra charge would be required. Hence it is only currently possible to transfer or change an affiliated entry to another affiliated entry. The same problem exists with chip rental fees.