My first content app Part II

Creating a basic content app

This page is the second part of the My first content app tutorial and describes how to configure and create a basic Bookshelf, a Magnolia content app.

The configuration is done using Magnolia content types – formal definitions for types of content in Magnolia including the properties the type may contain and its relationships to other types of content.


For development and testing, you need a running instance of Magnolia. In this tutorial, we suppose that it’s installed in a directory called magnolia.

If you don’t have Magnolia installed and running, go to Installing Magnolia through npm CLI and complete the steps described on it. Then, return and proceed from here.

Creating the bookshelf light module

Magnolia light modules usually define page, area and component templates and many more things.

In this tutorial, we use a light module called bookshelf to create a content app. The module contains both a definition of content types and the app descriptor.

  1. Open a terminal.

  2. Go to the light-modules folder of your Magnolia installation:

  3. Run the following command:

    mgnl create-light-module bookshelf

    The command creates the bookshelf light module.

    β”œβ”€β”€ decorations
    β”œβ”€β”€ dialogs
    β”‚   β”œβ”€β”€ components
    β”‚   └── pages
    β”œβ”€β”€ i18n
    β”‚   └──
    β”œβ”€β”€ includes
    β”‚   └── README.txt
    β”œβ”€β”€ templates
    β”‚   β”œβ”€β”€ components
    β”‚   └── pages
    └── webresources

Creating the app

Change to the bookshelf folder and enter the following command:

mgnl create-app bookshelf-app

The command creates the apps and contentTypes subfolders in the light module and adds the bookshelf-app.yaml file to both of them.

β”œβ”€β”€ apps
β”‚   └── bookshelf-app.yaml (1)
β”œβ”€β”€ contentTypes
β”‚   └── bookshelf-app.yaml (2)
β”œβ”€β”€ decorations
β”œβ”€β”€ dialogs
β”‚   β”œβ”€β”€ components
β”‚   └── pages
β”œβ”€β”€ i18n
β”‚   └──
β”œβ”€β”€ includes
β”‚   └── README.txt
β”œβ”€β”€ templates
β”‚   β”œβ”€β”€ components
β”‚   └── pages
└── webresources
1 The bookshelf-app.yaml file in the apps subfolder is an app descriptor.
2 The bookshelf-app.yaml file in the contentTypes subfolder contains a content type definition for the app.

As the function of the content type definition in this module is to describe a book, rename the content type definition file to book.yaml.

In the next steps, you modify these files to meet the design requirements for the Bookshelf app.

The mgnl create-app bookshelf-app command also creates a new workspace called bookshelf-app. However, as the Bookshelf app must interact with the books workspace, the name of the workspace is changed to books below.

Customizing the content type definition

In the contentTypes folder, open the book.yaml file and replace its content with the following:

book.yaml (content type definition)
datasource: (1)
  $type: jcrContentTypeDatasource
  workspace: books
  autoCreate: true

model: (2)
  nodeType: lib:book
  properties: (3)
    - name: authors
    - name: ed (4)
      type: Boolean
    - name: title
    - name: description
    - name: publisher
    - name: publish_date (5)
      type: Date
    - name: isbn13
1 Defines how the content type items are persisted.
For more details see the Content type Data source definition page.
2 Defines the node type and the properties of the new content item for the Bookshelf app.
3 Defines the app properties.
Defaults to the String type if no other type is supplied.
4 Set the type of the ed property to Boolean since it is more appropriate in regard to the values the system can store (true, false).
5 Set the data type of the publish_date property to Date so that the value would be stored in the JCR as calendar object.

Customizing the app descriptor

In the apps subfolder, open the bookshelf-app.yaml file and make sure it contains only the following two lines:

bookshelf-app.yaml (app descriptor)
!content-type:book (1)
name: bookshelf-app (2)
1 The app descriptor instructs the app generator to construct the app from the book content type definition.
2 You give the app the name bookshelf-app, under which the app is known to other resources and systems in Magnolia.

Check the app in the Definitions app

After saving the changes, run mgnl start if your Magnolia isn’t running yet. Then, go to the Definitions app on the author instance to check that the app’s definitions have been loaded by Magnolia (the bookshelf-app should appear in the apps folder).

In case the bookshelf-app isn’t there or there’s a problem notification next to it, please double-check that all your yaml files have been copied exactly as they appear in this tutorial.

Starting the app

Magnolia adds a tile for your new app to the App launcher automatically when registering the app.

App launcher tile

i18n message keys and the Name, Title and Description labels

The magnolia-ui-framework module already contains several generic i18n message keys whose values are applied as labels in the UI of the Bookshelf app.

Bookshelf detail subapp

In the last part of the tutorial, you create new label values in subsection Adding an i18n message bundle.

Congratulations! The content app is up and running now.

Continue to My first content app Part III, where you fine-tune this raw app to a final form.


DX Core



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
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.