EDO

Field Methods

Detailing the intricacies of the theory and use behind Field Methods.

• Introduction
• Basic Methods
• Escaped Data
• Field Properties
• Field Validation

Introduction

A Field is a data object, which can be a complex data type. The support for Fields in EDO allows much of the complexities of handling these data types to be handled internally, rather than cluttering up user applications with them. Why is this useful? For many data types, we may want to show the value in different formats depending the requirements. eg; A "html" representation of an E-mail address may include a live link to the address in question. Or a "date" may be stored numerically, yet be shown as "text" in a nice human-readable format.

To reference a Field, the full syntax is:
  [record.]field[.method]
The optional addition of a method is used to extract different formats of a Field's data, as well as provide additional special functionality. Rather than require a method to be specified every time, a default method is used, and this can be overridden using the EDO Markup <SET METHOD="defaultmethod">.

Regardless of the Field type, there are a number of basic methods supported for getting the data of a field, in a particular format. These basic methods include:

as_text

Returns the value as nicely formatted plain text.

as_html

Returns the value as nicely formatted HTML code, making use of HTML markups to improve the readability of the data.

as_form

Returns a HTML Form Element for the Field, including defaulting to the current value.

as_int

Returns an integer representation of the value. This is not supported by all field types!

value

Returns the raw data. The "value" is the format in which the data is stored in whichever "Source" holds it.

Being all about the data, there are various methods available to all Field types for representing the basic value in a "safe" format for a particular situation. For example, within most data queries (based on SQL), the data value has to be in an SQL-friendly format. Elsewhere, if the value is part of a URL, it will need to be in a HTTP-friendly format. These syntaxes usually involve "Escaping" special characters within the data.

Methods for giving different "Escaped" versions of the value include:

esc_sql

SQL-Friendly data. Basically adds a slash in front of single-quotes. Useful for using data within SQL syntactical code.

esc_http

HTTP-Friendly data. Replaces all special characters with a % followed by a Hex representation of the character, etc. Useful in formulating URLs from data.

esc_html

HTML-Friendly data. Puts in appropriate &whatever; for certain characters. Useful for using data within HTML form elements, and showing HTML code from fields without browsers parsing it.

As well as retrieving the Field Data itself in various formats, methods can be used to access properties of the Field. As different field types can have different properties, this does vary from type to type. Properties can be used to alter many aspects of a Field; some are specific to a type of field, while some are more generic. Properties can be used for such things as:

• Affecting the formatting and properties of a field when represented as a form element.
• Affecting layout and additional functionality when represented as other formats (such as HTML, text, etc...)
• Defining restrictions and requirements for values stored in the field to be considered valid.

Any property can be retrieved using the method syntax "prop_propertyname". For example, the maximum size (maxsize) of a "string" field called "bob" can be accessed using:
  $bob.prop_maxsize
In addition to all the custom properties, there are a number of default properties common to all types. Some of these are purely informational, such as the Title of a field, etc... Some of these default properties don't need the "prop_" preceeding their method calls. They include:

title

The Title of a field.

help

A Help description associated with a field. Usually contains a description of what the field is used for.

type

The Type of the field.

units

The units of measurement for the field.

As well as general properties and methods, there are a number of properties and methods associated with setting the requirements for a field to be valid, and querying whether the current value is valid or not. Some field types have pre-determined validity checks (for example, an "int" field cannot have any letters or special characters - only numbers), and some field types can have custom conditions specified to determine a field's validity (for example, a "string" can have the validformat property set to a regular expression, where the string will only be considered valid if the value matches the expression).

One commonly supported property affecting field validation is the "required" property. If this is set (to anything other than blank or 0), then the field is considered to be a required field. Normally, a blank field will be considered valid; setting the field to be "required" means a validity check will come back as invalid if the field is blank.

By default, most EDO markups will not check the validity of field values. This means that it is possible for invalid data to end up in a field, which will cause problems doing queries, exports, etc...

Methods provided to test the validity of a field's current value include:

blank

Returns 1 if a field's value is considered blank or not defined.

valid

Returns 1 if a field's value is considered to be "valid". As well as data format checks, this will also return 0 ("invalid") if a field is required and blank

validity

Returns one word describing the state of the field's validity. This will return one of valid, invalid or blank. This is similar to the valid method, but differentiates between a field that is invalid due to being blank and required, versus invalid data.

validation

Returns a customised string, based on the validity of the field. These strings are defined as properties validmsg and invalidmsg, specifying messages for valid and invalid responses respectively. Note: Perhaps we should consider implementing a custom blankmsg property as well.