Creating a custom content app

In this section you learn to create a custom content app:

1. Start with the content app framework and learn the building blocks.
2. Get the sample code for a Flickr photo app.
3. Do the simple tutorial where you use a String as an item ID and create a single container.

The example photo app uses the Flickr Web service as a remote data source. If you are interested in non-JCR data sources in general see Content app with non-JCR content.

Use case: accessing remotely stored images

Digital agencies use thousands of images to build attractive Web content. Large image libraries are typically not stored locally in the JCR but in purpose-built digital asset servers and repositories either on the company's premises or at remote host.

In these tutorials we:

• Connect a remote image hosting service to Magnolia.
• Create a custom content app that makes it easy for Magnolia editors to browse remotely stored images.
• Create a dialog that allows editors to select an image for use on the site.

The custom app avoids the cumbersome process of downloading each image separately from the host and adding it to Magnolia's DAM before it is available for use.

In this tutorial we don't go into details of creating a template to embed an image on the site. However, we provide an example component template that uses the Flickr browser app in a choose dialog.

Flickr

Flickr is a popular photo sharing site that hosts billions of images. It also provides an API to fetch data, has high availability, and creates many different sizes of an image. In this example we use Flickr as a media store.

Flickr account

To upload and host photos on Flickr you need an account. Every photo has a unique ID. The ID is not only unique within an account but within Flickr as a whole.

Flickr allows you to organize photos into albums. One photo can belong to one or more albums. Each album also has a unique ID.

Flickr API key and secret

To use use the Flickr API you have to apply for an API key. You will get a key and a secret. To fetch data from the API, use your account ID, API key and API secret.

The example module contains an account that has access to a few albums and photos. Please do not abuse the account, otherwise we have to remove it.

If you need to access many Flickr accounts and choose photos from them, create another app to manage Flickr account data. This could be done in a simple JCR content app.

Referencing photos

We only store a reference to a Flickr photo in the JCR content of a page instead of storing the UUID of a Magnolia Asset. We let the rendered page fetch the picture from Flickr. Such a solution may save a lot of bandwidth for your infrastructure but it also means that the images are always served from the remote host.

Flickr4Java

Flickr4Java is a Java API which wraps the REST-based Flickr API. We use it in the example to make accessing Flickr from Java code easier.

Get the flickr-integration project

To understand the tutorials and the Flickr example, install the flickr-integration project into your development environment.

• If you use an IDE, add the modules to the POM file of your development project and clone the resources from the Magnolia Git repository. You can read the complete source and debug the examples.
• If you don't use an IDE, add the required JAR files to your bundle . 

Project structure

The project has a parent pom which contains 6 submodules.

• flickr-integration-parent: Takes care for dependency management.
  
  • flickr-accounts: JCR based content app to manage Flickr accounts. Data* is read by flickr-integration.
  • flickr-integration: Provides classes to fetch data via Flickr API.
  • flickr-simple-browser: A simple content app to browse Flickr photos.
  • flickr-browser: Extended content app to browse Flickr photos and albums.
  • flickr-templates: Minimal set of templates to add Flickr photos to Magnolia pages, storing references to Flickr photos or albums.
  • flickr-integration-bundle: Bundles all the other submodules including their dependencies to third party libraries

*) The accounts submodule contains access data for a demo Flickr account to play around. Please do not abuse - neither account data nor the account itself.

Adding modules to your project POM

<dependency>
  <groupId>info.magnolia.documentation</groupId>
  <artifactId>flickr-accounts</artifactId>
  <version>1.0.7</version>
</dependency>

<dependency>
  <groupId>info.magnolia.documentation</groupId>
  <artifactId>flickr-integration</artifactId>
  <version>1.0.7</version>
</dependency>

<dependency>
  <groupId>info.magnolia.documentation</groupId>
  <artifactId>flickr-simple-browser</artifactId>
  <version>1.0.7</version>
</dependency>

<dependency>
  <groupId>info.magnolia.documentation</groupId>
  <artifactId>flickr-browser</artifactId>
  <version>1.0.7</version>
</dependency>

<dependency>
  <groupId>info.magnolia.documentation</groupId>
  <artifactId>flickr-templates</artifactId>
  <version>1.0.7</version>
</dependency>

Clone the project from Git

The project code is stored on Magnolia's Git repository.

Open a shell, change to a directory where you want to clone the project, and type the following:

git clone http://git.magnolia-cms.com/git/documentation/flickr-integration.git

After cloning the repo - check out the tagged version of the highest major version of 1.0.x series of this module which currently is 1.0.7.

Adding JAR files to a bundle

To install the flickr modules on an existing installation, download the JAR files and add them to the folder WEB-INF/lib of your webapps. See Installing a module for help.

• flickr-accounts.jar
• flickr-integration.jar
• flickr-simple-browser.jar
• flickr-browser.jar
• flickr-templates.jar
• flickr-integration-bundle.zip (includes third-party libraries)

If you are dropping JAR files to your bundle, make sure to also add the 3rd party JAR files com.flickr4java:flickr4java:2.12 and org.scribe:scribe:1.3.5. (You can find these files within the flickr-integration-bundle.zip or on public Maven repositories).