External reference factory

The hybrid asset reference factory determines where the content of a hybrid asset will be stored. The reference factory can have one or more "mappings". Each mapping contains a reference template used to create a storage URL pointing to the asset content and a set of voters that decide if the mapping will be used to generate the storage URL.

When an asset is chosen to be transformed into a hybrid asset, the reference factory will find the first matching mapping and generate a storage URL for the asset content. The asset and its new storage URL are passed to an external content store which takes care of transferring the asset’s content to external storage.

Where hybrid asset content resides outside of Magnolia does not have to reflect where it resides within Magnolia, though it can. You can store asset content at different paths in external content stores. You can change the name of the asset content. With voters and the reference template, a reference mapping controls where the content of a hybrid asset will end up.

Reference factory configuration

The reference factory is configured as part of the Hybrid Assets module. The app is configured at Configuration > /modules/hybrid-assets/config/referenceFactory.

Property Description

class

required

Must be info.magnolia.dam.hybrid.mapping.SimpleReferenceFactory.

the reference factory class must implement the interface info.magnolia.dam.hybrid.mapping.ReferenceFactory if you wish to implement your own reference factory.

Reference mappings

Reference mappings are defined at /modules/hybrid-assets/config/referenceFactory/mappings. You can define more than reference mapping.

The reference factory (SimpleReferenceFactory) checks each defined reference mapping in the order they are defined to see if the mapping can be applied to a given asset, the first mapping that can be applied to the asset is used to generate the storage URL for the asset content.

A reference mapping contains the following properties:

Property Description

class

required

Must be info.magnolia.dam.hybrid.mapping.TransformReferenceMapping.

the reference mapping class must implement the interface info.magnolia.dam.hybrid.mapping.ReferenceMapping if you wish to implement your own reference mapping.

referenceTemplate

required

The reference template should produce a unique storage URL or reference understandable by an external content store.

The referenceTemplate can include the following placeholders whose values are substituted into the final storage URL:

  • fileName: the path to the asset without the asset file name

  • baseName: the asset file name minus the file extension

  • extension: the extension from the asset file name

  • nodeId: the JCR node ID of the asset

  • nodePath: the JCR node path

  • nodePathHash: a MD5 hash has of the JCR node path

  • random: a random integer between 0 and 999999

  • timestamp: the current time in milliseconds (UNIX epoch time in milliseconds)

The values of the above will be replaced in the reference template with their current values with placeholders like this: {<placeholder>}.

See below for examples reference templates.

voters

required

A VoterSet (info.magnolia.voting.voters.VoterSet) containing one or more voters. The voters will determine if a reference mapping will be used to generate the storage URL for a given asset.

In addition to standard Magnolia voters, the Hybrid Assets module provides a number of voters, see below.

Example reference templates

One important consideration in a reference template is: will the resulting storage URL be unique? If the storage URL is not unique, you may overwrite hybrid asset content or use the content of a different hybrid asset than intended.

Assets in the Magnolia DAM workspace are uniquely named by their node path or ID, so you can use the nodePath or nodeId placeholders to generate a unique storage URL.

However, if you don’t want replicate the path structure of your asset content on your external storage, you can use the placeholders nodePathHash, random and timestamp to generate a unique storage URL.

Example
s3://mgnl-hybrids/{nodePath}

The above referenceTemplate will put the asset content into a bucket named mgnl-hybrids using the asset path. If your asset is located at /foo/bar/myasset.jpg, the resulting URL will be:

Example
s3://mgnl-hybrids/foo/bar/myasset.jpg.
Example
s3://mgnl-hybrids/mgnl-test/${baseName}-${nodeId}-${timestamp}.${extension}

This referenceTemplate will put asset content into a bucket named mgnl-hybrids in the subdirectory mgnl-test. The file name of the content will be <base name of the asset file>-<JCR node ID>-<current time in milliseconds>.<asset file extension>.

If your asset was located at /foo/bar/wisequackingduck.jpg in the DAM workspace, the resulting URL would look something like this:

s3://mgnl-hybrids/mgnl-test/wisequackingduck-f32093ab-b6a4-42da-968d-c2f02144ad69-1580813330904.jpg
Since all assets will be placed in the same bucket and subdirectory, this referenceTemplate uses nodeId and timestamp to guarantee that the storage URL will be unique.

Reference mapping voters

The Hybrid Assets module contains a number of voters that you can use in configuring your reference mappings. These voters work on assets and can check various asset attributes:

  • AssetMimeTypeVoter - check if the asset’s mime type matches a given value

  • NodePathRegexVoter - check if the asset’s path matches a regular expression

  • NodePathVoter - check if the asset’s path matches a given path

  • NodePropertyRegexVoter - check if the value of an asset property matches a regular expression

  • NodePropertyVoter - check if the value of an asset property is equal to the expected value

  • NodeWorkspaceVoter - check if the workspace of an asset is equal to the expected value

All these voters have a common property:

Property Description

not

optional, default is false

If set to true, negates the boolean result when voting

AssetMimeTypeVoter

AssetMimeTypeVoter returns true if the asset’s mime type equals the configured mime type .

Class: info.magnolia.dam.hybrid.voters.AssetMimeTypeVoter

Property Description

mimeType

optional, default is application/octet-stream

A mime type, the voter will return true if the asset’s mime type is equal to the value.

NodePathRegexVoter

NodePathRegexVoter returns true if the asset’s path matches the configured regular expression.

Class: info.magnolia.dam.hybrid.voters.NodePathRegexVoter

Property Description

pathMatches

required

A valid Java regular expression, the voter will return true if the regular expression matches the asset’s path.

NodePathVoter

NodePathVoter returns true if the asset’s path matches the configured path.

Class: info.magnolia.dam.hybrid.voters.NodePathVoter

Property Description

nodePath

required

The expected node path.

startsWith

optional, default is false

nodePath must equal the initial path if true, otherwise the entire path must be equal to nodePath.

NodePropertyRegexVoter

NodePropertyRegexVoter returns true if the value of a specified property of the asset matches the configured regular expression.

Class: info.magnolia.dam.hybrid.voters.NodePropertyRegexVoter

Property Description

propertyName

required

The property name to be tested.

valueMatches

optional, default is false

A valid Java regular expression, the voter will return true if the regular expression matches the property value.

NodePropertyVoter

NodePropertyVoter returns true if the value of a specified asset property equals the expected value.

Class: info.magnolia.dam.hybrid.voters.NodePropertyVoter.

Property Description

propertyName

required

The property name to be tested.

propertyValue

optional, default is false

The expected value of the asset property.

NodeWorkspaceVoter

NodeWorkspace returns true if the asset is stored in the expected workspace equals the expected value.

Class: info.magnolia.dam.hybrid.voters.NodeWorkspaceVoter

Property Description

workspace

required

The expected workspace.
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Hybrid Assets module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules