Example app descriptor: content-tags.yaml

This page describes in more detail a configuration file that defines a Magnolia app called Tags. The app provides:

  • A browser subapp, for listing and managing content tags.

  • A detail subapp, for viewing tag content.

You can see and test the app in the Magnolia online demo.

Content tagging can be enabled in a new content app or in one that already exists. For more details, see How to enable content tags for a content app.

Overview

The app’s configuration is written in YAML and adheres to Magnolia’s app descriptor schema, as outlined in the App descriptor.

  • It defines a ContentAppDescriptor with two subapps: browser and detail.

  • The app interacts with a JCR workspace named tags and supports two node types: mgnl:tag and mgnl:folder.

  • The structure is modular, with reusable definitions within the same file for the datasource and action configurations.

Complete descriptor

Click to see the full configuration

content-tags.yaml
icon: icon-tag-2-app
appClass: info.magnolia.ui.framework.app.BaseApp
class: info.magnolia.ui.contentapp.configuration.ContentAppDescriptor
datasource: &datasource
  $type: jcrDatasource
  workspace: tags
  allowedNodeTypes:
    - mgnl:tag
    - mgnl:folder

subApps:
  browser:
    class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor
    actions:
      createTag:
        icon: icon-add-item
        $type: openDialogAction
        dialogId: content-tags-ui:createTag
        availability:
          writePermissionRequired: true
          root: true
      showDependencies:
        icon: icon-switch-preview
        $type: openDetailSubappAction
        appName: content-tags
        subAppName: detail
        viewType: edit
        availability:
          writePermissionRequired: true
          nodeTypes:
            tag: mgnl:tag
      rename:
        icon: icon-edit
        $type: openDialogAction
        dialogId: content-tags-ui:renameTag
        availability:
          writePermissionRequired: true
      confirmDeletion:
        successActionName: delete
        class: info.magnolia.contenttags.ui.dependencies.TaggingAwareConfirmationActionDefinition
        recursive: false
        icon: icon-delete
        availability:
          writePermissionRequired: true
          multiple: true
      delete:
        class: info.magnolia.contenttags.ui.app.action.DeleteTagsActionDefinition
    actionbar:
      defaultAction: showDependencies
      sections:
        - name: tag
          groups:
            - name: editActions
              items:
                - name: showDependencies
                - name: rename
                - name: confirmDeletion
          availability:
            nodeTypes:
              tag: mgnl:tag
        - name: folder
          availability:
            nodeTypes:
              folder: mgnl:folder
        - name: root
          groups:
            - name: addActions
              items:
                - name: createTag
          availability:
            root: true
    workbench:
      contentViews:
        - name: tree
          $type: treeView
          multiSelect: true
          dropConstraint:
            $type: jcrDropConstraint
            primaryNodeType: mgnl:tag
          columns:
            - name: jcrName
              $type: jcrTitleColumn
              editable: true
              nodeTypeToIcon:
                mgnl:tag: icon-people
                mgnl:folder: icon-folder
              editor:
                availability:
                  nodes: true
                  properties: true
            - name: mgnl:lastModified
              $type: dateColumn
              editable: false
        - name: list
          $type: listView
          columns:
            - name: jcrName
              $type: jcrTitleColumn
              editable: true
              nodeTypeToIcon:
                mgnl:tag: icon-people
                mgnl:folder: icon-folder
              editor:
                availability:
                  nodes: true
                  properties: true
            - name: path
              $type: jcrPathColumn
              editable: falase
            - name: mgnl:lastModified
              $type: dateColumn
              editable: false

  detail:
    actions:
      cancel:
        $type: closeAction
      commit:
        $type: commitAction
    class: info.magnolia.ui.contentapp.detail.DetailDescriptor
    itemProvider:
      $type: jcrNodeFromLocationProvider
      workspace: tags
      nodeType: mgnl:tag
    datasource:
      <<: *datasource
      describeByProperty: jcrName
    form:
      properties:
        - name: referencesTo
          class: info.magnolia.contenttags.ui.dependencies.TaggingAwareDependenciesViewDefinition
          referencesTo: true

Configuration components

Core app definition

App classes, icon

Defines the app’s metadata and base class.

icon: icon-tag-2-app (1)
appClass: info.magnolia.ui.framework.app.BaseApp (2)
class: info.magnolia.ui.contentapp.configuration.ContentAppDescriptor (3)
1 Specifies the UI icon (icon-tag-2-app) for the app in Magnolia’s App launcher.
2 Uses the BaseApp, a standard Magnolia class for app initialization.
3 Uses the ContentAppDescriptor, indicating this is a content app designed to manage JCR-based content.

Data source configuration

Configures the data source for the app, connecting it to the JCR repository in this example.

datasource: &datasource (1)
  $type: jcrDatasource (2)
  workspace: tags (3)
  allowedNodeTypes: (4)
    - mgnl:tag
    - mgnl:folder
1 The &datasource is a YAML anchor that allows reuse of this configuration in the detail subapp, promoting DRY principles.
2 Specifies a JCR data source.
3 Points to the tags workspace in the JCR repository.
4 Restricts the app to handle mgnl:tag (tags) and mgnl:folder (organizational folders) node types.

Subapps

Each subApps configuration node defines the main UI for browsing and managing tags.

