Content type Model definition

A model definition, a subitem of the Magnolia Content type definition, defines the model of a content type. The model describes the properties of a content item such as name, description, asset, birthday, and so on.

In the default JCR-based implementation, the type of the properties can be String, Boolean, Decimal, Double, Long, Date, asset, richText, another content type or a submodel. The model can define a list of submodel definitions.

Model definition properties

When designing a model don’t think about it in terms of UI elements like fields. Think in terms of what type of data the field stores. For example, a link field. stores a String type (i.e., property). The property in the model definition can be decorated in the app definition with whatever UI element stores that data type.

/content-type-examples/contentTypes/tourGuide.yaml
datasource:
  $type: jcrContentTypeDatasource
  workspace: tourguides
  namespaces:
    mt: https://www.magnolia-travel.com/jcr/1.0/mt
  autoCreate: true

model:
  nodeType: mt:tourGuide
  properties:
    - name: birthday
      type: Date (1)
    - name: gender
    - name: shortBio
    - name: contact
      type: contactData
  subModels:
    - name: contactData
      properties:
        - name: email
        - name: phoneNumber
        - name: addresses
          type: address
          multiple: true
    - name: address
      properties:
        - name: street
        - name: city
        - name: postalCode
        - name: country
1 Here, the type set is Date.
Property Description

properties

required

A list of property definition objects.

     <property>

A subdefinition item defining one property of the model. Its definition interface is info.magnolia.types.model.PropertyDefinition.

Read the Property definition properties section for all the details of a PropertyDefinition object.

Although it’s possible to create a content type definition that doesn’t contain a content property specification in the list of properties, with the intention that you would set the properties later on manually in a configured app, such a content type definition creates an app that:

  • has a details subapp of type ConfiguredSubAppDescriptor rather than DetailDescriptor,

  • offers no Add item or Edit item actions.

To avoid this, define at least one content property in your content type definition.

For example, as a minimum property configuration for a fully functional content app, define the name property and set its required attribute to true.

...
model:
  properties:
    name:
      required: true

subModels

optional

A list of submodel definition objects.

     <submodel>

A subdefinition item configuring a complete submodel. Its definition interface is info.magnolia.types.model.SubModelDefinition.

A submodel has the same properties as a model, but a submodel cannot have additional submodels.

If nodeType is not provided, the mgnl:contentNode is used by default.

nodeType

optional

The name of the node type for storing an item of the given content type.

For JCR, the system automatically registers a new node type by the given name if it has not been registered yet. The type generated is inherited from the Magnolia mgnl:content node type.

If the nodeType is not provided, mgnl:content is used by default.

For contentDatasource, node types are not automatically registered in the system.

If the nodeType is not provided, no node type is defined for the content.

Folders in contentDatasource have the node type folder.

Property definition properties

This section describes the PropertyDefinition item. Property definition items can be defined in the properties property, which is a property of the model definition of a content type definition.

Table 1. <property>
Property Description

name

required

The name of the property. The name is used for storing values in the underlying data source.

type

optional, default is String

Possible values:

  • JCR property types

    • String

    • Boolean

    • Decimal

    • Double

    • Long

    • Date

  • richText - creates a Rich text field, which is a custom Magnolia field implementing the CKEditor component.

  • asset - creates a Link field to choose an asset.

  • The name of a Submodel.

    You can only reference submodels defined in the same content type.

  • The name of a Content type making a reference to another content item. Prefix the value with reference: (for example, + type: reference:tourGuide)

Number zero trimming behavior

If you configure a field as Decimal or Double, values entered with trailing zeros are displayed without them after saving. For example:

  • 123.01230 is saved and reloaded as 123.0123

  • 123.00 is saved and reloaded as 123

This is caused by the way JavaScript and JSON handle numeric types. When a numeric value is parsed or serialized, it’s converted to a minimal numeric representation.

If preserving the exact numeric format (including trailing zeros) is required:

  • Use the String type instead to store the exact text representation entered by the user.

  • Format numbers for display using tools such as Intl.NumberFormat, specifying a fixed number of decimal places. Be aware, however, that the formatted output is still a String, not a numeric value.

required

optional, default is false

Makes the property mandatory.

i18n

optional, default is false

Enables i18n support for the property.

You also need to enable i18n for a site definition. There, use info.magnolia.cms.i18n.DefaultI18nContentSupport as the value for the class property. For example, see this configuration for the fallback site of DX Core, if no other site is present: 
'fallback':
  'mappings':
    'extends': 'override'
  'domains':
    'extends': 'override'
  'i18n':
    'class': 'info.magnolia.cms.i18n.DefaultI18nContentSupport'
    'enabled': true
    'fallbackLocale': 'en'
    'locales':
      'en':
        'country': ''
        'enabled': true
        'language': 'en'
      'de':
        'country': ''
        'enabled': true
        'language': 'de'

multiple

optional, default is false

The true setting allows storing multiple values of the property.

options

optional

Defines a parent node for a list of selectable options OptionDefinition rendered as a Select field.

model:
  nodeType: lib:book
  properties:
    - name: category
      options:
        fiction:
          value: catFiction
          label: Fiction
        poetry:
          value: catPoetry
          label: Poetry

Options dropdown

Further customization such as using an alternative control, for example a radio button group, is possible by overriding the class or the fieldType property in the app descriptor.

Currently, the values are saved to the JCR repository only as the String type: MGNLCT-132.

     value

required

Value saved to the repository when selected.

     label

optional

Option label displayed to the user.

Submodels

Use submodels to define complex content types.

Submodels are useful whenever you need a group of fields more than once. A content type model definition can contain a list of submodel definitions within the subModels property. Submodels can be used only within the content type where they have been defined.

A submodel definition has the same properties as a model, but a submodel cannot have additional submodels.

The default nodeType for a submodels is mgnl:contentNode.

Referencing content types

Projects often have multiple content types, and those types can reference each other. For example you could have a Book type and a Publisher type. The Book could have a reference to the Publisher type. Then in Magnolia authors can manage publishers in one app, and books in another app. The form for the Book app will include a control to select a Publisher for that app. This common use-case is easy to configure in the content type.

bookType example
type: reference:bookType (1)
1 Prepending reference: allows you to reference another content item.

Interfaces and classes

Model

The base model interface is info.magnolia.types.model.ModelDefinition and info.magnolia.types.model.ConfiguredModelDefinition is set as the default implementation class.

Submodel

The submodel item is defined by the info.magnolia.types.model.SubModelDefinition interface, which extends info.magnolia.types.model.ModelDefinition.

Migrating CT-based definitions

See Upgrading to Magnolia 6.4

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules