Content Application Developer Manual / Version 2404
Table Of Contents
In order to hand over information rendered by the CAE to Studio you can include metadata
in your HTML documents. To allow attaching metadata to a specific DOM element, it is added as a custom HTML 5
data attribute called data-cm-metadata.
For each DOM element, metadata may consist of complex data structures in terms of (nested) maps and lists that hold
primitive data objects like strings or integers but also application objects if corresponding serializers are
available. Several serializers are predefined, in particular one for Content objects.
Metadata nodes are assumed to be nested corresponding to the DOM hierarchy of the elements they are attached to. From all metadata nodes found in the HTML document, a metadata tree is built according to the following rules:
There is an artificial metadata tree root node.
For a metadata node m found in a DOM node d, look for the first parent DOM node that also has a metadata node assigned (say m') and add m as a child of m'. If no such parent node is found, add m as a child of the root node.
If a DOM node has a list of metadata nodes assigned, these are interpreted as hierarchical nodes in the metadata tree, that is, children are assigned to the last node of the list and the first node of the list is assigned as a child to the metadata parent node.
Example 4.10, “
A DOM with Metadata and Generated Metadata Tree
” shows an example DOM tree with metadata attached to its
elements (->). Note that the list of metadata at the topmost div element is mapped to a hierarchy
of metadata nodes in the metadata tree.
| DOM with Metadata | Metadata Tree |
|---|---|
<html>
|
<body> -> "S"
|
<div> -> ["A", "x"]
|
|-- <div> -> "B"
| |
| <div>
| |
| <span> -> "y"
|
`-- <img> -> "C"
|
root
|
slider metadata "S"
|
content "A"
|
property "x"
|
|-- content "B"
| |
| property "y"
|
`-- content "C"
|
Example 4.10. A DOM with Metadata and Generated Metadata Tree
When the preview page is shown inside Studio, the resulting metadata tree is serialized and sent to the containing Studio, where it is deserialized and used by the built-in preview integration.
Supported Metadata
If metadata refers to a Content object, Studio shows a context menu that allows the editor to interact with this document (open it in a document tab, for instance) when the editor right-clicks inside the preview panel on the corresponding DOM element to which the metadata has been attached.
Similarly, string metadata is interpreted as a property path starting at the document specified by the parent metadata node. If this document is the same as the one shown in the document form, right-clicking the DOM element to which the property metadata has been attached (or any of its subelements) focuses the corresponding property field in the document form. This even works for link list properties. If the property belongs to another document, right-clicking on the property DOM element delegates to the parent node, that is, it opens a context menu that offers actions for that document.
Since Preview Shortcuts refer to Content, not content beans, note that all custom
properties have to be specified with a properties. prefix. Only Content meta properties
like modificationDate are specified without this prefix.
Preview Slider Setting: sliderMetaData
The third kind of metadata which is supported in Studio is device slider metadata,
which is used to render a device slider for responsive websites
that can be used to switch between different target resolutions of the site.
The device slider metadata is a structured object consisting of two properties:
cm_responsiveDevices which is basically a map from device name to resolution
and cm_preferredWidth which tells the width for the full-width mode of the
Studio preview.
{
"sliderMetaData": {
"cm_preferredWidth": 1280,
"cm_responsiveDevices": {
"mobile": {"width": "320", "height": "480", "order": "1", "isDefault": true},
"tablet": {"width": "600", "height": "800", "order": "2"},
"notebook": {"width": "1024", "height": "768", "order": "3"}
}
}
}Example 4.11. Responsive Device Slider Metadata
Due to the tight integration of CoreMedia Studio and the embedded preview
it might be preferable to block animations or certain behavior inside the embedded preview.
In order to do so a previewed documents can provide metadata with additional style sheet and JavaScript URLs.
These URLs are only loaded when the document is displayed in the context of the embedded preview.
The metadata specifying these URLs has to be attached to the head element of the previewed document.
{
"cm_studioPreviewCss": ["css-url-1", "css-url-2"],
"cm_studioPreviewJs": ["js-url-1", "<js></js>-url-2"]
}Example 4.12. Studio Specific CSS and JavaScript Metadata
The built-in Studio preview integration renders borders around highlighted preview DOM elements to indicate where metadata is available (gray border on mouse hover) and which DOM elements carrying metadata have been focused (blue border on right-click or focus). Usually, these borders are rendered by absolutely positioned line overlays. Occasionally, these lines interfere with the web page's mouse hover behavior, for example when the web page uses pop-up menus for navigation.
For such cases, you can tell Studio to use an alternative highlight border rendering strategy
by adding the metadata property cm_highlightStrategy with a value of "CSS" to a DOM
element. Then, for all metadata of this DOM element or any transitive child elements, highlight borders are rendered
by adding a generated style class that sets an inner border (more precisely, an inset box shadow).
This rendering strategy does not interfere with mouse hover events, but its visibility on different kinds of
DOM elements (images, for instance) is less reliable.
If you have to combine standard metadata and cm_highlightStrategy, consider
Section 4.3.5.3, “Advanced Metadata Usage” about using the default property "_" (underscore).
It is also possible to attach custom metadata to the preview and implement a Studio plugin that accesses the metadata tree. For details, see Section 4.3.5.3, “Advanced Metadata Usage”.
