Author content

Content is made up of primarily elements that are defined in the content type. You can also add entirely new elements to Content. Custom user interfaces can be used to define the display and function of an element in the content authoring form. For more information, see Custom user interfaces. You can reference a content type for the content through the typeId attribute in the authoring content rest API. A content can have multiple elements such as text, number, video, and images. Each element type has a different representation and a content can have multiple elements of the same type. Based on how it is configured, some elements like images have different representations. For example, images with image profile or not.

Review the list of available element types and their format

The following table lists the element types that are available and their format.

Element typeDescriptionFormat
TextThe text element holds text value in a JSON string.{
"elementType":"text",
"value":"Some text goes here"
}
NumberThe number element stores the value in the JSON as a number type.{
"elementType":"number",
"value":42
}
ToggleToggle just uses JSON boolean.{
"elementType":"toggle",
"value":true
}
LinkLink element has three text fields linkURL, linkText, and linkTitle.{
"elementType":"link",
"linkURL":"http://cms.com",
"linkText":"Acoustic",
"linkTitle":"Acoustic"
}
DateDate element uses a string property, the value must be an ISO 8601 date time.{
"elementType":"datetime",
"value":"2016-11-02T22:30:00Z"
}
CategoryCategory is a reference element. The contents that are stored in the category element are references to categories created in Content. When ?include=metadata is used, the categories property is included which has the full name path for each selected category.

Note: When you set categories on the category element, you need to add the UUID of the category to the categoryIds property. The categories property, which returns the name path of the category is a read-only property and is not used when the content is updated. If you set it during an update, it is ignored.
{
"elementType":"category",
"categoryIds":[
"9cb72485075dc4a5fc8fec56e61974e6"
],
"categories":[
"Location/Australia/Sydney"
]
}
FileFile element is the most basic asset reference element. It is a reference element that is used to point to an asset in Content.

Except for asset ID, all the other properties are read-only and are added from the asset at the time it is selected on a content.

With asset references most of the properties are read-only and come from the asset. So when you set a file on file element you need to set the asset.id property. The other information is fetched automatically by the content service and stored in read-only fields.
{
"elementType":"file",
"asset":{
"id":"30940dbb-4f9b-4e7f-a19b-cb6011c42574",
"resourceUri":"/authoring/v1/resources/d57f05536ff005ae00cd1573f62111c7",
"fileSize":360,
"fileName":"text.rtf",
"mediaType":"text/rtf"
}
}
VideoStandard video element is similar to the file element. The video asset is represented in the asset section. Optionally a video asset can have a caption and a thumbnail as well, and in this case both of these point two resources in Content.

As mentioned with file, most of the properties here are inlined data from the asset/resource and is read-only. To update a video asset or its caption/thumbnail update the relevant asset/resource ID. The related information is retrieved again and added. Attempts to change the read-only fields are ignored.
{
"elementType":"video",
"caption":{
"resourceId":"417aba003e620208727b794382c74bb5",
"resourceUri":"/authoring/v1/resources/417aba003e620208727b794382c74bb5",
"fileName":"subs.vtt"
},
"thumbnail":{
"resourceId":"9ca782f37cd6d8d4c5bd42eb7edf2349",
"resourceUri":"/authoring/v1/resources/9ca782f37cd6d8d4c5bd42eb7edf2349",
"fileName":"800px-Four_solaire_001.jpg"
},
"asset":{
"id":"6ff32201-f5cb-4f3c-82bd-0c6a635fd907",
"resourceUri":"/authoring/v1/resources/02f6fdf2794ed2e6ffa84a38e32c37cc",
"fileSize":1274225,
"fileName":"autobot.mp4",
"mediaType":"video/mp4"
}
}

Setting or Updating Format for Video with Caption and thumbnail
{
"elementType":"video",
"caption":{
"resourceId":"417aba003e620208727b794382c74bb5"
},
"thumbnail":{
"resourceId":"9ca782f37cd6d8d4c5bd42eb7edf2349"
},
"asset":{
"id":"6ff32201-f5cb-4f3c-82bd-0c6a635fd907"
}
}
Setting or Updating Format for Video

{
"elementType":"video",
"asset":{
"id":"6ff32201-f5cb-4f3c-82bd-0c6a635fd907"
}
}
ImageImage is one of the more complex elements and the following section describes a normal image without an image profile configured. For information on updating and formatting the image element, see the following Updating image element format step in this tutorial.

Note: You are always selecting a rendition of an asset and not the asset directly.

As a result interactions with image elements involve setting and updating a rendition reference. Most other fields that are displayed in image element are read only!
{
"elementType": "image",
"mode": "shared",
"altText":"This is a tree!",
"profiles": [
"0585e337-d2ca-445f-a8eb-b1700a2739d8"
],
"asset": {
"id": "bfef5514-e65b-48f4-9857-907d17635520",
"resourceUri": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133",
"fileSize": 486223,
"fileName": "Tree.jpg",
"mediaType": "image/jpeg",
"width": 1440,
"height": 900,
"altText": ""
},
"renditions": {": {
"source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133?resize=640px:400px&crop=100:400;270,0",
"width": 100,
"height": 400,
"transform": {
"scale": 0.44444,
"crop": {
"x": 270,
"y": 0,
"width": 100,
"height": 400
}
}
}
}
}

