Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

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. (warning) 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:

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.

Node nameValue
 server
 

 modules

 

 app-tutorial

 

 version

1.3.3-SNAPSHOT

App descriptor

App descriptor configuration describes an app. The descriptor assigns the app a name, icon and implementation class. The name of the app content node must be unique as it is used to refer to the app across the system. This means you cannot name your own app pages since a Pages app already exists.

Node nameValue

 modules

 

 app-tutorial

 

 apps

 

 products

 

 appClass

info.magnolia.ui.contentapp.ContentApp

 class

info.magnolia.ui.contentapp.ContentAppDescriptor

 version

1.3.3-SNAPSHOT

App launcher layout

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

Node name

 modules

 ui-admincentral

 config

 appLauncherLayout

 groups

 edit

 apps

  pages

  assets

  contacts

 products

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

If you move the app to another group, log out and back in to see the change.

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.

Node nameValue

 modules

 

 app-tutorial

 

 apps

 

 products

 

 subApps

 

 browser

 

 class

info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor

 subAppClass

info.magnolia.ui.contentapp.browser.BrowserSubApp

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. (warning) Magnolia 5.3+

Node nameValue
 subApps
 

 browser

 

 contentConnector

 

 nodeTypes

 

 product

 

 icon

icon-items

 name

mgnl:product

 defaultOrder

jcrName

 includeProperties

false

 rootPath

/

 workspace

products

Workbench

Workbench is a view that displays a list of content items in a workspace. It is part of the content app framework, typically defined in the browser subapp. The workbench can display the workspace content in three views: tree, list and thumbnail. It also provides a search box.

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

Node nameValue

 browser

 

 workbench

 

 defaultOrder

jcrName

 dropConstraintClass

info.magnolia.ui.workbench.tree.drop.AlwaysTrueDropConstraint

 editable

false

 includeProperties

false

 Working with Magnolia 5.2.5 or earlier?

Configure the workbench like this in Magnolia 5.2.5 and earlier:

Node nameValue

 browser

 

 workbench

 

 nodeTypes

 

 product

 

 icon

icon-items

 name

mgnl:product 

 folder

 

 icon

icon-folder

 name

mgnl:folder

 defaultOrder

jcrName

 dropConstraintClass

info.magnolia.ui.workbench.tree.drop.AlwaysTrueDropConstraint

 editable

false

 includeProperties

false

 path

/

 workspace

products

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.

Node nameValue
 workbench
 

 contentViews

 

 tree

 

 columns

 

 jcrName

 

 class

info.magnolia.ui.workbench.column.definition.PropertyColumnDefinition

 editable

true

 label

Product name

 propertyName

jcrName

 sortable

true

 status

 

 class

info.magnolia.ui.workbench.column.definition.StatusColumnDefinition

 displayInChooseDialog

false

 formatterClass

info.magnolia.ui.workbench.column.StatusColumnFormatter

 label

Status

 width

45

 moddate

 

 class

info.magnolia.ui.workbench.column.definition.MetaDataColumnDefinition

 displayInChooseDialog

false

 formatterClass

info.magnolia.ui.workbench.column.DateColumnFormatter

 label

Modification date

 propertyName

mgnl:lastModified

 sortable

true

 width

160

 class

info.magnolia.ui.workbench.tree.TreePresenterDefinition

 list

 

 columns

 

 extends

../../tree/columns

 class

info.magnolia.ui.workbench.list.ListPresenterDefinition

 thumbnail

 

 class

info.magnolia.ui.workbench.thumbnail.ThumbnailPresenterDefinition

 search

 

 columns

 

 extends

../../tree/columns

 class

info.magnolia.ui.workbench.search.SearchPresenterDefinition

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.

Node nameValue
 browser
 

 actions

 

 addProduct

 

 availability

 

 nodeTypes

 

 folder

mgnl:folder

 root

true

 appName

products 

 class

info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition

 icon

icon-add-item

 nodeType

mgnl:product

 subAppId

detail

 addFolder

 

 availability

 

 root

true

 class

info.magnolia.ui.framework.action.AddFolderActionDefinition

 icon

icon-add-folder

 editFolder

 

 deleteFolder

 

 editProduct

 

 deleteProduct

 

Action bar

An action bar makes actions available to users. The action bar is typically displayed on the right hand side of the browser subapp. The action bar definition organizes actions into sections (green label) and groups (between horizontal lines). Availability rules determine which section is displayed to the user. For example, when the user selects a content item in the browser subapp, availability rules display only actions that are relevant to working with that item. A group contains actions that have something in common, such as actions for adding things.

Node nameValue

 browser

 

 actionbar

 

 sections

 

 root

 

 groups

 

 addActions

 

 items

 

 addProduct

 

 addFolder

 

 availability

 

 nodes

false

 root

true

 folder

 

 product

 

 defaultAction

editProduct

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. 

Node nameValue

 browser

 

 imageProvider

 

 class

info.magnolia.ui.imageprovider.definition.ConfiguredImageProviderDefinition

 imageProviderClass

info.magnolia.ui.imageprovider.DefaultImageProvider

 originalImageNodeName

photo

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.

Node nameValue

 subApps

 

 detail

 

 class

 info.magnolia.ui.contentapp.detail.DetailSubAppDescriptor

 subAppClass

 info.magnolia.ui.contentapp.detail.DetailSubApp

Content connector

(warning) 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. 

Node nameValue
 subApps
 

 detail

 

 contentConnector

 

 workspace

products

 rootPath

/

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

Editor is a component that edits a content item. The editor typically contains a form. In a content app, you should create an editor definition under the detail subapp. Define the node types the editor edits, a form for editing them, and actions for saving the edit.

Node nameValue

 detail

 

 editor

 

 nodeType

 

 icon

icon-items

 name

mgnl:product

 workspace

products

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.

Node name

Value

 editor

 

 actions

 

 commit

 

 save

 

 form

 

 tabs

 

 product

 

 fields

 

 name

 

 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 name

jcrName

 fileUpload

 

 allowedMimeTypePattern

image.*

 binaryNodeName

photo

 class

info.magnolia.dam.asset.field.definition.DamUploadFieldDefinition

 photoCredit

 

 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

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).

Node nameValue

 detail

 

 actions

 

 commit

 

 class

info.magnolia.ui.form.action.SaveFormActionDefinition

 implementationClass

info.magnolia.ui.form.action.SaveFormAction

 cancel

 

 class

info.magnolia.ui.form.action.CancelFormActionDefinition

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.

Import and export actions in the Contacts app
/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.

(warning) 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 nameValue

     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: