Overview

Skill Level: Any

Content is made up of primarily elements that are defined in the content type. You can also add entirely new elements to Watson Content Hub. 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.

Step-by-step

  1. Review the list of available element types and their format

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

    Element type Description Format
    Text The text element holds text value in a JSON string.
    
    {
          "elementType":"text",
          "value":"Some text goes here"
    }
    
    Number The Number element stores the value in the JSON as a number type.
    
    {
          "elementType":"number",
          "value":42
    }
    
    Toggle Toggle just uses JSON Boolean.
    
    {
          "elementType":"toggle",
          "value":true
    }
    
    Link Link element has three text fields linkURL, linkText, and linkTitle. 
    
    {
          "elementType":"link",
          "linkURL":"http://ibm.com",
          "linkText":"IBM",
          "linkTitle":"IBM"
    }
    

    Date
    Date element uses a string property, the value must be an ISO 8601 date time.
    Category

    Category is a reference element. The contents that are stored in the category element are references to categories created in content hub. 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.

    File

    File element is the most basic asset reference element. It is a reference element that is used to point to an asset in content hub.

    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.

     Video

    Standard 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 hub. 

    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.

     Image

    Image 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!

  2. 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 on 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 on 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.

     

  3. Set image with Image Profile (renditions)

    Setting an image element with a rendition based on a profile involves many service endpoints and the individual services must be consulted for further information. For more information, go to API Explorer.

    1. Create an asset (prod-authoring-asset, prod-authoring-resource) or find an asset (prod-search-facade).
    2. Consult the Content-Type to determine the configured image profile for this element (prod-authoring-type).
    3. Use image profile to determine expected dimensions (prod-authoring-renditionprofile).
    4. Create a rendition (prod-authoring-rendition) based on the image profile dimensions from Step 3 based on the Asset from Step 1.
    5. Repeat step 4 if the image profile defines multiple renditions (for example, mobile and desktop).

    The image profile defines the keys that are used for the different renditions. For example, mobile or desktop.

    Same information as a regular image element applies. After you create the renditions that you can reference by ID, the asset information is calculated from the rendition selected.

    Note: All renditions must be renditions of the same asset.

Join The Discussion

Your email address will not be published. Required fields are marked *