App Launcher layout definition

The grouping and coloring in the App Launcher layout help you to identify apps based on your role (marketeer/editor vs. developer apps). All your apps are available at a glance after you log in. The layout property configures all the rows, groups, and apps.

App Launcher Modern layout

The App Launcher layout includes different colored backgrounds:

A green background indicates favorite apps
A gray background indicates marketeer/editor apps
A white background indicates developer apps

You can only use YAML to configure the App Launcher for the layout property. Everything is defined in the config.yaml file, and you can’t configure anything using JCR.

Example definitions

The App Launcher layout is a yaml-based module configuration. To modify the layout, you can decorate it runtime in one of your light modules: <LIGHT_MODULE>/decorations/admincentral/config.yaml. See Example layout definition decorations for more details.

To see the final state of the configuration in memory after all decorations are applied, look in the Definitions app at this location: /modules/admincentral/config/layout. Selecting the layout node and clicking the Show definition decorators action lets you see which decorations were applied in which order.

Apps configured in the new App Launcher layout will cause entries to appear in the log. To keep the log tidy, we recommend adjusting your App Launcher layout configuration and removing any apps you don’t use.

<LIGHT_MODULE>/decorations/admincentral/config.yaml

layout:
  defaultGroup: custom
  hiddenApps:
    contacts-v8: contacts-v8
    dam-chooser: dam-chooser
    preview: preview
    assets: assets
    categories: categories
    notifications: notifications
    tasks-app: tasks-app
    personas: personas
    tourCategories: tourCategories
    pages: pages
    segmentation: segmentation
    ecommerce-category-chooser: ecommerce-category-chooser
    ecommerce-connection-chooser: ecommerce-connection-chooser
    ecommerce-product-chooser: ecommerce-product-chooser
  groups:
    - name: content
      apps:
        - name: pages-app
        - name: dam
        - name: stories
        - name: tours
        - name: contacts
    - name: marketing
      apps:
        - name: analytics
        - name: campaigns
        - name: marketing-tags
        - name: abn-testing
    - name: personalisation
      apps:
        - name: personas-app
        - name: segmentation-app
        - name: preview-app
    - name: categorisation
      apps:
        - name: content-tags
        - name: categories-app
    - name: translation
      apps:
        - name: pages-translation
    - name: development
      apps:
        - name: jcr-browser-app
        - name: marketing-tags
        - name: content-tags
        - name: backup
        - name: mail
        - name: cacheTools
        - name: logTools
        - name: publishing
        - name: tools
        - name: jcr-tools
        - name: pages-translation
        - name: messages
        - name: groovy
        - name: sample
        - name: graphql
        - name: restclient
        - name: resources
        - name: site
        - name: configuration
        - name: definitions-app
    - name: admin
      apps:
        - name: security
        - name: password-manager
        - name: visitors
        - name: cookies
        - name: about
        - name: ecommerce
        - name: rssAggregator
    - name: custom
      apps: []
  rows: (1)
    - name: one
      cssClass: editor
      groups:
        content: content
        marketing: marketing
    - name: two
      cssClass: editor
      groups:
        - personalisation
        - categorisation
        - translation
    - name: three
      cssClass: editor
      groups:
        - custom
    - name: four
      cssClass: developer
      groups:
        - development
        - admin

1	Notice that the `rows` section does not list any apps in the new layout definition, as shown in the example YAML above.

App Launcher Modern layout

Migrating from Magnolia 6.2?

You must configure the layout property according to the example definition below.

