My first content app

In this tutorial you create your first content app. Content app is a special app type that is well suited for managing custom content items such as products. The items in this example are antique cars but you can use any items you wish.  Magnolia 5.2.3

Create a module

Your content app needs to be deployed as a Magnolia module. Choose from these options depending on your skill level. 

Option 1: Clone the project in Git

Choose this option if you know how to work with a Magnolia project and Git. You get a project that you can edit it in your IDE and customize to your needs.

1. Clone the app-tutorial repository.

git clone http://git.magnolia-cms.com/git/documentation/app-tutorial.git

1. fake
2. Import the project into your IDE. Here's what the project looks like in IntelliJ IDEA:
   
3. Build the project into a JAR and deploy it to Magnolia instance. Or run the project in your IDE.

Option 2: Download the module JAR

Choose this option if you are new to Magnolia. Download the module JAR and follow the standard module installation instructions. You get the complete content app and can learn how it works.

1. Download magnolia-app-tutorial-1.3.2.jar from Nexus.
2. Copy the JAR into <CATALINA_HOME>/webapps/<contextPath>/WEB-INF/lib folder. Typically this is <CATALINA_HOME>/webapps/magnoliaAuthor/WEB-INF/lib.
3. Restart your Magnolia instance and run the Web update. This will install the App Tutorial module.

Module contents

The module contains the following source files:

• Module descriptor: magnolia-module-app-tutorial.xml
• App configuration bootstrap: config.modules.app-tutorial.apps.xml
• App Launcher layout bootstrap: config.modules.ui-admincentral.config.appLauncherLayout.groups.edit.apps.products.xml
• Sample products (cars): products.xml
• Custom node type mgnl:product: app-tutorial-nodetypes.xml
• User interface text in English: app-products-messages_en.properties  

App configuration

The best way to learn is change things and see what effect it has. Go to Configuration > /modules/app-tutorial to find the configuration.

App descriptor

App launcher layout

In the app launcher layout we add the app to the Edit group.

Go to the app launcher and verify that you can see the Products app icon.

Browser subapp

The browser subapp in /modules/app-tutorial/apps/products allows you to view and organize items. It is part of every content app.

Content connector

A content connector tells the app where the content resides. In this case we store products in the repository so we use a JCR content connector. The configuration identifies the workspace and a path. It also configures the node type the app operates on.  Magnolia 5.3+

Workbench

In this app, the workbench displays two node types: mgnl:folder and mgnl:product.

Content views

A content view defines how the content is displayed to the user. Under workbench, we have three views: tree, list, thumbnail and search. The tree view defines columns: Name, Status and Modification date. The other views extend the tree view, displaying the same columns.

Here's the tree view:

Test the other views too. Search is case sensitive by default.

Actions

Actions allow you to add, edit and delete folders and products. Each action adheres to an action definition.

Action bar

Image provider

Image provider is a component that renders images used in apps. It generates the portrait image at the bottom of the action bar and the thumbnails for the thumbnail view. 

Select an item in the browser subapp to test the preview. The preview image is displayed at the bottom of the action bar.

Detail subapp

A detail subapp allows you to edit a product. It is configured with a subapp descriptor just like a browser subapp but the classes are different.

Content connector

 Magnolia 5.3+

A JCR content connector is also needed in the detail subapp. Here the definition is simpler. You just need to name the workspace. 

The rootPath property has the same value (/) as in browser subapp content connector. They must have the same value. However, since / is the default value you can leave it out in both subapps.

Editor

Form

Your app edit any kind of content. What you plan to edit determines what fields you need on the form. In this tutorial the items are products so we create a form with three fields: product name, photo and photo credit.

Commit and cancel actions

Commit and cancel are generic reusable actions that save the form data. They are defined under the detail subapp. The corresponding dialog buttons are in the editor (see above).

Create a few items. Verify that you can edit existing items too.

Now do it yourself

Here are ways to create your own content app:

Option 1: Copy an app

1. Copy the configuration nodes of an existing content app into a new app. You can copy one of Magnolia's native apps such as Contacts.
2. Export the copied configuration nodes into XML.
3. Open the XML in a text editor. Search and replace the item names. For example, if your app manages apples instead of oranges, replace apple with orange.
4. Import the XML back to Magnolia.
5. Register a new workspace in the module descriptor and create a new node type.

Option 2: Extend an app

This method works well if one of Magnolia's native apps does almost what you need. You don't need to change much. Extend the native app to get all its functionality and add something special. For example, configure a special Pages app that displays only one website branch. If editors mostly work in that branch the app saves them from having to navigate there.

1. Extend an existing app to inherit configuration. For example, see how the JCR Browser app extends the Configuration app by inheriting its subapps.
2. Define exceptions in your own app.

See also 3.3.5 Create an app in Magnolia Academy.

Enhancements

Here are ideas for enhancing your content app and making it ready for production use:

Add import and export actions

Add export and import actions so you can export products into XML. See how the actions are implement in the Contacts app. Copy the action configuration to your app. The Magnolia UI framework provides generic export and import actions that you can use out of the box.

/modules/contacts/apps/contacts/subApps/browser/actions/export
/modules/contacts/apps/contacts/subApps/browser/actions/import
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/root/groups/importExportActions
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/contact/groups/importExportActions
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/folder/groups/importExportActions

Add publishing actions

To add publishing actions:

1. Add activate and deactivate actions so that you can publish products to the public instance. Copy the actions from the Contacts app.
2. Add the activate and deactivate actions in the action bar. You can copy these also from the Contacts app.
3. Add a subscription to the products workspace so that public instances receive the content.

 Don't forget to install your module also on the public instance! You may not need the app on the public instance but you will need the products workspace so that products can be activated.

Add deletion approval

Prevent editors from deleting products with a single click. The best practice is to mark an item for deletion and require the editor to publish the change:

1. Display a confirmation message, asking if the user really wants to delete the item.
2. Mark the item as deleted.
3. Activate the change. This finally deletes the item.

See how the Contacts app handles this and replicate the actions in your app. See also how the  info.magnolia.ui.api.availability.IsNotDeletedRule action availability rule is used in the activate action to make sure that the activatable item is not marked for deletion. 

Display product images on the website

You may want to display product images on the website or in a shop. Add a URI2RepositoryMapping for the products workspace. The mapping tells Magnolia to serve content from the products workspace when the request URL contains the /products prefix.

To add a URI2RepositoryMapping:

1. Go to Configuration > /server/URI2RepositoryMapping/mappings.

2. Map the /products URI prefix to the products workspace.

   Node name	Value
   server
   URI2RepositoryMapping
   mappings
   products
   URIPrefix	/products
   handlePrefix
   repository	products

3. Activate the products node and its properties to the public instance.
4. Optional: Grant the anonymous role permission to read the products workspace. This allows visitors to view the images on the public instance.
    

To request an image, use the /products prefix in the URL:

http://localhost:8080/magnoliaPublic/products/Fiat-Cinquecento/photo/Fiat%20Cinquecento.jpg

Credits:

• Pedro Ribeiro Simões: Riley Brooklands 1930 and Fiat Cinquecento photos. Creative Commons Attribution 2.0 Generic (CC BY 2.0)
• John Lloyd : Pontiac 1952, Continental Mark II and Hudson 1927 photos.  Creative Commons Attribution 2.0 Generic (CC BY 2.0)