The Camera Collection module is a custom-built Magnolia Maven module originally created for educational purposes for Magnolia Conference 2016 workshop #2.
Installing
Maven is the easiest way to install the module. Add the following 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:
camera-collection
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.
(Content) apps
The module provides two apps - Makers
and Cameras
- which operate in the same workspace called cameracollection
.
Images related to content items are stored in the Assets app dam
workspace.
The items from both apps can be categorized.
Makers app
A maker is a manufacturer (typically a company) that builds cameras (for instance “Nikon”).
The Makers app manages the makers.
workspace: cameracollection
basePath: /makers
nodeType: mgnl:maker
item properties:name
, longName
, history
, image
Cameras app
The Cameras app manages the cameras - it is the core app of this module.
workspace: cameracollection
basePath: /cameras
nodeType: mgnl:camera
item properties:maker
(a reference to a maker-item from the Makers app)name
description
history
images
(a multi-field to store references to dam assets)categories
(a multi-field to store references to categorization items)
Uses custom components
referencedJcrItemColumnFormatter, DamLinkFromListImageProvider
Custom JSON
providers
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.
API
Both implementations produce the same JSON structure and have the following common RESTful APIs:
$/cameras{cameraPath:(/.+)?}
$/makers{makerPath:(/.+)?}
$/cameraById/{uuid}
$/makerById/{uuid}
$/allCameras
$/allMakers
where $
is the api base path: /.rest/cameracollection/v1
for the REST endpoint
and /json
for the freemarker template.
Custom-built REST endpoint
The endpoint only provides GET
methods at the moment.
Endpoint class
info.magnolia.documentation.apps.cameracollection.rest.v1.CameraCollectionEndpoint
Endpoint configuration
The endpoint must be configured.
See Configuration app > /modules/camera-collection/rest-endpoints/cameracollection
.
The endpoint configuration is bootstrapped with the module.
Role camera-rest
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
/.rest/cameracollection/v1/cameras{cameraPath:(/.+)?}
/.rest/cameracollection/v1/cameraById/{uuid}
/.rest/cameracollection/v1/allCameras
/.rest/cameracollection/v1/makers{makerPath:(/.+)?}
/.rest/cameracollection/v1/makerById/{uuid}
/.rest/cameracollection/v1/allMakers
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 withmagnolia-rest-tools
using the built-in swagger API explorer.
FreeMarker-based template simple-json-provider
The FreeMarker-based JSON provider comes with a page template named simple-json-provider
which includes json-provider-utils.ftl. This .ftl file contains the rendering macros and functions.
The macros and function use cmsfn
and 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 > /modules/rendering/renderers/json
Macro renderResponse
This is the main macro starting the rendering procedure.
The macro expects request parameters in order to render the appropriate JSON content.
service
can 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
RESTful URIs
are mapped to URIs with query parameters by using virtual URI mapping definitions.
The mappings are bootstrapped by the module.
Mapping class: info.magnolia.cms.beans.config.RegexpVirtualURIMapping
Mapping examples:
-
fromURI: /json/allCameras
toURI: forward:/json?service=allCameras
-
fromURI: /json/cameras(\/[0-9A-Z]+)
toURI: forward:/json?path=$1
-
fromURI: /json/makerById/([0-9A-Z]+)
toURI: forward:/json?service=makers&uuid=$1
Please see Configuration app > /modules/camera-collection/virtualURIMapping for all 6 mappings.
RESTful URI examples
- /json/cameras/F3
- /json/cameraById/7e0940e1-9ac0-47e9-af45-52cbd2559a1a
- /json/allCameras
- /json/makers/Rollei
- /json/makerById/723040c9-2f1b-4d88-8569-bbd9a57277cc
- /json/allMakers
Custom components
Column formatter referencedJcrItemColumnFormatter
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.
classes: ReferencedJcrItemColumnDefinition
, ReferencedJcrItemColumnFormatter
Image provider DamLinkFromListImageProvider
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.
classes:DamLinkFromListImageProvider
, DamLinkFromListImageProviderDefinition
,
ConfiguredDamLinkFromListImageProviderDefinition
, LinkPropertyType
(enum)