Community Wiki
Page tree
Skip to end of metadata
  • Created on 2016-03-28, last edited by Christoph Meier on 2017-11-29
Go to start of metadata

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

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
magnolia-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

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)





  • No labels