Working with Rich Content Fields
Introduction
Working with rich content fields in the Aprimo DAM REST API requires knowledge of a JSON structure based on the Draft.JS format. This article will walk through how to interpret and create the structure so you can integrate rich content fields to other systems. Aprimo’s Article Editor functionality leverages rich content fields to create article content with rich styling.
Rich content fields can be retrieved or set like any other custom field in Aprimo, the only difference is that the value must conform to the format defined below. A simple way to understand the structure is to use the various features of a rich content field in the Aprimo UI, then GET the field data via the API to see how the output translates.
Format Definition
There are two top level properties in the JSON.
The blocks property is a collection of objects that contains the text and references to other content . There is only 1 blocks list, with numerous rich content fields are added to that same list. When rendered, content in blocks are separated by newlines.
The entitymap property is a collection of entities referenced by the block that contain information about entities inserted into the rich content field, such as other assets in Aprimo.
The structure and properties of these objects are defined below
- • Block Properties:
- key: a unique ID for the block.
- text: The unstyled text content of the block.
- type: atomic or unstyled
- depth: Indicates the depth of a nested list.
- inlineStyleRanges: A collection of inlineStyleRange objects, which represent the styling of text within the block. See below for properties.
- Offset: The start of the inline style in the text, 0 indexed.
- Length: The length of the string from the offset that has this style.
- Style: The style name (i.e. BOLD, ITALIC)
- entityRanges: A collection of entityRange objects which refer to additional entities part of the block, such as inserted assets and hyperlinks.
- Offset: The start of where this entity goes in the block, 0 indexed.
- Length: The amount of characters this entity is taking up.
- Key: The key referencing the entity representation in the entitymap object. See below.
- data: Contains various other data about the block, such as alignment.
- EntityMap: A set of properties that are a key/value pair, where the key is present in the entity range, and the the value is a complex type of entity.
- Entity properties:
- Type: CONTENTITEM, LINK, TEXTSNIPPET
- Mutability: IMMUTABLE or MUTABLE (set to immutable for contentitems & textsnippets; mutable for links)
- Data:
- For entities of type CONTENTITEM, data contains the guid of the record referred to plus the type of “Record.” Can optionally contain an “alignment” attributes, if not supplied left alignment is default
- For entities of type LINK, data contains the url property with the hyperlink URI
- For entities of type TEXTSNIPPET, data contains the guid of the record reffered to plus the type of “TextSnippet.” Can optionally contain an “alignment” attributes, if not supplied left alignment is default
- Entity properties:
Examples
Below are some examples of how to update rich content fields.
The first two examples show the format of a full call to update a custom field on endpoints such as PUT {{damurl}}/api/core/record/{recordguid}.
Subsequent examples show just the JSON definition for the rich content field, and will have to be escaped properly to pass in through the REST API.
Note that some line breaks are included for readability within JSON strings that are not technically valid, and languageId and fieldId will vary based on your configuration.
Example: Blank Rich Content Field
At a minimum, a rich content field must contain an array of blocks and the entityMap object.
An API call to set a blank rich content field appears below.
{
"fields":{
"addOrUpdate":[
{
"id":"d0377079-ea10-4220-b732-aa5701094665",
"localizedValues":[
{
"languageId":"00000000000000000000000000000000",
"value":"
{
\"blocks\": [],
\"entityMap\" : {}
}"
}
]
}
]
}
}Example: Creating a basic block
To create a block, you will need to specify the full definition for it and generate your own key if you are not updating an existing block. The example below creates a block with some basic, unstyled text.
{
"fields":{
"addOrUpdate":[
{
"id":"d0377079-ea10-4220-b732-aa5701094665",
"localizedValues":[
{
"languageId":"00000000000000000000000000000000",
"value": " {
\"blocks\": [
{
\"key\": \"3fmhm\",
\"text\": \"Basic Text\",
\"type\": \"unstyled\",
\"depth\": 0,
\"inlineStyleRanges\": [],
\"entityRanges\": [],
\"data\": {}
}
],
\"entityMap\" : {}
}
"
}
]
}
]
}
}Example: Styling Text and showing lists
To style text, use the inlineStyleRanges property within a block to specify the style and index/length of the styled text. For lists, set the type and depth properties accordingly.
{
"blocks": [
{
"key": "ba6ii",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed facilisis ligula ut lacinia ultricies. ",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 100,
"style": "ITALIC"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "aomsv",
"text": "",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [],
"entityRanges": [],
"data": {}
},
{
"key": "ail3v",
"text": "Donec id laoreet velit. Nam pharetra pretium odio et volutpat. Nunc semper laoreet ullamcorper. Nullam ut interdum ante, a eleifend nunc. In consequat ut diam non semper. Etiam commodo, magna eu bibendum hendrerit, risus tellus efficitur libero, non rutrum lectus erat non sapien. Pellentesque efficitur ullamcorper libero ac rutrum. Aliquam erat volutpat. Quisque tellus lorem, gravida eu malesuada in",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 402,
"style": "ITALIC"
},
{
"offset": 0,
"length": 402,
"style": "BOLD"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "633eo",
"text": "",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [],
"entityRanges": [],
"data": {}
},
{
"key": "d2gua",
"text": "nec ligula. Vestibulum dictum, lectus et posuere lobortis, augue tortor pulvinar diam, a sodales justo nisi ",
"type": "header-one",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 108,
"style": "ITALIC"
},
{
"offset": 31,
"length": 28,
"style": "UNDERLINE"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "bf9pa",
"text": "fermentum mi. ",
"type": "ordered-list-item",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 14,
"style": "ITALIC"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "eco87",
"text": "Vestibulum convallis, urna ut sollicitudin venenatis, est sem convallis lectus, ",
"type": "ordered-list-item",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 80,
"style": "ITALIC"
},
{
"offset": 0,
"length": 80,
"style": "BOLD"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "2sh4",
"text": "nec ",
"type": "ordered-list-item",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 4,
"style": "ITALIC"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "10vb",
"text": "aliquet turpis justo nec nunc. Proin commodo vulputate enim, eget fringilla nunc aliquam sollicitudin. Nam dolor metus, luctus sed eleifend in, rhoncus non est. Cras non enim condimentum dolor rutrum molestie.",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
{
"offset": 0,
"length": 209,
"style": "ITALIC"
}
],
"entityRanges": [],
"data": {}
},
{
"key": "937j0",
"text": "",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [],
"entityRanges": [],
"data": {}
},
{
"key": "c3kas",
"text": "",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [],
"entityRanges": [],
"data": {}
}
],
"entityMap": {}
}Example: Insert Asset
To insert an asset create an object in the entityMap object. For an asset, type should be CONTENTITEM, mutability should be IMMUTABLE, and the data object will contain the asset id and the type of asset it is. Any styling, such as alignment, will also be included here. An object will also have to be added to the entityRanges object of a block object. Offset should be set to 0, length should be set to 1, and key should be the key of the asset you want to map from entityMap
{
"blocks":[
{
"key":"6sqg",
"text":"",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"6nf0t",
"text":" ",
"type":"atomic",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
{
"offset":0,
"length":1,
"key":0
}
],
"data":{
}
},
{
"key":"eaerm",
"text":"Soccer Ball is left(default) aligned.",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"mqls",
"text":"This is some text. Above this text is a soccer ball asset and below it is a tree asset.",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"1f6o",
"text":"Tree is center aligned",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"buudp",
"text":"",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"7gpgq",
"text":" ",
"type":"atomic",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
{
"offset":0,
"length":1,
"key":1
}
],
"data":{
"alignment":"center"
}
},
{
"key":"e2qjp",
"text":"",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
}
],
"entityMap":{
"0":{
"type":"CONTENTITEM",
"mutability":"IMMUTABLE",
"data":{
"id":"eb04ac4fddea48b0b4fbaa4c0158bafa",
"type":"Record"
}
},
"1":{
"type":"CONTENTITEM",
"mutability":"IMMUTABLE",
"data":{
"id":"7d41249a65bf45e48741a9df0126fde2",
"type":"Record",
"alignment":"center"
}
}
}
}Example: Insert Hyper Link
To include a hyperlink in a block, create an object in the entityRanges that contains an offset that specifies which character in the text the link begins at, an integer length that specifies how many characters in the text starting from the offset the link will be, and the integer key that will reference an object in the entityMap object. An object must be added to the entityMap object. Type should be LINK, mutability should be MUTABLE, and the data object should contain a url attribute that’s value is the full url the hyper link should redirect to.
{
"blocks":[
{
"key":"qk8d",
"text":"This will take you to www.aprimo.com: To Aprimo",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
{
"offset":38,
"length":9,
"key":0
}
],
"data":{
}
},
{
"key":"7qcjn",
"text":"This will take you to google: To Google after text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
{
"offset":30,
"length":9,
"key":1
}
],
"data":{
}
},
{
"key":"7gfe2",
"text":"This will take you to Sharepoint: To Sharepoint",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
{
"offset":34,
"length":13,
"key":2
}
],
"data":{
}
}
],
"entityMap":{
"0":{
"type":"LINK",
"mutability":"MUTABLE",
"data":{
"url":"https://www.aprimo.com"
}
},
"1":{
"type":"LINK",
"mutability":"MUTABLE",
"data":{
"url":"https://www.google.com"
}
},
"2":{
"type":"LINK",
"mutability":"MUTABLE",
"data":{
"url":"https://aprimoco.sharepoint.com/_layouts/15/sharepoint.aspx"
}
}
}
}Example: Insert Hashtag
Hashtags do not need any special markup and will be automatically detected by the rich content field.
{
"blocks":[
{
"key":"c8ogk",
"text":"This rich content #field contains #text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"ak0ll",
"text":"",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"d8tdf",
"text":"#hashtag #aprimo #pen #glasses #hashtagwitha#hashtag",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
}
],
"entityMap":{
}
}