Part I - 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.

Getting Magnolia

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

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.

└── bookshelf
    ├── decorations
    ├── dialogs
    │   ├── components
    │   └── pages
    ├── i18n
    │   └── bookshelf-messages_en.properties
    ├── includes
    │   └── README.txt
    ├── README.md
    ├── templates
    │   ├── components
    │   └── pages
    └── webresources

Creating the app

Change to the bookshelf folder and enter the following command:

mgnl create-app bookshelf-app

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

└── bookshelf
    ├── apps
    │   └── bookshelf-app.yaml
    ├── contentTypes
    │   └── bookshelf-app.yaml
    ├── decorations
    ├── dialogs
    │   ├── components
    │   └── pages
    ├── i18n
    │   └── bookshelf-messages_en.properties
    ├── includes
    │   └── README.txt
    ├── README.md
    ├── templates
    │   ├── components
    │   └── pages
    └── webresources

The bookshelf-app.yaml file in the apps subfolder is an app descriptor, while the bookshelf-app.yaml file in the contentTypes subfolder contains a content type definition for the app. In the next steps, you modify these files to meet the design requirements for the Bookshelf app.

Customizing the content type definition

In the contentTypes folder, open the bookshelf-app.yaml and replace its content with the following:

datasource:
  workspace: books
  rootPath: /
  namespaces:
    lib: https://www.magnolia-travel.com/jcr/1.0/lib
  autoCreate: true

model:
  nodeType: lib:book
  properties:
    - name: authors
    - name: ed
      type: Boolean
    - name: title
    - name: description
    - name: publisher
    - name: publish_date
      type: Date
    - name: isbn13  

• In the datasource section (lines 1-6), you define how content type items are persisted. For more details see the Content type Data source definition page.
• In the model section (lines 8-19), you define the node type and the properties of the new content item for the Bookshelf app. 

For the properties, the default String type is used when no other type is supplied. The definition of the Bookshelf app requires that we change the type in case of the ed and publish_date properties:

• Line 13: 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).
• Line 18: Set the data type of the publish_date property to Date so that the value would be stored in the JCR as calendar object.

For more details, see the Content type Model definition page.

Customizing the app descriptor

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

!content-type:bookshelf-app
name: bookshelf-app

• Line 1: The app descriptor instructs the app generator to construct the app from the bookshelf-app content type definition.
• Line 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, you can check in the Definitions app that the app's definitions have been loaded by Magnolia:

Starting the app

Magnolia adds a tile for your new app to the App launcher automatically when registering the app. However, to make the tile appear in the App launcher, you must first restart your Magnolia session once by logging out and logging in again. For further details see App launcher layout.

To start using the app, login to Magnolia again and click the bookshelf-app tile in the App launcher.

 Congratulations! The content app is up and running now and the editors could already start using by cataloging new books in it. 

Continue to the last page of this tutorial, where you fine-tune this basic app to its final form.