Browser subapp

The browser subapp configuration includes actions, an action bar, and a workbench with content views.

subApps:
  browser:
    class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor (1)
1 The class indicates this subapp is a browser interface for listing and interacting with content.
Action definitions

The browser subapp defines five actions:

    actions: (1)
      createTag:
        icon: icon-add-item
        $type: openDialogAction
        dialogId: content-tags-ui:createTag
        availability:
          writePermissionRequired: true
          root: true
      showDependencies: (2)
        icon: icon-switch-preview
        $type: openDetailSubappAction
        appName: content-tags
        subAppName: detail
        viewType: edit
        availability:
          writePermissionRequired: true
          nodeTypes:
            tag: mgnl:tag
      rename: (3)
        icon: icon-edit
        $type: openDialogAction
        dialogId: content-tags-ui:renameTag
        availability:
          writePermissionRequired: true
      confirmDeletion: (4)
        successActionName: delete
        class: info.magnolia.contenttags.ui.dependencies.TaggingAwareConfirmationActionDefinition
        recursive: false
        icon: icon-delete
        availability:
          writePermissionRequired: true
          multiple: true
      delete: (4)
        class: info.magnolia.contenttags.ui.app.action.DeleteTagsActionDefinition
1 Opens the content-tags-ui:createTag dialog for creating new tags. Requires write permissions and is available at the root level.
2 Opens the detail subapp in the edit mode to show tag dependencies. Available for mgnl:tag nodes with write permissions.
3 Opens the content-tags-ui:renameTag dialog for renaming tags. Requires write permissions.
4 Handles tag deletion with a confirmation step, triggering the delete action itself. Supports multiple selections and requires write permissions.
Action bar configuration

Configures the Action bar, which displays available actions based on context.

actionbar:
  defaultAction: showDependencies (1)
  sections: (2)
    - name: tag (3)
      groups:
        - name: editActions
          items:
            - name: showDependencies
            - name: rename
            - name: confirmDeletion
      availability:
        nodeTypes:
          tag: mgnl:tag
    - name: folder (4)
      availability:
        nodeTypes:
          folder: mgnl:folder
    - name: root (5)
      groups:
        - name: addActions
          items:
            - name: createTag
      availability:
        root: true
1 Sets the default action when a tag is selected by double-clicking it.
2 Section delimitation in the Action bar.
3 Displays the editActions group (with showDependencies, rename, and confirmDeletion actions) for the mgnl:tag nodes.
4 Section for the mgnl:folder nodes.
5 Displays the addActions group (with the createTag action) at the root level.
Workbench configuration

Defines the Workbench, with content display modes (tree and list views).

workbench:
  contentViews:
    - name: tree (1)
      $type: treeView
      multiSelect: true
      dropConstraint:
        $type: jcrDropConstraint
        primaryNodeType: mgnl:tag
      columns:
        - name: jcrName
          ...
        - name: mgnl:lastModified
          ...
    - name: list (2)
      $type: listView
      columns:
        - name: jcrName
          ...
        - name: path
          ...
        - name: mgnl:lastModified
          ...
1 Defines the tree view, where multiSelect: true allows selecting multiple items, dropConstraint restricts drag-and-drop to the mgnl:tag nodes. The column definition includes the jcrName column (editable, with icons for tags and folders) and a date column (mgnl:lastModified).
2 Defines the list view. It’s similar to the tree view but includes an additional path column (path).

Detail subapp

Provides a view for displaying tag dependencies.

detail:
  actions: (1)
    cancel:
      $type: closeAction
    commit:
      $type: commitAction
  class: info.magnolia.ui.contentapp.detail.DetailDescriptor (2)
  itemProvider: (3)
    $type: jcrNodeFromLocationProvider
    workspace: tags
    nodeType: mgnl:tag
  datasource: (4)
    <<: *datasource
    describeByProperty: jcrName
  form: (5)
    properties:
      - name: referencesTo
        class: info.magnolia.contenttags.ui.dependencies.TaggingAwareDependenciesViewDefinition
        referencesTo: true
1 Defines the cancel and commit form actions.
2 The class that indicates that this is a detail subapp.
3 Fetches the mgnl:tag nodes from the tags workspace.
4 Reuses the &datasource YAML anchor, with the describeByProperty: jcrName definition to display the tag’s name.
5 A form definition to show tag dependencies. The form content is created using a custom TaggingAwareDependenciesViewDefinition class from the Content Tags module. The class extends the DependenciesViewDefinition of the Content Dependencies module, where the boolean referencesTo property comes from.

Related configuration files

  • Dialogs: The dialogs folder contains createTag.yaml, renameTag.yaml, and setOrAdd.yaml, which define the UI forms for tag creation, renaming, and possibly adding tags to other content.

  • i18n: The i18n folder includes translation files for multiple languages, ensuring the app supports internationalization.

content-tags-ui
├── apps/
│   └── content-tags.yaml
├── dialogs/
│   ├── createTag.yaml
│   ├── renameTag.yaml
│   └── setOrAdd.yaml
└── i18n/
    ├── content-tags-ui-messages_backend_en.properties
    ├── content-tags-ui-messages_backend_de.properties
    ...
    └── content-tags-ui-messages_backend_<locale-tag>.properties
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