My first content app

This tutorial guides you through the process of creating a content app in Magnolia. The app you create is called the Bookshelf app and you create it as a Magnolia light module from a custom content type definition.


Tutorial overview

The tutorial consists of three parts:

Going through the tutorial you learn:

  • How to define content types and use them to quickly create a Content app.

    A Content app is a specialized app type for managing structured content. The content app user interface consists of a browser subapp and one or more detail subapps. Content apps make it easy to enter items such as products or events. Many native Magnolia apps such as Tours and Contacts are content apps. Because this app style is used often, the framework provides convenience classes to make building a content app faster.

  • The basics of configuring fields and setting field validators.

  • How to override configuration properties.

  • How to make the elements of the app’s UI ready for internationalization.

If you want to skip the tutorial and install the final app immediately, clone the repository containing the ready-made Bookshelf app as a light module directly into your Magnolia light module folder with the command:

git clone -b master --single-branch https://bitbucket.org/magnolia-cms/bookshelf.git

Bookshelf app use case

The Bookshelf app you create in this tutorial is an example of a content app. It is a simple book catalog allowing the user to store basic bibliographic data about each book such as its title, the names of the author(s), the publisher’s name, or the ISBN-13 number. The app also allows you to group selected book items into folders called shelves in the app.

The subapps in the Bookshelf app

The Bookshelf app contains subapps:

Book Browser

In the Book Browser subapp, you can:

  • Browse the book catalog.

  • Add, rename and delete books.

  • Add, rename and delete shelves (folders for organizing books).

Book Detail

The Book Detail subapp is a place where you can create and edit a book’s bibliographic properties using text fields and a checkbox field.

Book properties

For each book item, the Bookshelf app can store and retrieve the following content properties:

  • Short cataloging name (a required content property).

  • Full book title.

  • Author(s)’ name(s).

  • Whether the author(s) role is editorial or not.

  • Book description.

  • Publisher’s name.

  • Book publication date.

  • ISBN-13 number.

Bookshelf app and Magnolia content types

The Bookshelf app is based on Magnolia content types.

The books workspace

Magnolia stores content in the magnolia repository, a JCR repository that is divided into workspaces. The Bookshelf app stores all books in a new workspace called books.

Custom lib:book node type

In the books workspace, each book is a custom lib:book node type defined specifically for this tutorial.

Content type properties

Each book of the lib:book type can have the following content properties:

Property Usage Type Restrictions

authors

Name(s) of the author(s) of the book.

String

none

ed

The property to store the true value if the primary role of the Author(s) is editorial.

Boolean

none

title

Official book title.

String

none

description

Description of what the book is about.

String

5000 characters max.

publisher

Book publisher’s name.

String

none

publish_date

Date of publication of the book.

Date

Display format:

YYYY-MM-DD

isbn13

International Standard Book Number in the 13-character variant.

String

13 characters

  • The first 12 characters can only be numerals, the last character can be a numeral or X.

  • The first three numerals can only be either 978 or 979.

  • We don’t need to perform the validity check against the number’s checksum digit.

The name property

When you create an app from a content type definition, the name property is generated automatically by Magnolia. The JCR node name is then automatically deduced from it.

We make use of this auto-generated name property in the Bookshelf app by:

  • Setting it to be a required property.

  • Referring to it via the Cataloging name label in user dialogs.

  • Using it for creating a short and hyphenated book identifier (JCR node name) such as Hawking-2005-God-Created-the-Integers.

    Therefore, in the Bookshelf app, the data in the Cataloging name field should be entered using the following syntax:

    <first-author's-surname> <publication-year> <short-form-of-the-book's-full-title>

    For example, Hawking 2005 God Created the Integers.

    Magnolia automatically replaces the spaces with hyphens when creating a node name from the name property.


Feedback

DX Core

×

Location

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