Page tree
Skip to end of metadata
Go to start of metadata

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 content connector you can decouple content management from content storage. You can store content in a database, cloud storage or a Web service. You can create a connector that lets authors choose image assets from Flickr, for example. Authors benefit as they can manage all content in familiar Magnolia content apps. They don't have to leave Magnolia just because the content resides somewhere else.

Implementing a content connector

In technical terms, a content connector is a bridge to a data source. It allows you to access content outside the JCR repository.

The ContentConnector interface defines APIs that map arbitrary objects to three representations:

  1. A unique identifier known as itemId.
  2. A Vaadin Item that you can use in a detail form, for example.
  3. A unique String representation that the content app uses as a location fragment.

A content app does not fetch data directly from the content connector but from a Vaadin Container. In your content app you need to also provide content views (tree, list) that work with the container. These views and their presenter classes are 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. The provider creates one instance of a connector 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.

subapps:
  browser:
    contentConnector:
      class: info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnectorDefinition
      implementationClass: info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnector
Node nameValue
 subApps
 

 browser

 

 contentConnector

 

 class

info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnectorDefinition

 implementationClass

info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnector

Properties:

class

optional, default is info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnectorDefinition

Definition class. Only needed if you implement your own, non-JCR content connector. 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.

Examples of definition classes:

  • info.magnolia.ui.vaadin.integration.contentconnector.ContentConnectorDefinition: Basic content connector definition interface. Implement this in your custom definition class.
  • info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnectorDefinition: Defines a connector that operates on the JCR repository.
implementationClass

optional, default is info.magnolia.ui.vaadin.integration.contentconnector.JcrContentConnector

Implementation class that implements the  ContentConnector  interface. If you store content in the JCR repository this property is not needed. The value must be a fully-qualified class name.

Example: JCR content connector

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

We highly recommend using the same rootPath in both the detail and browser sub-apps, to benefit from our standard set of actions provided out of the box.

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.

subapps:
  browser:
    contentConnector:
      defaultOrder: jcrName
      includeProperties: false
      rootPath: /
      workspace: contacts
      nodeTypes: 
        - name: mgnl:contact  
          icon: icon-user-public        
Node nameValue
 subApps
 

 browser

 

 contentConnector

 

 nodeTypes

 

 contact

 

 icon

icon-user-public

 name

mgnl:contact

 defaultOrder

jcrName

 includeProperties

false

 rootPath

/

 workspace

contacts

Properties:

nodeTypes

required

List of node types the content connector operates on. For example, the connector in the Contacts app displays contacts and folders.

<node‑type‑name>

required

Arbitrary node name such as contact if you are displaying contacts in the browser.

name

required

Node type the connector operates on. These are Magnolia or JCR node types such as  mgnl:contact.

icon

optional , default is none

CSS class name of the icon displayed on the workbench. See the default icons that ship with Magnolia or create your own.

strict

optional

Specifies whether to include only the exact node type and ignore subtypes. 

hideInList

optional

Specifies whether to display the current node in list view and and search results. Use this property to, for example, exclude folders.

workspace

required

workspace in the magnolia repository that you want to browse.

defaultOrder

optional

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

optional, default is false

Displays also the JCR properties of the node when set to true. Only nodes and subnodes are displayed when false.

includeSystemNodes

optional , default is false

Displays also nodes used by the system such as nodes internal to the operations of the JCR implementation. Set to true if you want to see image renditions in the imaging workspace for example.

rootPath

optional , default is / (root)

Path configured as the root of the workspace. Only content below the path is operated on.

detail subapp

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

subapps:
  detail:
    contentConnector:
      workspace: contacts
Node nameValue
 subApps
 

 detail

 

 contentConnector

 

 workspace

contacts

 

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.

../apps/fs-browser-app/fs-browser.yaml
subApps:
  browser:
    contentConnector:
      class: info.magnolia.filesystembrowser.app.contentconnector.FSContentConnectorDefinition
      rootFolder: /Users/jsmith/Documents/magnolia
Node nameValue
 fs-browser-app
 

 apps

 

 fs-browser

 

 subApps

 

 browser

 

 contentConnector

 

 class

info.magnolia.filesystembrowser.app.contentconnector.FSContentConnectorDefinition

 rootFolder

/Users/jsmith/Documents/magnolia

Credits:

2 Comments

  1. defaultOrder is not optional, if one defines a list or a search workbench presenter. info.magnolia.ui.workbench.container.AbstractJcrContainer.constructJCRQuery requires it to be around as currently implemented in 5.5.5.

    1. Thanks for reporting this. I have created MGNLUI-4282 - Getting issue details... STATUS to address the issue.