The HCMS allows you to access storage items (files) of the current context asset.
Introduction
Asset storage items can be mapped in the schema by specifying the file type id using the property "cs:storage.item"
. They are typically mapped as a string
either containing a link to the actual storage item content or the actual content itself.
Storage Item as Link
With this mapping, storage items are always represented as a URL link that can be used to download the content, as a consequence the JSON type of the target property needs to be string
. The following properties are used to configure the download link:
"cs:storage.item"
: String containing the storage item file type id (required)"cs:link"
: Must be present to indicate that the download link is created. The value of the property is ignored and can be of any JSON type.
When reading the entity a URL pointing to the desired storage, an item is created by the Headless CMS. On creation or update, one of the following methods can be used to set the data:
- A
data:
direct value URI (as specified by RFC 2397) - A URL (schema http or https) from which the Headless CMS downloads the binary data from. The content size for downloads as part of updates is limited to 200MB and transfer must be finished within two minutes. If the URL generated by the Headless CMS is send back to it during an update, the update of the storage item file is skipped.
- A URL with the scheme
formdata
followed by a colon and the name of the part in theformdata/multipart
request used to update the JSON entity
Example schema:
{ "type" : "object", "properties" : { "image": { "type" : "string", "cs:storage.item" : "master", "cs:link" : "" } } }
Example entity:
{ "image": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDY3OTgyLzAvdGh1bWJuYWls" }
Storage Item inline
With this mapping the storage item file content is mapped to a JSON type string
encoded as base64. The following properties are used to configure it:
"cs:storage.item"
: String containing the storage item file type id (required)"cs:$string_type"
: Must be set tobase64
Example schema:
{ "type" : "object", "properties" : { "image": { "type" : "string", "cs:storage.item" : "master", "cs:$string_type" : "base64" } } }
Example entity:
{ "image": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKBAMAAAB/HNKOAAAAD1BMVEUAAAD///9fX18/Pz8fHx9fJrE7AAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAIElEQVQImWNgwAEUgJiJQcGAmcGBQYEJxIOQBkARKAAAIiIBnc84ujIAAAAASUVORK5CYII=" }
XML Content
XML content can be directly mapped inside string
typed properties. In addition, the XML can also be mapped split into several fragments.
"cs:storage.item"
: The storage item file type id, typestring
, (required)"cs:$string_type"
: Specifies the presentation of the XML, (optional):"plain"
: Plain unicode text- Default value
- Mime type
text/plain
- Stored by using
UTF-8
encoding
"xml"
: xml document- Mime type
text/xml
- Mime type
"cs:storage.$path"
: Path inside the XML document- This declares that the value is not a complete storage item content, but just a single fragment of the XML document stored in the storage item
- This is not Xpath, but just simple dot-separated list of element names from path to the final element
- It cannot be used alone, always requires
"cs:storage.$xml"
"cs:storage.$xml"
: ID of the defined XML structure- It can be used in combination with
"cs:storage.$path"
or alone
- It can be used in combination with
Special care is taken for XML documents, because they are used to store structured data and/or formatted text. A typical example is the article content, which contains both. The structure of the XML document must be defined beforehand (usually at the schema root) and referenced by its id. This allows the same XML structure to be used at different places.
Any level of JSON schema can contain the property "cs:$xml"
with any number of new structures defined. The property name is the id of the structure, the value is a JSON object containing:
"initial"
: The initial content of the XML document ("empty" value)- required, it must contain at least the root element
"processor"
: Name of the processor used to convert XML between internal and external format- Currently there is only one possible value:
CenshareXLink
: Converts all censhare URLs in XLinks to external (REST API) links and vice versa
- Currently there is only one possible value:
A single XML document can be split into several fragments that are separately mapped to different JSON properties. Each of these properties specify the same "cs:storage.item"
and "cs:storage.$xml"
, but different "cs:storage.$path"
. On export, the value is obtained by finding the element specified by path (and a property is missing if there is no such element). On import, this element is created and deleted (as needed) and its content is updated.
A fragment can be both plain
and xml
; in the former case, the text value of the element is actually used. In the latter case, the value in JSON string is the selected element with all the content. Note that on import, the name of the element is always the last element of the XML path; the name of the root element
in JSON string is actually ignored.
Example schema:
{ "type": "object", "cs:asset.type": "text.", "cs:$xml": { "article": { "processor": "CenshareXLink", "initial": "<article><title/><content/></article>" } }, "properties": { "title": { "type": "string", "cs:storage.item": "master", "cs:storage.$xml": "article", "cs:storage.$path": "title", "cs:$string_type": "plain" }, "content": { "type": "string", "cs:storage.item": "master", "cs:storage.$xml": "article", "cs:storage.$path": "content", "cs:$string_type": "xml" } } }
Example entity:
{ "title": "The Title", "content": "<content>Some <bold>content</bold></content>" }
Storage Item Attributes
Some attributes of storage items can be mapped by using the property "cs:storage.$attribute"
with the attribute name as a value. These mappings are only for reading, the values are always ignored on creation or update.
Available storage item attributes are:
mimetype
:string
, always availablefilelength
:integer
, always availablehashcode
:string
, available for all typeswidth_px
andheight_px
:integer
, only for imagesdpi
:integer
, only for imagescolordepthbits
:integer
, only for some imagescolor
:string
, only for images, contains the color schema, typically"rgb"
Storage item attribute can either be used stand alone in conjunction with the property "cs:storage.item"
to specify the storage item type:
{ "mime": { "type": "string", "cs:storage.$attribute": "mimetype", "cs:storage.item": "master" } }
Or it can be mapped together with a storage mapping in a common JSON object using the property "cs:storage.$value_property"
on the storage item mapping:
{ "storage": { "type": "object", "cs:storage.item": "master", "cs:storage.$value_property": "content", "cs:$string_type": "plain", "properties": { "content": { "type": "string" }, "mime": { "type": "string", "cs:storage.$attribute": "mimetype" } } } }
Media Mapping
The media mapping can be used to expose pre and on-demand generated variants of media content for consumption, e.g. image cropping variants, video size variants. This mapping is read only and does nothing on creation and update. Media mapping generates base URLs into the property that need to be extended by appending variant ids to create a URL that points to a variant. The admissible variants are part of the schema configuration. Since the mapping returns URLs the property type needs to be string
and the media mapping is indicated with the child property cs:media
of type object
. This child object contains the variant ids as properties of type object
in turn containing the configuration of the property. The variant type of the variant needs to be defined in the property "type"
.
Below is an example illustrating the abstract principle. Schema:
{ "type" : "object", "properties" : { "image": { "type" : "string", "cs:media" : { "small" : { "type" : "…" }, "large" : { "type" : "…" } } } } }
It results in an entity like this:
{ "image": "http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w" }
And the URLs of the actual variants are http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w/small
and http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w/large
.
Variant Type Storage
The variant type storage
provides access to a storage item specified by the property storageKey
.:
Example schema:
{ "cs:media": { "preview": { "type": "storage", "storageKey": "preview" } } }
Variant Type Dynamic Image
The variant type dynamic_image
provides access to dynamically generated images. The dynamic image generation needs to be enabled in the global service configuration. It supports the following options:
aspectRatio
: Aspect ratio for the generated image e.g. 16:9, value typestring
with
: Width for the generated image in pixel, value typeinteger
height
: Height for the generated image in pixel, value typeinteger
cropKey
: ID of the censhare image crop to use for the selection of the clipping, value typestring
fileFormat
: Format of the generated image (either"jpg"
or"png"
), value typestring
quality
: Quality for JPEG images as number between 0 and 100, value typeinteger
backgroundColor
: Color to fill the transparencies when converting to JPEG images as hexdecimal RGB color (e.g."#ff00ff"
), value typestring
watermarkAssetId
: ID if an image asset to overlay as a watermark, value typeinteger
watermarkOpacity
: Opacity of the watermark as floating point number between 0 and 1.0 inclusive, value typenumber
At least width
or height
must be specified and can be combined with aspectRatio
. width
, height
and aspectRatio
must not be specified together.
Example schema:
{ "cs:media": { "medium": { "type": "dynamic_image", "width": 400, "asepectRatio": "4:3", "fileFormat": "jpg" } } }
Asset elements
To handle assets with element structures e.g. PDFs with their individual pages, you can map elements to an array of objects using "cs:element.key": "actual"
. Currently this mapping is read only and just the actual elements are supported.
The mapping does not generate anything besides the empty object for each element. You need to either use the storage or media mappings mentioned above or use the element attribute. The element attribute mapping is configured using the property cs:element.$attribute
with one of the following values:
kind
the element kind, must be mapped to a JSONstring
width_mm
,height_mm
,xoffsmm
oryoffsmm
the element geometry, must be mapped to a JSONnumber
Example schema:
{ "type" : "object", "properties" : { "pages": { "type" : "array", "items": { "type": "object", "cs:element.key": "actual", "properties": { "preview": { "type": "string", "cs:storage.item": "preview", "cs:link": "" }, "kind": { "type": "string", "cs:element.$attribute": "kind" } } } } } }
Example entity:
{ "pages": [ { "preview": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDA2ODgyNS8x", "kind": "page" }, { "preview": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDA2ODgyNS8y", "kind": "page" } ] }