This page explains how to use the delivery endpoint so that it resolves
references to nodes from different workspaces.
The information on this page only applies to the Delivery API.
What is reference resolving?
The endpoints of the delivery API are configured to return content as
JSON from one JCR workspace (configured with the workspace property).
Here is a JSON response of a tour from the workspace tours.
{
"@name": "Kyoto",
"@path": "/magnolia-travels/Kyoto",
"@id": "b475f27e-2929-427b-9517-815118a3b36e",
"@nodeType": "mgnl:content",
"body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
"name": "Kyoto",
"description": "The natural side of Japan",
"destination": [
"7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
],
"location": "Kyoto, Japan",
"tourTypes": [
"d2245867-ecaa-4b4e-8743-e0c939be68b7",
"415025c6-e4b5-4506-9384-34f428a52104"
],
"author": "Magnolia Travels",
"duration": "7",
"image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
"@nodes": []
}Copy
Lines 13-15: The tourTypes property contains two references to tour
type nodes that reside in the category workspace.
Line 19: The image property contains the asset identifier, which is
the reference to an asset. In this case the asset is stored in the
Magnolia DAM in the dam workspace. In other cases, the asset could be
in another asset provider.
We could send additional requests to deliver content for the category
and dam workspaces. However, it is more efficient to get the data of
the referenced nodes directly with the first request by resolving the
references.
In the following sections, we show you how to configure the delivery
endpoint in order to resolve the references.
The properties of a single reference are defined in info.magnolia.rest.reference.ReferenceDefinition.
Property
Description
name
optional
An arbitrary name. If you do not set the property, the first property
must start with a - in order to have proper YAML list item. Using the
name property improves the readability of the YAML file.
propertyName
required
The value of this property contains the name of the JCR node property
that stores one or multiple references to nodes of other workspaces.
nodeType
optional
The value must be a valid
node type. If set,
references are resolved only on nodes of the given type.
referenceResolver
required
The reference resolver defines how references are resolved. The
properties are defined in
info.magnolia.rest.reference.ReferenceResolverDefinition.
Magnolia provides a JCR node reference resolver that is suitable in most
cases, with the exception of assets. Use the definition class
info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
for configuration.
The lines 3-10 define how the references stored in the field tourTypes
are resolved.
{
"@name": "Kyoto",
"@path": "/magnolia-travels/Kyoto",
"@id": "b475f27e-2929-427b-9517-815118a3b36e",
"@nodeType": "mgnl:content",
"body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
"name": "Kyoto",
"description": "The natural side of Japan",
"destination": [
"7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
],
"location": "Kyoto, Japan",
"tourTypes": [
{
"@name": "ecotourism",
"@path": "/tour-types/ecotourism",
"@id": "d2245867-ecaa-4b4e-8743-e0c939be68b7",
"@nodeType": "mgnl:category",
"body": "Nature is calling you. And there’s nowhere more natural than Africa’s savannah plains or the icy wilderness of Antartica. But what’s even better than getting closer to nature is knowing that when you travel with us, you’re making your own contribution to keeping those untouched parts of earth just as they are.",
"name": "ecotourism",
"level": "level-1",
"description": "Call of the wild",
"icon": "jcr:8ad908e7-2ab7-4fe2-b1ed-e6eb3f68f3b0",
"displayName": "Ecotourism, Nature & Wildlife",
"image": "jcr:2fd89d97-f932-4533-8a30-d70988bde30c",
"@link": "/magnoliaAuthor/tour-types/ecotourism.html",
"@nodes": [
]
},
{
"@name": "offPath",
"@path": "/tour-types/offPath",
"@id": "415025c6-e4b5-4506-9384-34f428a52104",
"@nodeType": "mgnl:category",
"body": "Riding on a big tour bus, eating tourist menus and taking pictures of the Eiffel Tower is not your idea of travelling. You want to find something new, and see things from a local point of view. With us, you can discover the local gems that most travellers never experience. ",
"name": "offPath",
"level": "level-1",
"description": "Unique holidays that take you off the beaten track ",
"icon": "jcr:6d5d576a-79f9-48d9-b141-6682f2eef585",
"displayName": "Off the Beaten Path",
"image": "jcr:272f75b9-ed87-4e0b-8bf3-15db217ba897",
"@link": "/magnoliaAuthor/tour-types/offPath.html",
"@nodes": [
]
}
],
"author": "Magnolia Travels",
"duration": "7",
"image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
"@nodes": [
]
}Copy
Properties
Property
Description
referenceResolver
required node
$type
required (unless class is used)
Must be jcrReferenceResolver.
class
required (unless $type is used)
Must be
info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition or a
subclass.
targetWorkspace
required
The name of the workspace containing the nodes that are referenced.
expand
optional, default is true
If set to true, all properties of the referenced node are included in
the JSON.
If false, the JSON contains only links to the referenced node. See
generateLink below.
generateLink
optional, default is false
If true, the resolved node contains an additional link property. The
value of the link property is a relative link to directly render the
referenced node.
The format of the generated links depends on the configuration of the
link generator (configured in config workspace at
/server/rendering/linkManagement).
depthInReferencedNode
optional, default is -1
Sets the depth in the referenced nodes.
The default value of -1 means that the endpoint returns the referenced nodes up to the configured referenceDepth property (a specific depth for the returned "root" nodes) but it also returns all their children.
While the referenceDepth property sets a specific depth for the returned "root" nodes, you can control the depth in the referenced nodes with the depthInReferencedNode property.
Example: Depth in the referenced nodes in the Tour Finder page
In the Travel Demo, the Tour Finder page has the following structure:
In this case, the tourFinder node is resolved and shows its content, but only to one level. The main and footer area nodes are not resolved any further:
You may have a situation where resolvers reference fields with an identical name because the fields are generated by a jcrMultiField of different pages.
You can resolve this conflict by setting a different name for one of the fields through the name property in the configuration of the field. In the following example, a custom name: categoryField is configured for a jcrMultiField:
Magnolia REST modules come with an asset resolver, which creates a
(relative) link to the image as well as Dublin Core metadata (if it
exists for the asset). Use the
info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition
class for configuration.
The Magnolia asset resolver operates on the
DAM API.
If the referenced assets reside in the
Magnolia
DAM, the asset resolver can also generate links to asset renditions
(also known as image variations). Renditions must be defined in the
theme that is linked to the
site definition. See
image variations to learn how
to define asset renditions in a theme.
For image variations to be resolved correctly, make sure that the
fallback site has theme variations configured or extends a site
definition with desired variations.
The lines 5-12 define how the references stored in the dam workspace
are resolved.
{
"@name": "Kyoto",
"@path": "/magnolia-travels/Kyoto",
"@id": "b475f27e-2929-427b-9517-815118a3b36e",
"@nodeType": "mgnl:content",
"body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
"name": "Kyoto",
"description": "The natural side of Japan",
"destination": [
"7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
],
"location": "Kyoto, Japan",
"tourTypes": [
"d2245867-ecaa-4b4e-8743-e0c939be68b7",
"415025c6-e4b5-4506-9384-34f428a52104"
],
"author": "Magnolia Travels",
"duration": "7",
"image": {
"@name": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
"@path": "/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
"@id": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
"@link": "/magnoliaAuthor/dam/jcr:44689d29-5966-4d41-8fd4-2dc7da783528/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
"metadata": {
"fileName": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
"mimeType": "image/jpeg",
"caption": "Stairs to Ōminesan-ji temple",
"fileSize": "1115288",
"height": "2133",
"width": "1600",
"title": "Stairs to Ōminesan-ji temple",
"format": "image/jpeg",
"coverage": "Yoshino district, Nara prefecture, Japan",
"description": "Ōminesan-ji (大峯山寺 Ōminesan-ji) is an important temple of the Shugendō religion in Yoshino district, Nara prefecture, Japan. It is located at the peak of Mount Ōmine, or Sanjōgatake. According to tradition, it was founded by En no Ozunu, the founder of Shugendō, a form of mountain asceticism drawing from Buddhist and Shinto beliefs.",
"publisher": "Tim Notari",
"rights": "by-sa/2.0/",
"source": "https://www.flickr.com/photos/tasteful_tn/204886404/",
"creator": [
"superuser"
],
"contributor": [
"Tim Notari"
],
"subject": [
"Ōminesan-ji temple"
],
"date": "2019-01-17T10:30:29.618+01:00",
"created": "2015-01-29T08:45:41.613+01:00",
"modified": "2019-01-17T10:30:29.618+01:00"
},
"renditions": {
"320x240": {
"mimeType": "image/jpeg",
"link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/320x240/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
},
"1600x1200": {
"mimeType": "image/jpeg",
"link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/1600x1200/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
},
"nonexistent": {
"mimeType": "image/jpeg",
"link": "/magnoliaAuthor/.imaging/default/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content.jpg"
}
}
},
"@nodes": [
]
}Copy
NOTE:
Line 23: The property @link provides a relative link to the asset.
The asset is served by info.magnolia.dam.core.download.DamDownloadServlet.
Line 51 pp - renditions. When requesting the links of the renditions,
they are served by info.magnolia.imaging.ImagingServlet.
Line 54: The link contains a relative link to an asset rendition
(of a defined image variation).
Line 62: The link to an undefined rendition returns the original
uploaded asset. Here it returns as @link of line 51 (the former served
by dam servlet, the latter served by imaging servlet).
Properties
Property
Description
referenceResolver
required node
$type
required (unless class is used)
Must be assetReferenceResolver.
class
required (unless $type is used)
Must be
info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition or a
subclass.
expand
optional, default is true
If set to false, neither the list of defined renditions nor the meta
data is shown.
If includeDownloadLink is set to true, a link is returned, otherwise
the asset item key or original text is shown.
includeDownloadLink
optional, default is true
If set to false, the JSON file does not show the relative asset link.
includeAssetMetadata
optional, default is true
If set to false, metadata is not included.
assetRenditions
optional
A list of rendition names as defined in the theme linked to the current
site.
<rendition-name>
required
A rendition name.
To get the asset in its original (default) size, use original as the
value.
If you add an undefined (a non-existent) rendition, the
asset resolver creates a link to the default variation which is the same
as the asset in its original size.
Resolving asset links in rich text fields
We provide a resolver which helps resolve links for assets in the
rich
text field. In the following example, the first word Kyoto in the
rich text field has been turned into a link to the kyoto.png image
with UUID 0a3bb34f-b49f-4e02-a9e9-e46cf860b612:
In the repository, this part of content is stored like this:
Without the asset link resolver, the endpoint returns what is stored in
the repository, with escaped double quotes:
<p>Experience the still beauty that permeates and surrounds
<ahref=\"${link:{uuid:{0a3bb34f-b49f-4e02-a9e9-e46cf860b612},repository:{dam},path:{/untitled}}}\">Kyoto</a>.
Kyoto is famous for many things,Copy
If the resolver is set, the link to the asset will be resolved as a URL:
<p>Experience the still beauty that permeates and surrounds
<ahref=\"http://localhost:8080/magnoliaAuthor/fallback/dam/jcr:0a3bb34f-b49f-4e02-a9e9-e46cf860b612/kyoto.jpg\">Kyoto</a>.
Kyoto is famous for many things,Copy
Properties
Property
Description
referenceResolver
required node
$type
required (unless class is used)
Must be richTextLinkReferenceResolver.
class
required (unless $type is used)
Must be
info.magnolia.rest.reference.link.RichTextLinkResolverDefinition or a
subclass.
completeUrl
optional, default is true
The endpoint returns a full URL, using the value configured in
server.defaultBaseUrl (see
Configuration
management).
If set to false, a relative link is returned instead, for example:
<p>Experience the still beauty that permeates and surrounds
<ahref=\"/magnoliaAuthor/dam/jcr:0a3bb34f-b49f-4e02-a9e9-e46cf860b612/kyoto.jpg\">Kyoto</a>.
Kyoto is famous for many things,Copy