The Camera Collection module is a custom-built Magnolia Maven module originally created for educational purposes for Magnolia Conference 2016 workshop #2.
Maven is the easiest way to install the module. Add the following dependency to your bundle:
<dependency> <groupId>info.magnolia.documentation</groupId> <artifactId>camera-collection</artifactId> <version>1.0-SNAPSHOT</version> </dependency>
Pre-built jars are also available for download. See Installing a module for help.
The information below is imported from the module README file in the GIT repository:
A Magnolia Maven module providing
- JCR based content apps to manage a camera collection.
- Bootstrapped content.
- Custom-built ready-to-use JSON providers producing JSON based on content app items and their referenced content.
The module provides two apps -
Cameras - which operate in the same workspace called
Images related to content items are stored in the Assets app
The items from both apps can be categorized.
A maker is a manufacturer (typically a company) that builds cameras (for instance “Nikon”).
The Makers app manages the makers.
The Cameras app manages the cameras - it is the core app of this module.
maker (a reference to a maker-item from the Makers app)
images (a multi-field to store references to dam assets)
categories (a multi-field to store references to categorization items)
Uses custom components
Magnolia provides default REST endpoints for nodes and for properties.
See REST API (documentation).
This module also provides interfaces to create custom tailored JSON for items from the Cameras and
Makers apps and their referenced content from assets and categories
The JSON produced is i18n-ized; if the JSON contains html, crucial characters are encoded properly.
For educational purposes the module has two implementations both providing the same API:
A freemarker page template combined with virtualURIMapping and a Java based custom REST endpoint.
Both implementations produce the same JSON structure and have the following common RESTful APIs:
$ is the api base path:
/.rest/cameracollection/v1 for the REST endpoint
/json for the freemarker template.
Custom-built REST endpoint
The endpoint only provides
GET methods at the moment.
The endpoint must be configured.
See Configuration app >
The endpoint configuration is bootstrapped with the module.
You must grant the
camera-rest role to appropriate users to enable access to REST resources.
As a developer, add the role to superuser on author and to anonymous on public context.
The role is bootstrapped with the module but not yet assigned to any user.
The role has the following web access rules assigned:
- deny: /.rest*
- get: /.rest/cameracollection/v1/*
- get: /.rest/properties/v1/cameracollection*
- get: /.rest/nodes/v1/cameracollection*
Available REST resources
Resources are relative to the
contextPath which depends on the environment.
In a typical development environment it is: http://localhost:8080/magnoliaAuthor.
Check the above resources with
using the built-in swagger API explorer.
The FreeMarker-based JSON provider comes with a page template named
which includes json-provider-utils.ftl. This .ftl file contains the rendering macros and functions.
The macros and function use
damfn standard templating functions only.
(No additional Java code.)
The module bootstraps the page node
/json and virtual URI mappings - one mapping for each method of the API.
To make sure the server response ‘Content-type’ is appropriate,
a specific JSON renderer configuration is added, see
Configuration app >
This is the main macro starting the rendering procedure.
The macro expects request parameters in order to render the appropriate JSON content.
servicecan be ‘cameras’, ‘makers’, ‘allMakers’, ‘allCameras’. optional, default=‘cameras’
uuid- the jcr node identifier of the item.
path- makerPath or cameraPath, e.g. “/F3” (camera) or “/Nikon” (maker).
Virtual URI mappings
are mapped to URIs with query parameters by using virtual URI mapping definitions.
The mappings are bootstrapped by the module.
Please see Configuration app > /modules/camera-collection/virtualURIMapping for all 6 mappings.
RESTful URI examples
A custom ColumnFormatter to render a property of a referenced item.
For instance an item in content app1 has a reference to an item in content app2.
This column formatter is used in content app1 to render a property of the referenced item from content app2.
The label can render a property from the referenced item and combine it with a property of
the item which keeps the reference.
DamLinkFromListImageProvider behaves in a similar way to DamLinkImageProvider,
however, the content app item can have one image or a list (multi-field) - from which the image provider will grab the first image.