Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

This page describes data source definition of a Magnolia Content type. A data source defines how content type items are persisted.

Properties

Example configuration:

/content-type-examples/contentTypes/tourGuide.yaml
datasource:
  workspace: tourguides
  namespaces:
    mt: https://www.magnolia-travel.com/jcr/1.0/mt
  autoCreate: true
  
model:
  nodeType: mt:tourGuide
  properties:
    - name: birthday
      type: Date
    - name: gender
    - name: shortBio
The datasource properties:

type

optional, default is JCR

The type of the data source. If the value is JCR, the definition class must implement JcrDataSourceDefinition.

workspace

required

The name of the JCR workspace to store the content items.

When the definition item is loaded, and if there is no workspace registered by the given name and the autoCreate property is set to true, the system will register the workspace.

rootPath

optional, default is /

The root path for content type items in the given JCR workspace.

namespaces

optional

A list of JCR namespace names.

<namespace‑name>

A JCR namespace name.

When the definition item is loaded, and if the given JCR namespace hasn't been registered yet, the system will register the namespace.

The namespace name must comply with the rules for XML namespaces, see https://www.w3.org/TR/REC-xml-names/#NT-NCName, https://www.w3.org/TR/REC-xml/#sec-common-syn.

autoCreate

optional , default is false

If set to true, the following modifications will take place in the entire content type definition.

  • Workspace
    • Register the JCR workspace defined by the workspace property if it hasn't been registered yet.

  • Namespace
    • Register the JCR namespaces defined by the namespaces property if they haven't been registered yet.
    • Remap the namespace prefix to the new namespace URI if the namespace URI has been modified.
    • Re-register the namespace if the namespace prefix has been modified.
  • Node type
nodeTypeDefinition

optional

The path to an XML file which defines a JCR node type definition. The file must be a Magnolia Resource.

When the definition item is loaded, and if the node type defined in the file is not yet registered, the system will register it. (See Using the nodeType definition.)

JCR name spaces, node types and node type definitions

The model, explained in more detail on the Content type Model definition page, defines which nodeType is used. The model itself does not define the nature of the node type. In the example above the nodetype chosen is mt:tourGuide

Let's assume that the  mt:tourGuide  nodetype has not been registered yet. How to make sure that the model can utilize it?

There are two approaches. 

  • All specifications in the YAML file. 
  • Using the the nodeTypeDefinition and XML-based node type definition.

All specifications in the YAML file

The example above defines all the JCR parameters in one YAML file. In most cases this is the recommended approach.

Namespace

If you intend to use a JCR namespace that hasn't been defined yet, you can define the new namespace, for example mt, with the namespaces property.

Node type

In the above example, assuming that mt:tourGuide has not been registered yet,  the system will automatically register a new node type with the given namespace mt, and the new node type inherits from the Magnolia mgnl:content node type.

Using the nodeTypeDefinition and XML-based node type definition

With the nodeTypeDefinition property you can define a path to an XML file to define a JCR node type definition.

Using an XML file allows you to define various JCR namespace and node type definitions. Node type definitions based on an XML file can be more complex than the automatically generated node types, which inherit from mgnl:content automatically

Example of an XML-based node type definition:

/content-type-examples/jcr-node-type-files/travellers-node-types.xml
<nodeTypes
    xmlns:mgnl="http://www.magnolia.info/jcr/mgnl"
    xmlns:mt="https://www.magnolia-travel.com/jcr/1.0/mt">
  <nodeType name="mt:traveller" isMixin="false" hasOrderableChildNodes="true" primaryItemName="">
    <supertypes>
      <supertype>mgnl:content</supertype>
    </supertypes>
  </nodeType>
  <nodeType name="mt:tourGuide" isMixin="false" hasOrderableChildNodes="true" primaryItemName="">
    <supertypes>
      <supertype>mt:traveller</supertype>
    </supertypes>
  </nodeType>
  <nodeType name="mt:happyCustomer" isMixin="false" hasOrderableChildNodes="true" primaryItemName="">
    <supertypes>
      <supertype>mt:traveller</supertype>
    </supertypes>
  </nodeType>
</nodeTypes>
Example of a content type definition referencing an XML-based node type definition:
/content-type-examples/contentTypes/happyCustomer.yaml
datasource:
  workspace: happycustomers
  autoCreate: true
  nodeTypeDefinition: /content-type-examples/jcr-node-type-files/travellers-node-types.xml
 
model:
  nodeType: mt:happyCustomer
  properties:
    - name: country
    - name: age
      type: Double

The XML node type definition resource is loaded only if the XML resource is referenced in the Content type Data source definition of a Content type definition.

JCR security

Access to JCR workspaces is controlled by role-based access control lists (ACLs).

When the system detects and registers a new JCR workspace from a data source definition, it also automatically updates the superuser role by adding an ACL for the given workspace and granting read/write permissions for the / path.

In a production system, if you want to provide anonymous website visitors with (read) access to a specific JCR workspace, you must update the anonymous role by adding an ACL for the workspace.

For further information please read:

Interfaces and classes

The base DataSourceDefinition interface is agnostic of any data source type. To specify a JCR data source, Magnolia provides the JcrDataSourceDefinition interface and the ConfiguredJcrDataSourceDefinition implementation class.

For DataSourceDefinition the ConfiguredJcrDataSourceDefinition is the default implementation class via type mapping on the XML-based module descriptor of the magnolia-content-types module. 

By default Magnolia expects you to configure properties for ConfiguredJcrDataSourceDefinition to define a JCR data source.