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
NOTE: instance of
Magnolia. In this tutorial, we suppose that it is installed in a
directory called magnolia
.
If you don’t have Magnolia installed and running, go to the page called 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.
-
Open a terminal.
-
Go to the
light-modules
folder of your Magnolia installation: -
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.
Please note that 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 bookshelf-app.yaml
and replace
its content with the following:
bookshelf-app.yaml (content type definition)
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 toBoolean
, 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 toDate
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:
bookshelf-app.yaml (app descriptor)
!content-type-m5: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.
WARNING: Note the presence of them5
suffix in the content type directive. For the time being, our app will be based on UI 5 definitions. -
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.
how to launch app launcher tiles list
To see the list of the app tiles, click the app launcher icon (mgnl-app-launcher: [])to the right of the Find Bar.
To start using the app, login to Magnolia again and click the bookshelf-app tile in the App launcher.
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. You will create new label values in
Adding
an i18n message bundle on the third page of the tutorial.
👍 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.