How to enable content tags for a content app

This page explains how to enable content tagging in a content app so that authors can add tags to content items. Content tagging can be enabled in a new content app or in one that already exists.

The configuration code snippets displayed in the examples on this page are based on content tagging configuration applied to the Authors app which is part of our demonstration bookshelf module. You can clone the module with this command:

git clone -b withAuthorCatalog https://git.magnolia-cms.com/scm/documentation/bookshelf.git

In an existing content app, you can also use definition decoration to enable content tagging.

Content tags can be edited:

  • In the browser subapp of your app.

  • Through a dedicated tags field (info.magnolia.contenttags.ui.field.TagsFieldDefinition) in the detail view of a content item.

  • Using the Tags app. To be able to do this, you need to register the app’s workspace in the configuration of the content-tags-core module. Registering it there ensures that dependencies are managed across workspaces.

Before you start customizing your app, make sure your bundle contains the Content tags module’s magnolia-content-tags-core and magnolia-content-tags-ui submodules. The third submodule, magnolia-content-tags-ui-compatibility, is not mandatory. It only handles 5 UI configurations in Magnolia 6 UI. If you wish to create or modify a 5 UI definition for content tagging, see the How to enable content tags for a content app - 5 UI page.

Adding a tags column to the browser subapp

Configure a new column to display content tags in the browser subapp of your app. Add the following tree and list content view configurations to the workbench node of the browser subapp of your content app descriptor:

<path-to-your-light-module>/apps/<app-name>.yaml

      contentViews:
        tree:
          columns:
            tags: &tags
              name: mgnl:tags
              $type: columnComponent
              type: java.util.Collection
              editor:
                field:
                  $type: tokenField
                  comboBox:
                    datasource:
                      $type: jcrDatasource
                      workspace: tags
                      allowedNodeTypes:
                        - mgnl:tag
        list:
          columns:
            tags: *tags

image

Configure an i18n property to assign a custom title to the tags column. The property’s name would be <app-name>.browser.views.mgnl-tags.label and its value is in this case set to Genre tags.

Use an i18n message bundle for all i18n labels or descriptions of your content app.

Creating a dialog definition for tag editing

To edit a content item’s tags directly in the app’s browser subapp, you need to create a new action for the subapp and a dialog that will be called when you click that action.

image image

First, create the dialog definition and add it to the dialogs folder of your module. In this example, the dialog’s name is modifyTags.yaml:

<path-to-your-light-module>/dialogs/modifyTags.yaml

form:
  properties:
    - name: mgnl:tags
      class: info.magnolia.contenttags.ui.field.TagsFieldDefinition
actions:
  cancel:
    $type: closeAction
    availability:
      multiple: true
  commit:
    class: info.magnolia.contenttags.ui.form.action.AddTagsActionDefinition
    availability:
      multiple: true
footerLayout:
  $type: defaultEditorActionLayout
  primaryActions:
    cancel: cancel
    commit: commit

The dialog’s ID will be <module-name>:modifyTags.

Adding edit tag action to the action bar

Add the following actions and actionbar definitions to the browser node in the app descriptor of your app. The edit tag dialog is called through the dialogId: <module-name>:modifyTags property.

<path-to-your-light-module>/apps/<app-name>.yaml

    actions:
      addTags:
       class: info.magnolia.contenttags.ui.dialog.OpenTagDialogActionDefinition
       dialogId: <module-name>:modifyTags
    actionbar:
      sections:
        item:
          groups:
            editActions:
              items:
                addTags:
                  name: addTags

Again, use an i18n property in a message bundle to set the new action’s label, for example <app-name>.browser.actions.addTags.label=Edit genre tags.

Alternatively, a dialog for editing content tags already exists in the content-tags-integration module. You can use it in your app by referencing its ID. Below, the change can be seen on line 4. The i18n keys for the labels in this dialog will be different, though.

<path-to-your-light-module>/apps/<app-name>.yaml

    actions:
      addTags:
       class: info.magnolia.contenttags.ui.dialog.OpenTagDialogActionDefinition
       dialogId: content-tags-integration:modifyTags
    actionbar:
      defaultAction: editItem
      sections:
        item:
          name: item
          groups:
            editActions:
              name: editActions
              items:
                addTags:
                  name: addTags

Adding a field for tag editing to the detail subapp

To edit content tags through a dedicated field in the detail subapp of your app, add the following section to the properties node of the detail subapp’s form definition:

<path-to-your-light-module>/apps/<app-name>.yaml

        mgnl:tags:
          class: info.magnolia.contenttags.ui.field.TagsFieldDefinition

This definition will create a field where users can edit content tags attached to the content item:

image

Register content app’s workspace as a taggable workspace

This step is optional but recommended. It ensures JCR data sanity and improves user experience. It also makes sure that when you intend to delete a tag in the Tags app, the system:

  • Checks for occurrences of these tags in registered workspaces.

  • Shows notifications about these occurrences.

  • If you agree, removes the references of the tags on content items in registered workspaces.
    image

    To register the workspace, add a node to /modules/content-tags-core/config/taggableWorkspaces
Property Description

taggableWorkspaces

required

The root node for registration of content dependencies.

     <node-name>

required

Arbitrary name to register one workspace as taggable.

         appMapping

required

Use this pattern apps:<app-name>:<detail-subapp-name>

         workspace

required

The name of the workspace of a content app.

Feedback