EDO

Data Structures

Detailing the markups used to define resources related to data.

Introduction
Data Sources
Data Views
Records and Fields

Introduction

There are three basic structures for referencing data within EDO:

Source: A Data Source refers to a source of data. This could be a database, such as a MySQL database, another data source such as a data file, or even an abstract source of data.
View: A View is a way of accessing a set of data. In its simplest form, a View may reference a Table, while more complex Views may filter data from within a source, join tables, etc... A view at its base level is a two-dimensional set of data, with column field names, and rows containing different records. A Source may contain multiple Views.
Record: Commonly used with Views, a record is a grouping of values, identified by field names. As such, they are sets of Variables - ways of temporarily storing values.

Data Sources

Data Sources are usually a reference to a Database, but may also include other forms of data, including CGI, Data Files, and RAM/temporary. Internally, all sources are represented as a DBI handle (Perl's standard DataBase Interface), and Non-Database sources are represented using techniques such as the DBD::RAM module.

Data Sources are defined using the <SOURCE> markup, which requires two properties to be defined; the NAME of the source, which is an identifier used to reference this source, and the TYPE of the source. Additional properties can be defined (and some are required) as additional markups within a <SOURCE> markup.

The currently supported source types include:

mysql

The source is a MySQL Database. Additional markups to define information for this type include:

<USER>username</USER>: The name of the user in the database to connect as.
<PASSWORD>password</PASSWORD>: The matching password for connecting to the database.

CGI

The source is data submitted to the page as CGI data (ie; using a GET or POST submission). This is not required to access normal CGI data (which can be accessed through the special CGI record), but is used when tabulature data is posted from a CGI form. ie; where multiple values for the same field name are submitted. This type requires no additional markups.

datafile

The source is a Data File. This is a text file with a syntax similar to .INI files under Windows, and is commonly used by some for storing data in an easy-to-hand-edit format. Additional markups to define information for this type include:

<FILE>filename</FILE>: The filename of the Data File, relative to the primary EDO application page (or absolute off the document root, I think. ie; any URI).
<KEY>fieldname</KEY>: As Data Files use an un-named unique key system, defining this property will give that field a field-name, so it may be accessed within views.

Here's some quickie examples of complete Source definitions:

A DataFile stored at URI "data/thedata.dat", where the key field is called "Bill":

<SOURCE NAME="mysource" TYPE="datafile">
   <FILE>data/thedata.dat</FILE>
   <KEY>Bill</KEY>
</SOURCE>

A MySQL DB, with access as user "bingle" without a password:

<SOURCE NAME="mysource" TYPE="mysql">
   <USER>bingle</USER>
</SOURCE>

Data Views

Data Views, as the name implies, is a view of some data within a source. More specifically, this data, which is stored in a source, consists of a number of named fields, and a number of records, consisting of values for those fields. Most views are simply references to tables within a database, or a similar structure from non-database sources.

Data Views are defined using the <VIEW> markup, which requires at least the view NAME to be defined. A Source is also required, which can be specified either using the SOURCE parameter to the <VIEW> markup, or by defining the view inside a Source definition, effectively implying that parent source for the view.

Views also require a list of fields to be specified, using the <FIELDS> markup within a <VIEW> markup. The field names are comma-delimited.

Here's some quickie examples of complete View definitions:

A view to a People table with 5 fields in a Source called "Fred":

<VIEW NAME="People" SOURCE="Fred">
   <FIELDS>ID,name,address,phone,email</FIELDS>
</VIEW>

A datafile source "fields" containing Field definitions with one view "fields"

<SOURCE NAME="fields" TYPE="datafile">
   <FILE>db.fields</FILE>
   <KEY>name</KEY>
   <VIEW NAME="fields">
      <FIELDS>title,name,type,other,help</FIELDS>
   </VIEW>
</SOURCE>

Records and Fields

A Record is a collection of fields, used to temporarily store values.

Records are often used to store the results of a query to a View, and as such may consist of the same fields as a view, but there is no enforced correlation. For example, a more complex record may contain select fields from several views, and the data of the one record may be populated by a join across several Views.

The Fields within a record can contain specific properties, which dictate the formatting of the fields in different circumstances, as well as the type of data they can store. The most important setting for each Field is the field type. Once a type is set, further properties can be customised.

Records are defined using the <RECORD> markup, which requires the record NAME to be defined.

Records also require a list of fields to be specified, using the <FIELDS> markup within a <VIEW> markup. The field names are comma-delimited. A special View containing the types and parameters for each field can be specified using the DETAILS option to <FIELDS>.

The syntax to reference a particular field is:
[record.]field[.method]
If a record is not specified, then the default record is assumed. If a method is not specified, then the default method is assumed (more on methods later). To include the value of a field anywhere in a document, preceed the field specification by a $ symbol. ie;
$[record.]field[.method]
If it isn't clear within the flow of the document what the field specifier is, the whole field specifier can be enclosed in braces ({ and }) to clarify it. ie;
${[record.]field[.method]}

As a general rule, preceeding a Field specification by a $ will substitute the value stored in that field before further processing. As such, the value of a field can be used within the normal document, and within the arguments of the custom EDO markups. Some EDO markups specifically want the name of the field, not its value, and so the field specification is required without the $.

By default, a Field is of type "string", with a formatted size of "30" and a maximum size of "255". Properties of fields can be defined in a View and referenced when creating a Record, or can be altered using the <ALTER> tag, which takes as arguments the FIELD to alter, and the name of the property to alter. All fields have some common properties (including TYPE), but different types of fields can have different properties.

Here's some quickie examples of Record definitions:

A Record "People" to match the earlier View example, with the details of the Fields stored in a View called "fields":

<RECORD NAME="People">
   <FIELDS DETAILS="fields">ID,name,address,phone,email</FIELDS>
</RECORD>

The same Record definition, but using <ALTER> to change Field properties, instead of a DETAILS View:

<RECORD NAME="People">
   <FIELDS>ID,name,address,phone,email</FIELDS>
</RECORD>
<ALTER FIELD="People.ID" TYPE="int">
<ALTER FIELD="People.address" TYPE="text">
<ALTER FIELD="People.email" SIZE="60">