Models.xml

Suggest Edits

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

  • 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

Updated less than a minute ago