Update the image element format

Image is one of the more complex elements. You can update the image element to set alt text and image profile renditions in either shared or snapshot mode.

1. Shared mode

In shared mode, the image element uses whatever resource is set on the asset. Therefore, updating the image on the asset updates all the content image elements that use the asset. You need to specify the mode and asset ID. The alt text is optional.

{
      "elementType":"image",
      "mode": "shared",
      "asset":{
        "id": "bfef5514-e65b-48f4-9857-907d17635520"
      },
      "altText":"This is a tree!"
}

After the image element is successfully saved, additional asset information and any renditions are expanded.

{
      "elementType": "image",
      "mode": "shared",
      "altText":"This is a tree!",
      "profiles": [
            "0585e337-d2ca-445f-a8eb-b1700a2739d8"
      ],
      "asset": {
            "id": "bfef5514-e65b-48f4-9857-907d17635520",
	    "resourceUri": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133",
            "fileSize": 486223,
            "fileName": "Tree.jpg",
            "mediaType": "image/jpeg",
            "width": 1440,
            "height": 900,
            "altText": ""
      },
      "renditions": {
            "wide": {
                  "source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133?resize=400px:250px&crop=400:100;0,75",
                  "width": 400,
                  "height": 100,
                  "transform": {
                        "scale": 0.27777,
                        "crop": {
                              "x": 0,
                              "y": 75,
                              "width": 400,
                              "height": 100
                        }
                  }
            },
            "tall": {
                  "source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133?resize=640px:400px&crop=100:400;270,0",
                  "width": 100,
                  "height": 400,
                  "transform": {
                        "scale": 0.44444,
                        "crop": {
                              "x": 270,
                              "y": 0,
                              "width": 100,
                              "height": 400
                        }
                  }
            }
      }
}

In the example provided for shared mode, the renditions (wide and tall) are extracted from asset bfef5514-e65b-48f4-9857-907d17635520 because they are part of the image profile 0585e337-d2ca-445f-a8eb-b1700a2739d8. This image profile must be defined in the content type.

2. Snapshot mode

In snapshot mode, the image element always uses the image from the asset at the time it was saved. Updating the image on the asset will not update any of the content image elements that uses the asset. You need to specify the mode and asset ID. The profiles and renditions are optional. You can specify your own rendition transformations. Any renditions that are defined in the content type is automatically generated by using a best-fit transformation. The alt text is also optional.

{
      "elementType":"image",
      "mode": "snapshot",
      "profiles": [
            "5dcc54bf-92f2-4d3a-8e24-a83c72e3d971"
      ],
      "asset":{
        "id": "bfef5514-e65b-48f4-9857-907d17635520",
      },
      "renditions": {
            "wide": {
                  "transform": {
                        "scale": 0.7,
                        "crop": {
                              "x": 1,
                              "y": 134,
                              "width": 400,
                              "height": 100
                        }
                  }
            }
      }
      "altText":"This is a tree!"
}

After the image element is successfully saved, additional asset information and any extra renditions that are needed are generated.

{
      "elementType":"image",
      "mode": "snapshot",
      "profiles": [
            "5dcc54bf-92f2-4d3a-8e24-a83c72e3d971"
      ],
      "asset": {
            "id": "bfef5514-e65b-48f4-9857-907d17635520",
	    "resourceUri": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133",
            "fileSize": 486223,
            "fileName": "Tree.jpg",
            "mediaType": "image/jpeg",
            "width": 1440,
            "height": 900,
            "altText": ""
      },
      "renditions": {
            "default": {
                  "renditionId": "r=283bab90-a1a1-41db-85e8-2a039015d133&a=bfef5514-e65b-48f4-9857-907d17635520",
                  "source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133",
                  "width": 1440,
                  "height": 900
            },
            "wide": {
                  "source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133?resize=400px:250px&crop=400:100;1,134",
                  "width": 400,
                  "height": 100,
                  "transform": {
                        "scale": 0.7,
                        "crop": {
                              "x": 1,
                              "y": 134,
                              "width": 400,
                              "height": 100
                        }
                  }
            },
            "tall": {
                  "source": "/authoring/v1/resources/283bab90-a1a1-41db-85e8-2a039015d133?resize=640px:400px&crop=100:400;270,0",
                  "width": 100,
                  "height": 400,
                  "transform": {
                        "scale": 0.44444,
                        "crop": {
                              "x": 270,
                              "y": 0,
                              "width": 100,
                              "height": 400
                        }
                  }
            }
      }
}

In the example provided for snapshot mode, the rendition tall was generated because no transform instructions for it were given and it is part of the image profile 0585e337-d2ca-445f-a8eb-b1700a2739d8. This image profile must be defined in the content type.

📘

Note:

When a snapshot asset is created, it pre-creates a default rendition automatically.
Most fields are read-only and cannot be changed. The content is round-trippable. You don't need to strip out read only fields. The service ignores any changes.