Content connector

The content you manage in Magnolia is typically stored in the JCR repository but it doesn't have to be. A content connector defines where the content resides. With a custom content connector you can decouple content management from content storage. Store the content in a database, cloud storage or a Web service. Write a connector that lets editors choose image assets from Flickr. Users can continue to manage the content in familiar Magnolia content apps. They don't have to leave Magnolia just because the content resides somewhere else.

 Magnolia 5.3+. Content connector was introduced in Magnolia 5.3. Before this, content apps were limited to JCR persistent storage. See Migrating your apps.

Implementing a content connector

In technical terms, a content connector is a bridge to a data source, which helps you read content outside the JCR repository.

The ContentConnector interface defines APIs to "map" arbitrary objects to three main representations, and vice-versa:

• a unique identifier, also referred to as itemId
• a Vaadin Item, e.g. for use in a detail form
• a unique String representation, for the content app to use as location fragment.

Mind that your content app will not fetch data directly from the connector but typically from a Vaadin  Container. You need to also provide content views (e.g. tree, list) that work with this container. These views and their presenter classes are then configured in the workbench definition.

If required, you can inject your own content connector in the constructor of your class. Content connector has its own provider: info.magnolia.ui.contentapp.contentconnector.ContentConnectorProvider. One instance of a connector is created per subapp by default.

The Content app with non-JCR content tutorial explains how to implement a non-JCR content app, including a custom content connector.

Content connector definition

A connector definition specifies the data source. In case of a JCR connector, the definition requires you to specify a workspace and a path in that workspace. Each content app subapp must provide its own content connector definition. If you implement your own connector, extend info.magnolia.ui.vaadin.integration.contentconnector.ContentConnectorDefinition.

Properties:

• contentConnector
  • class: Definition class. Only needed if you implement your own, non-JCR content connector. The default definition class is info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnectorDefinition. If you store content in the JCR repository this property is not needed but you need to define a number of other properties. See the JCR content connector example below. The value must be a fully-qualified class name.
  • implementationClass: Implementation class that implements the ContentConnector interface. The default implementation is info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnector. If you store content in the JCR repository this property is not needed. The value must be a fully-qualified class name.

Examples of definition classes:

• ContentConnectorDefinition: Basic content connector definition interface. Implement this in your custom definition class.
• JcrContentConnectorDefinition: Defines a connector that operates on the JCR repository.

Example: JCR content connector

JCR content apps have at least two subapps. A browser subapps display the items and a detail subapp edits them. Both subapps need their own connector definition.

browser subapp

A JCR content connector definition introduces properties that identify a JCR workspace as a data source. It also defines the node types to operate on.

Properties:

• contentConnector
  • nodeTypes:  The types of content the connector operates on. For example, the connector in the Contacts app displays contacts and folders.
    
    • <node type name>
      
      • icon: CSS class name of the icon displayed on the workbench. See the default icons that ship with Magnolia or create your own.
      • name: Node type the connector operates on. These are Magnolia or JCR node types such as  mgnl:contact.
  • defaultOrder: Default sort order for the content items in list views. The value is the name of the property you want to sort by, such as jcrName.
  • includeProperties: Displays also the JCR properties of the node when set to true. Only nodes and subnodes are displayed when false.
  • includeSystemNodes: Displays also nodes used by the system such as nodes internal to the operations of the JCR implementation. Set this property to true if you want to look in the imaging workspace in detail to learn how image renditions are generated, for example. Default is false.
  • rootPath : Path configured as root for this workspace. Only content below the path is operated on. If not specified, defaults to workspace root (/).
  • workspace : The workspace in the magnolia repository where the content resides.

detail subapp

The connect definition for a detail subapp is much simpler. You only need to define the workspace.  

Properties:

• contentConnector
  • workspace: The workspace in the magnolia repository where the content resides.

Example: non-JCR content connector

This is an example content connector definition for a content app that manages files on the local file system. This is a simplified example.

Changes between Magnolia 5.2 and 5.3

JCR content app configuration changed in Magnolia 5.3. Some nodes that used to be configured in the workbench definition moved to the new content connector definition:

• nodeTypes
• defaultOrder
• includeProperties
• path (renamed to rootPath)
• workspace

Comparison of 5.3 and 5.2 configuration in the Contacts app:

Migrating your apps

When upgrading your Magnolia 5.2 instances to 5.3, all native Magnolia JCR content apps in community and enterprise editions are updated to use the new content connector automatically. The properties are migrated from the workbench to the connector configuration. You need to migrate your own custom JCR content apps. Add the ContentAppMigrationTask to your module version handler.

import info.magnolia.ui.contentapp.setup.for5_3.ContentAppMigrationTask;

public class CustomModuleVersionHandler extends DefaultModuleVersionHandler {
    public CustomModuleVersionHandler() {
		// "2.0" is just an example of the new version of your custom module
		register(DeltaBuilder.update("2.0", "").addTask(new ContentAppMigrationTask("/modules/customModule")));
    }
}

Credits:

• Database icon by Anton Outkine from The Noun Project
• Cloud icon by Edward Boatman from The Noun Project