Metadata
Metadata means data about data and is used generically to describe data that holds information about other data objects. In a Siteframe class definition, however, the metadata is a specific data structure (a PHP array) that contains information about the properties, or individual data elements, that make up a data class. Each Siteframe class definition contains a metadata structure that defines its make-up. This metadata structure is used for numerous purposes:
- It is used to create the database table(s) that hold the object. Instead of having an external SQL script that must be synchronized with the object data definition, having a single repository of metadata ensures that data structures are always kept in sync.
- It is used to define HTML forms for entering and editing objects. Since the metadata defines the object data structure, there is never any difference between the input form definition and the object's data, as could happen if the form definitions were separate from the data itself.
- It defines rules for handling data. For example, a metadata field can define a specific pattern that can be used to enforce structured data. For example, you might define a telephone number data object that has the pattern "999-999-999" to ensure that phone numbers are always entered in the same manner.
- It defines relationships between data elements. For example, the metadata can enforce referential integrity rules among different data objects.
Metadata Structure
The metadata definition consists of a single PHP array; each array element is indexed by the name of a property, and its value is a property definition array. In this example,
public $metadata = array(
'page_id' => array(
'col' => true,
'required' => true,
'type' => 'integer',
'internal' => true,
),
);
the metadata array holds one element, page_id. The page_id element is a physical column ('col' => true), cannot be null ('required' => true), is of type integer('type' => 'integer'), and is used internally (i.e., not set directly by the user).
Metadata Properties
The following is a list of all available properties for metadata definitions. Note that the value following the name is the PHP datatype of the meta-property.
- advanced - boolean
If true, then the property appears under the "Optional Settings" or "Advanced Settings" section of the input form. While the exact handling of these values is determined by the form template, the advanced values are typically hidden unless the user takes a specific action to display them, such as clicking on a link. - auto_increment - boolean
If true, then these properties are marked as "auto_increment," which means that, whenever a new object is created, a unique integer is automatically assigned to the value. - col - boolean
If true, the property represents a physical column in the database. Most pre-defined properties except for long text fields are columns. Properties that are columns can be used in sorting and querying (such as joining between tables). When col is false, then values are accessible when the object is created, but not directly in the database. - formatted - boolean
For textarea properties, this determines whether or not HTML values are allowed. If formatted is false, then all HTML tags are stripped from the value before it is saved. If formatted is true, then HTML tags in the configuration variable allowable_html are retained, while other tags are removed. If a rich-text editor is available, it is usually applied to formatted properties. - help - string
This is a help string associated with the property. On input forms, the help string is usually displayed as a link of text underneat the input control or in a pop-up window. If a language file entry named help_name (where name is the name of the property) exists, then its value will overwrite any value provided in the metadata definition. - hidden - boolean
If hidden, the value is stored in a hidden field in the input form. Hidden values are typically used for keys, where the value is required for editing, but should not be changed by the end user. - index, unique - boolean
If either of these properties is true, then an index is created on the specified property column; a true value is thus invalid if col == false. If unique is true, then a unique index is created (this disallows duplicate values in the database). You should only use either index or unique, never both. - internal - boolean
When a property is marked as internal, its value cannot be set by the end user. The value is not displayed for input, and the value is set internally by the software. For example, object creation dates are almost always marked as internal. Contrast this with virtual, where values are displayed and set by the user, but are never stored in the database. - minlength, maxlength - number
These determine the maximum and minimum length of the value. An error is signalled if the entered value is less than the minlength or greater than the maxlength. The maxlength is also used for the column length for text properties. For example, if a property is text and has a maxlength = 50, the resulting SQL data type is VARCHAR(50). - noupdate - boolean
If this flag is true, then the property is not used in an update statement. For example, primary keys and creation dates are not usually updated. - options - array
For select properties, this is a hashed array of values; the index is the return value, and the value is the prompt. For example,options => array(1 => "One", 2 => "Two"); in this case, the dropdown list for the property will display "One" and "Two"; the return value, however, is either 1 or 2. - pattern - string
This is a Perl-compatible regular expression that is matched against the value; if the pattern fails to match, then the value is rejected and an error is recorded. For example, you might define a US-formatted telephone number aspattern => '/[0-9]{3}-[0-9]{3}-[0-9]{4}/'. - prompt - string
A prompt string for the property, used on input forms. If a language string entry prompt_name exists (where name is the name of the property), its value will overwrite any value provided in the metadata definition. This allows the input form to be internationalized. - references - string
A special string that indicates a foreign key relationship. The value is in the format 'Class.column'; for example, 'User.user_id' indicates that the current field has a parent key of user_id in the User class. - required - boolean
A property marked required is created as NOT NULL in the database and a value is required when the property appears on an input form. - rval - number
For checkbox items, this determines the value that is stored or returned when the property is checked. This is almost always 1. - size - number
For text items, the displayed size of the text box (in characters). This size can be overridden through CSS formatting. - sqltype - string
For select items, defines the SQL data type of the property. Since drop-down lists can return either character strings or numbers, the SQL type determines how the column is created (if col is true). - type - (integer, text, textarea, datetime, checkbox, select)
This defines the data type of the property expressed as an HTML input object type. "integer" represents a numeric value. "text" is a string with a fixed maximum length. "textarea" is a string with (basically) unlimited length. "checkbox" is actually a numeric value, but represented by a 0 or 1 (unchecked/checked). "select" is a dropdown list; if "select" is specified as the type, then options and sqltype must also be specified. - virtual - boolean
Virtual values are displayed and set by the user, but are never stored in the database. For example, when you attach a new file to a page, the form field that accepts the uploaded file name is virtual. The value is never stored in the database; instead, the value is used to create a File object, and a link between the File and the Page is created. A property can never be both virtual and internal.
Please report any errors or omissions to the webmaster.
<Couldn't be bothered to add a subject>
by
/ at 21:50 on July 1, 2005
[read entire article]
