Models.xml

In the models.xml file all data types of your setup are defined. This file the center of your setup's logic and requires some strict naming conventions.

If the file does not ecxist yet, you can create it in application/config.

Coding and naming standards
Field types
Options and validators

Coding and naming standards

PascalCase should be used for the model name
camelCase should be used for field names
when defining a field relation to another model, the name of this model should be PascalCase
hasMany fields should have a plural name
always define a field label if that field is displayed somewhere in the backend
a field description is not required but strongly encouraged when a field's use should be explained to the user
always try to use the same tab names. Much used names are the following :
- General, Context, Contact, Media, Visibility
model fields, formats and options should be regarded as seperate sections. They should be divided as such using enters
in a field definition no enters should be added in between lines
no space is required before a closing bracket

<model name="Article">
    <field name="title" type="string" localized="true">
        <option name="label.name" value="label.title"/>
        <option name="scaffold.form.tab" value="general"/>
        <option name="scaffold.search" value="true"/>
        <validation name="required"/>
    </field>
    <field name="intro" type="text" localized="true">
        <option name="label.name" value="label.intro"/>
        <option name="scaffold.form.tab" value="general"/>
        <option name="scaffold.search" value="true"/>
        <validation name="size">
        		<parameter name="maximum" value="300"/>
        </validation>
        <validation name="required"/>
    </field>

    <format name="title">{title}</format>

    <option name="behaviour.log" value="true" />
    <option name="behaviour.slug" value="title" />
    <option name="scaffold.expose" value="true" />
    <option name="scaffold.form.tabs" value="general,media" />
    <option name="scaffold.title" value="title.articles" />
</model>

Property fields

Property fields are fields which have a scalar or primitive type. This means, the type of the field can directly mapped to a variable in your code.

The following property field types are available:

string
text
boolean
integer
float
date
datetime
email
website
password
wysiwyg
file
image
binary

Data Formats

Data formats provide a way to generalize your model data.

The predefined and common used data formats are:

title A title or name for your data
teaser A teaser for your data
image Path to the image of your data
date A date for your data

<format name="title">{title}</format>
<format name="teaser">{intro|truncate:150}</format>
<format name="image">{image.value}</format>

Although data formats are optional, it's recommended you define at least a title format.

Relation Fields

Relation fields have no primitive type. They are represented by another model. There are different types of relations.

Belongs To

A belongsTo relation type is the easiest relation.

A simple example would be a comment for a blog post. The comment model would have a belongsTo field with the blog model as related model.

For this relation, no extra tables are needed. The field blog is added to the comment table. It contains the id of the blog item.

<field name="program" model="Program" relation="belongsTo">
    <option name="label.name" value="label.program"/>
    <option name="scaffold.form.type" value="select"/>
    <validation name="required"/>
</field>

Has One

A hasOne relation type is simular to the belongsTo relation with the exception of how it's handled on database level. For a hasOne relation type, a link table is needed since no field for the relation is stored in the table of the linking model.

Has Many

The hasMany relation is in most cases the other side of a belongsTo relation.

In the blog-comment example, a blog post has many comments. Therefor a hasMany field with the comment model as related model could be added to the blog model. That way, you can query for a blog post with all it's comments.

<field name="items" model="OrderItem" relation="hasMany">
    <option name="label.name" value="label.items"/>
    <option name="scaffold.form.type" value="object"/>
    <option name="scaffold.form.tab" value="items"/>
</field>

Has Many To Many

The other case for a hasMany relation is when you have a relation of multiple records.

A example for this could be when you start to tag your blog posts. A blog post could have multiple tags and a tag can be used for multiple blog posts.

You would have a tag model with a hasMany field with the blog model as related model. The blog model on his side, would have a hasMany field with the tag model as related model.

Reference

The following is a reference for models.xml and the available elements.

models

attributes: -
value: -
parent: none (root of your file)
children: model

model

attributes:

name: Name of the model (required)
modelClass: Full class name for your model, defaults to ride\library\orm\model\GenericModel
dataClass: Full class name for your data, defaults to ride\library\orm\model\data\Data
willBlockDeleteWhenUsed: Boolean to state if entries from this model can only be deleted when they are not referenced in other models.
value: -
parent: models
children: field, index, format, option

field

attributes:

name: Name of the model (required)
type: Type of the field. (required for a non relation property)
default: Default value for the field. (only for scalar properties)
label: Translation key for the name of this field, defaults to null
localized: Boolean to state if this field is localized, defaults to false
model: Model name of the relation. (required for a relation property)
relation: Type of the relation. (required for a relation property)
linkModel: Model name for the link model, defaults to a generated value of the 2 linked model names
foreignKey: Name for the foreign key in the related model, set this attribute when the related model has multiple relations back to this model.
dependant: Boolean to state if the related data should be deleted when this record gets deleted, defaults to false
relationOrder: Order expression for the relation. (only for hasMany relations)
value: -
parent: model
children: validation, option

validation

attributes:

name: The name of the validator (required)
value: -
parent: field
children: parameter

parameter

attributes:

name: The name of the parameter (required)
value: The value of the parameter (required)
value: -
parent: validation
children: none

index

attributes:

name: The name of the index (required)
value: -
parent: model
children: indexField

indexField

attributes:

name: The name of the indexed field (required)
value: -
parent: index
children: none

format

attributes:

name: The name of the format (required)
value: The format
parent: model
children: none

option

attributes:

name: The name of the option (required)
value: The value of the option (required)
parent: model, field
children: none