Skip to content

Models

Models define the structure of your content. They are blocks of information, objects.

Models are made up of fields and inheritance.

Model definition

A model definition is made up of the following properties.

  • Name is a user-friendly short description of what the model is for
  • Alias is a short name used to reference the model through external integrations
  • Usage defines how the model can be used
  • Inheritance defines what Base models the model inherits from
  • Fields define what properties your model has

The two most important parts of a model definition are its alias and its usage.

The name of a model is simply a user-friendly description. The only restriction on the name of a model is that it must be present. A model cannot have an empty name.

Model alias

The alias is how your model is referred to throughout the system, and by external integrations. Though aliases are mutable, changing them may have unexpected consequences in external integrations that rely on a model having a specific alias.

There are restrictions on what a model alias can be.

Model alias restrictions

A model alias must -

  • start with an upper-case character (A-Z)
  • be at least 3 characters long
  • only contain letters and numbers
  • not contain any punctuation or spacing
  • be unique to your project

This is the regular expression used for model alias validation -

/^[A-Z][a-zA-Z0-9]{2,}$/

Model usage

You must define where and how a model may be used. There are three options.

Once a model has been created, its usage cannot be changed.

Model usage options

A model can be configured for the following uses -

  • Entry are physical entities that exist as queryable objects
  • Module models are components that live within the fields of entries
  • Base models can be inherited from by both Entry and Module models

Model inheritance

Model inheritance can help structure your data in a robust and reusable way.

When one model inherits another, it takes on all the field definitions from the model it is inheriting.

Restrictions around model inheritance

There are a few restrictions on what types of models can inherit from -

  • Entry and Module models may inherit from Base models
  • Base models may not inherit from other Base models
  • Entry models may not inherit from any model other than Base models
  • Module models may not inherit from any model other than Base models
  • Entry and Module models may inherit any number of Base models

As the APIs powering the system are all GraphQL endpoints, the inheritance of models follows the standard of GraphQL interface inheritance.

An example where model inheritance may be useful

In terms of a website, you may have several models that represent different types of pages. Though the pages have different fields, there may be some common ground - such as metadata.

Rather than repeating the common metadata fields (title, description, keywords, etc...) on all the various page models, you may wish to have a common Base template that defines those fields and have your page models inherit from it.

Model field definition

Model fields define what properties your model has, each field has the following properties.

  • Name is a user-friendly short description of what the field is used for
  • Alias is a short name used to reference the field through external integrations
  • Category optional groups model fields together for easier content entry
  • Order specifies the order in which the fields are displayed
  • Type describes what type of content the field will hold

The name of a field is simply a user-friendly description. The only restriction on the name of a field is that it must be present. A field cannot have an empty name.

Model field alias

The alias is how your field is referred to throughout the system, and by external integrations. Though aliases are mutable, changing them may have unexpected consequences in external integrations that rely on a model having a specific alias.

There are restrictions on what a field alias can be.

Model field alias restrictions

A model field alias must -

  • start with a lower-case character (a-z)
  • be at least 3 characters long
  • only contain letters and numbers
  • not contain any punctuation or spacing
  • be unique to the model (i.e., a model may not contain two fields with the same alias)

This is the regular expression used for field alias validation -

/^[a-z][a-zA-Z0-9]{2,}$/

Model field type

The type of a field defines how a user enters content into the field as well as how it is presented in the API endpoints.

Types are built into the system, there is no way (at present) to build custom field types.

Each field type can offer additional configuration options.

Text fields

A text field can be used to hold any sized string.

They can be marked as multi-line to allow editors to enter larger pieces of content.

link fields can hold references to other pieces of content within a project.

They can be configured to only link to specific types of content.

Media fields

Similar to link fields, media fields can be used to link to pieces of media within a project.

They can be configured to start at a specific media folder to optimise the content entry experience.

Modules fields

The field type modules allows you to add any number of objects to your content, it allows you to create a list of content of any type based on the Module model usage.

These fields can be configured to only accept modules of a certain type.

Base values

You can specify default values on a model that will be used until either an inheriting model or a piece of content overrides it.

Tip

Base values are entirely optional and are not required for every model.

The final value of a piece of content - be it a module or an entry - will be the combination of the base values of all the models it inherits with the value of the content itself.

Next to each field in the content entry editor there is a Clear button. Clicking this will remove any value in the piece of content causing it to inherit its value from the model base value if there is one.

Content based on a model with base values example

I have created a model called BlogPost with a title and body field.

I have specified the values on the model for title to be 'My new blog post'.

I create a new content entry based on the BlogPost model and leave the title field blank.

When querying this new content entry, the title field will be 'My new blog post'.

I then change the title field on my entry to 'My old blog post'.

Now, when querying this new content entry, the title field will be 'My old blog post'.

Transferring models

It's possible to transfer models between projects, even between user accounts. If I am working on a project and have defined a model structure I feel may be useful for someone else, I can package up that model and send it.

Exporting models

Navigate to the models section by hovering over the Content item in the top menu, then clicking Models.

Click the Export models button.

Select the models you want to export. Inherited models will automatically be selected.

Then click the Generate button. A text field will appear with a base64 encoded payload. Send the contents of this field to the user you are sharing your models with.

Warning

Sharing models shares the base values of a model as well. Be sure not to share any models that contain confidential material in their base values.

Importing models

Navigate to the models section by hovering over the Content item in the top menu, then clicking Models.

Click the Import models button.

Paste the payload into the Model import payload field and click the Verify button.

A list of models to be imported will be displayed. If you already have a model from the payload it will be skipped.

Click the Import button to initiate the import process.