layout:
    defaultGroup: custom
    hiddenApps:
        - contacts-v8
        - dam-chooser
        - preview
        - assets
        - categories
        - notifications
        - tasks-app
        - personas
        - tourCategories
        - pages
        - segmentation
        - ecommerce-category-chooser
        - ecommerce-connection-chooser
        - ecommerce-product-chooser
    rows: (1)
        - cssClass: editor
          groups: (2)
            - name: content
              apps:
                - pages-app
                - dam
                - stories
                - tours
                - ecommerce
                - contacts
            - name: marketing
              apps:
                - analytics
                - campaigns
                - marketing-tags
                - abn-testing
        - cssClass: editor
          groups:
            - name: personalisation
              apps:
                - personas-app
                - segmentation-app
                - preview-app
            - name: categorisation
              apps:
                - content-tags
                - categories-app
            - name: translation
              apps:
                - pages-translation
        - cssClass: editor
          groups:
            - name: custom
        - cssClass: developer
          groups:
            - name: configuration
              apps:
                - jcr-browser-app
                - marketing-tags
                - content-tags
                - backup
                - mail
                - cacheTools
                - logTools
                - publishing
                - tools
                - jcr-tools
                - pages-translation
                - messages
                - groovy
                - sample
                - graphql
                - restclient
                - resources
                - site
                - configuration
                - definitions-app
            - name: admin
              apps:
                - security
                - password-manager
                - visitors
                - cookies
                - about
                - ecommerce
                - rssAggregator

1	The layout definition uses the keyword `layout` followed by `rows` indented.
2	One `groups` line corresponds to a row in the layout (defined under the `rows` property). The number of items listed in a group defines how many columns are displayed per row.

While the layout approach shown above allows you to see the definition easily, it is challenging to decorate. For instance, if you want to move the personalisation group from the second to the third row, you must define its apps again. In addition, you have to use the correct row number shown in the Definitions app below.

layout:
  rows:
    1:
      groups: !override
        - name: categorisation
        - name: translation
    2:
      groups: !override
        - name: personalisation
          apps:
            - personas-app
            - segmentation-app
            - preview-app

App Launcher 6.2.22 layout decoration

The updated layout definition makes decorations easier.

App Launcher properties

Property Description

Property	Description
`defaultGroup`	optional, default is `custom` Defines the group where a new app is added automatically, provided the app has not been added to another group of the App Launcher. During installation, Magnolia sets the value of the `defaultGroup` property to `custom`. During an update, it is set to `custom` only if the property has not been set already.
`hiddenApps`	optional List of apps to be hidden in the App Launcher.
`<app-name>`	optional Name of an app that should not be shown in the App Launcher. The name of the property is arbitrary and specified as a key-value pair such as `tasks-app: tasks-app`. Example: Change `pages` to `pages-app` to fall back to the compatibility changes in the App Launcher.
`groups`	required List of app groups.
`<group‑name>`	required App group name. For example, a group called content is specified by `name: content`
`label`	optional App group label. The label defined here is displayed in the App Launcher. An example of labeling a group `MY CONTENT GROUP` is given below. `groups: - name: content label: MY CONTENT GROUP apps: - name: pages-app - name: dam`
`apps`	required List of apps in the group.
`<app‑name>`	required Name of an app that belongs to the group. The name must match the name given in the app configuration (for example, `pages`).
`permissions`	optional Defines which users can see the group in the App Launcher. This allows you to provision the group to a limited number of users in your organization. Two examples are given below and more information about app permissions can be found here. `- name: admin apps: - name: security - name: password-manager - name: visitors - name: cookies - name: about - name: ecommerce - name: rssAggregator permissions: roles: - editor` `- name: admin apps: - name: security - name: password-manager - name: visitors - name: cookies - name: about - name: ecommerce - name: rssAggregator permissions: class: info.magnolia.cms.security.operations.VoterBasedConfiguredAccessDefinition voters: allowedRoles: class: info.magnolia.voting.voters.RoleBaseVoter roles: travel-demo-editor: travel-demo-editor travel-demo-publisher: travel-demo-publisher roles: - editor`
`rows`	required The rows in the App Launcher layout are named `one`, `two`, `three`, `four`, and so forth for your convenience. Furthermore, they are specified after the groups. Inside each row, the `groups` belonging to it are listed (see Example definitions). The number of groups defines how many columns are displayed per row. The column spacing is calculated automatically based on those definitions. You can only include, at most, four groups in a row. In case more groups are defined, the extra groups are discarded.
`<row‑name>`	required Row name. For example, the first row is named `one`, and is specified as `name: one`.
`cssClass`	required Defines a group’s background color. There are two possible values: `editor` and `developer`. Editor groups have a gray background, while developer groups have a white background (see Example definitions).
`displayed`	optional It is possible to hide a row by setting the displayed property to false: `displayed: false`.

