close

Filter

loading table of contents...

Content Application Developer Manual / Version 2307

Table Of Contents

4.3.5 Adding Document Metadata

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 MetadataMetadata 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.4, “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.4, “Advanced Metadata Usage”.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.