This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

Page tree
Skip to end of metadata
Go to start of metadata

This is the third and final part of the My first content app tutorial. This page describes how to change the configuration of the basic Bookshelf app to its final form as specified in the use case.

Change the app descriptor

First you change the bookshelf-app.yaml app descriptor, to:

  • Add an app icon
  • Fine-tune the properties
  • Remove the thumbnail view

Open the file, located in the bookshelf light module apps folder, and edit it as follows:

name: bookshelf-app
icon: icon-content-app
            name: bookDetailsTab
                fieldType: checkbox
                type: Boolean
                rows: 2
                rows: 5
                maxLength: 5000
                fieldType: date
                type: Date
                maxLength: 13
                  - name: isbn13
                    class: info.magnolia.ui.form.validator.definition.RegexpValidatorDefinition
                    pattern: '97(8|9)[0-9]{9}(\d|X)'
      contentViews: !override

Changing the app icon

On line 3 above, you assign the Bookshelf app a new icon called icon-content-app, which symbolizes a bookshelf.

Fine-tuning the properties in the detail subapp

  • Line 10: Give the default tab a new name.
    The app generator creates the default tab in the Book detail subapp. You assign the tab (node) a more meaningful name, bookDetailsTab, which makes it easier to address the app components and i18n labels.
  • Lines 12-14: Change the ed property.
    You change the field type of this property from the default text to the checkbox field type. You also change the type of the property to Boolean, since it is more appropriate in regard to the values the system can store (truefalse). Note that, alternatively, you can define the type in the content type definition file.
  • Lines 15 and 16: Set the height of the field for the title property.
    You set the rows field property of the title content type property to 2. Some book titles are longer and in most cases a two-row text field allows the user to read the whole title compared to just a one-row field.
  • Lines 17-19: Define the height and maximum length of the field for the  description property.
    Similarly, you set the number of rows for the description property to 5.
    You also limit the maximum length of a description to 5 000 characters to comply with data import restrictions of the cloud service, in case the user decides to transfer data between the Bookshelf app and
  • Lines 20-22: Change the publish_date property.
    Set the field type to date to help the user find a book publication date with a pull-down calendar.
    Set the data type to Date so that the value is stored in the JCR as calendar object.
  • Lines 23-28: Length setting and a validator related to the isbn13 property.
    We set the maxLength property to 13 characters to provide the user with a digit counter for entering the ISBN-13 number.
    On lines 25-28 we add a regex-based field validator for the ISBN-13 field. This validation makes sure that the number entered complies with the basic syntax of ISBN-13 numbers.

Hiding the thumbnail view

By default the app generator creates three view types in the Browser subapp:

  • Tree view
  • List view
  • Thumbnail view

Since we do not provide book cover images, the thumbnail view is not needed. The part at lines 29-33 overrides the default using the !override directive and renders only the tree and list views.

Adding an i18n message bundle

Now add and polish the i18n labels and descriptions for the elements of the UI in the Bookshelf app by adding a new message bundle to the bookshelf light module.

What is a message bundle?

A message bundle (resource bundle in Java) is a collection of .properties files. Each file contains key-value pairs of translated user interface text such as labels and messages. The keys in all files of the same bundle are identical but the values are language specific translations.

A message bundle must contain at least one .properties file. The files are named after the language (locale): <bundle-name>_<locale>.properties, for example Every Magnolia module should provide its own message bundle. If a module installs several apps, each app should have its own message bundle.

Since you've assigned a new name ( bookDetailsTab) to the default tab in the detail subapp, you have to create new labels even for the message keys that supply label values from the magnolia-ui-framework module.

In the i18n subfolder, create a new file called and save it with the following content (click the filename link to see the content):
# App label

# Book browser subapp labels.
bookshelf-app.browser.label=Book Browser
bookshelf-app.browser.actions.addItem.label=Add book
bookshelf-app.browser.actions.confirmDeletion.label=Delete book
bookshelf-app.browser.actions.editItem.label=Edit book data
bookshelf-app.browser.actions.rename.label=Rename book
bookshelf-app.browser.actions.addFolder.label=Add shelf
bookshelf-app.browser.actions.confirmDeleteFolder.label=Delete shelf
bookshelf-app.browser.actions.editFolder.label=Rename shelf
bookshelf-app.browser.actions.moveFolder=Move shelf
bookshelf-app.browser.actions.confirmDeleteFolder.confirmationHeader=Delete {0,choice,1#this shelf|1< these {1} shelves}?
bookshelf-app.browser.actions.confirmDeleteFolder.confirmationMessage={0,choice,1# This shelf|1< These {1} shelves} and all {1,choice,1#its|1< their} sub-items will be marked for deletion. name or book cataloging name name
bookshelf-app.browser.views.listview.path.label=Bookshelf location

# Book detail subapp labels and descriptions.
bookshelf-app.bookDetailsTab.label=Book Details name field is required. Its value is used to create a unique, hyphenated book cataloging name which is visible in the BOOK BROWSER subapp and under which the book is stored in the <i>books</i> workspace.<br/><br/>A hint: Use the following pattern to create the cataloging name:<br/><br/><pre>&lt;first-author's-surname&gt; &lt;publication-year&gt; &lt;short-form-of-the-book's-full-title&gt;</pre>
bookshelf-app.bookDetailsTab.ed.label=Author(s) in editorial role
bookshelf-app.bookDetailsTab.ed.description=Check off the box if the primary role of the "Author(s)" is editorial. 
bookshelf-app.bookDetailsTab.title.label=Full title
bookshelf-app.bookDetailsTab.publish_date.label=Publication date
bookshelf-app.bookDetailsTab.publish_date.description=If you know just the year of publication, enter the date as YYYY-01-01.
bookshelf-app.bookDetailsTab.isbn13.description=If an ISBN-13 is available for the book, enter it without hyphens or spaces.
bookshelf-app.bookDetailsTab.isbn13.validation.errorMessage=The ISBN-13 number has 13 characters. The first 12 characters can only be numerals, the last character can be either a numeral or "X". The number has to begin with either 978 or 979.
bookshelf-app.detail.actions.commit=Save Book Data

To apply the new labels and descriptions, close and reopen the Bookshelf app in Magnolia.

Compare the labels in the Book Detail subapp before and after adding the message bundle:


(thumbs up) Congratulations! The Bookshelf is now ready for use.

You can tweak the app's configuration further to expand its capabilities:

  • Sample book data

    If you would like to see some book data in the app, you may either add it yourself or download it as a sample file called books.My-Good-Reads.xml from the _sampleContent folder in the bookshelf repository. Import the sample data to the Bookshelf app using the Import action in the Book browser subapp.

  • Compatibility with online library management services

    Except for the ed and name content properties, all the other properties make the design of the Bookshelf app compatible with the data nomenclature used by the service. This makes a file-based or a REST-based exchange of book data between the Bookshelf app and the Libib cloud service possible.  

  • No labels