defaultGroup

optional, default is custom

Defines the group where a new app is added automatically, provided the app has not been added to another group of the App Launcher.

During installation, Magnolia sets the value of the defaultGroup property to custom. During an update, it is set to custom only if the property has not been set already.

hiddenApps

optional

List of apps to be hidden in the App Launcher.

<app-name>

optional

Name of an app that should not be shown in the App Launcher. The name of the property is arbitrary and specified as a key-value pair such as tasks-app: tasks-app.

Example:

Change pages to pages-app to fall back to the compatibility changes in the App Launcher.

groups

required

List of app groups.

<group‑name>

required

App group name. For example, a group called content is specified by name: content

label

optional

App group label. The label defined here is displayed in the App Launcher. An example of labeling a group MY CONTENT GROUP is given below.

groups:
  - name: content
    label: MY CONTENT GROUP
    apps:
      - name: pages-app
      - name: dam

apps

required

List of apps in the group.

<app‑name>

required

Name of an app that belongs to the group. The name must match the name given in the app configuration (for example, pages).

permissions

optional

Defines which users can see the group in the App Launcher. This allows you to provision the group to a limited number of users in your organization. Two examples are given below and more information about app permissions can be found here.

- name: admin
  apps:
    - name: security
    - name: password-manager
    - name: visitors
    - name: cookies
    - name: about
    - name: ecommerce
    - name: rssAggregator
  permissions:
    roles:
      - editor

- name: admin
  apps:
    - name: security
    - name: password-manager
    - name: visitors
    - name: cookies
    - name: about
    - name: ecommerce
    - name: rssAggregator
  permissions:
    class: info.magnolia.cms.security.operations.VoterBasedConfiguredAccessDefinition
    voters:
      allowedRoles:
        class: info.magnolia.voting.voters.RoleBaseVoter
        roles:
          travel-demo-editor: travel-demo-editor
          travel-demo-publisher: travel-demo-publisher
      roles:
        - editor

rows

required

The rows in the App Launcher layout are named one, two, three, four, and so forth for your convenience. Furthermore, they are specified after the groups. Inside each row, the groups belonging to it are listed (see Example definitions).

The number of groups defines how many columns are displayed per row. The column spacing is calculated automatically based on those definitions. You can only include, at most, four groups in a row. In case more groups are defined, the extra groups are discarded.

<row‑name>

required

Row name. For example, the first row is named one, and is specified as name: one.

cssClass

required

Defines a group’s background color. There are two possible values: editor and developer. Editor groups have a gray background, while developer groups have a white background (see Example definitions).

displayed

optional

It is possible to hide a row by setting the displayed property to false: displayed: false.

Example layout definition decorations

The App Launcher layout definition can take advantage of many decorations. Below we provide some use cases that enable you to configure your App Launcher layout using decorations.

You must put decorations in a decorations folder inside one of your modules in the light-modules folder. The config.yaml file belongs in an admincentral folder directly under the decorations folder.

Decorations folder location

Moving an app from one group to another: for example, the YAML decoration below would move the bookshelf-app from the custom group to the marketing group.
```
layout:
  groups:
    - name: marketing
      apps:
      - name: bookshelf-app
```
Hiding apps using the hiddenApps property: for example, the configuration app is hidden in the YAML decoration below.
```
layout:
  hiddenApps:
    configuration: configuration
```
Removing a row from the layout: such as taking away the first row one in the decoration below.
```
layout:
  rows:
    - name: one
      displayed: false
```
Splitting two groups in one row over two rows: for instance, separating the admin and developer groups over two rows using !override instead of the default placement, as shown below.
```
layout:
  rows:
    - name: four
      groups: !override
        development: development
    - name: five
      cssClass: developer
      groups:
        admin: admin
```

App Launcher layout definition

Example definitions

App Launcher properties

Example layout definition decorations

Location

Main doc sections