DataMgr 2.5 Documentation: Relation Fields

Relation Fields

One of the most powerful features in DataMgr is the use of Relation Fields. Relation Fields act just like fields in the database table, but aren't actually stored as fields in the database. Instead, Relation Fields use data from related to return (and save) their values.

Relation Fields will be included in the recordset returned from getRecords() and can be specified in the fieldlist attribute or used for filtering in that method as well.

With the exception of aggregates and custom relation fields, the values underlying a relation field can be saved just as you would save a normal field as well.

The remainder of this section will discuss different types of Relation Fields. Except XML, no code examples will be given as these fields will act just like normal fields from the perspective of your use of DataMgr.

As of version 2.1, Relation Fields can point to other Relation Fields (except type "list") instead of just pointing to physical fields. So, for example, a list relation field can list values from an aggregate relation field.

Relation Fields can be of the following types:

All relation fields (except custom) also have an optional onDelete attribute that covers how DataMgr should respond if the related record has data for the record being deleted.

For any Relation Field that has a join-field attribute, but no join-table attribute, the join-field represents the field name in both tables (and the must match). If the field names do not match, you can use the join-field-local (for the field name in the current table) and join-field-remote (for the field name in the related table) in place of the join-field attribute to make that distinction.

Note: You can create a Relation Field using loadXml() (as the examples below illustrate) or using the setColumn() method. If you use the setColumn() method, include a "Relation" argument, which will be a structure with keys matching the attributes of the "relation" element (not that keys with dashes "-" will have to be created with array format (eg relation["join-field"]).

Restrictions: While relation fields can point to other relation fields, they cannot point to list relation fields nor to any field that would yield an invalid result (aggregate fields other than count pointing to a string field, for example). Relation fields cannot point to fields with a CF_Datatype of CF_SQL_LONGVARCHAR.