Search

Searching DEVELOPERS

Export Page

To complement the more tutorial-driven development demonstrations, this reference digs deeper into the content type schemas that underpin Content Authoring.

 Read about Schema Structure...

Content Authoring - Schema Structure

While every schema is different according to the content type it describes, all schemas have the same overall structure as described here using a sample "Article Grid" schema as an example.

 See the complete schema code...

Schema Header

The first part of the schema definition identifies that the container is described according to the JSON schema standard, and it specifies the self-referential schema ID.

Schema Metadata

The next part of the schema definition is the metadata that describes the schema. This metadata includes the name and description of the schema plus the icon image that is used to represent it in the Content Authoring UI. It also includes details of the card that will be used to preview the content in the UI, plus the mapping between schemas fields and the displayed card fields.

Note that the text entered into the "name" field of a content type schema will be the human-readable friendly name for the schema that is displayed as a label in the UI. This text will be slugified (e.g. spaces converted to dashes and all characters made lowercase) by our system when forming the schema reference URL.

Schema Validation

The next section defines validation, in this case that the container must validate against "all of" the included definitions:

Schema Definitions

The following definitions section defines the content elements that a content editor user can populate when creating a content item, with this set of definitions also being used by the Content Authoring UI to build a schema-compliant input form for the content type described by the schema:

The schema section shown above defines the allowed content labelled "articleList" as being an "array" type comprising at least one item that complies with the validation required for a "contentLink". Besides being of type "array", the articleList is further constrained by being of semanticType "list".

A note about Inline Schemas...

The purpose of inline schemas is to include one schema's content within another schema's content "by value" in a composition arrangement, such that the lifetimes of the main content and included content are tied together... and so that the included content cannot be shared as a component of other owning content entities. This is in contrast to merely linked content that has a completely independent existence and can be shared among owning entities.

For the inline content case, the following schema code snippet shows how an inlined sub-schema can be included in an array. This includes the necessary "_interpolate": true indication that is required for inline schemas.

 Read about Schema Data Types...

Content Authoring Schema Data Types

To complement that JSON primitive data types that include numbers, strings, booleans, arrays and objects, we support a range of semantic data types that further constrain and validate those primitive types. In the following schema extract, you can see how a "heading" field of type "string" is associated with the semantic type "text" that defines it as a plain text string.

In contrast, the following schema extract shows how a "Body" field of type "string" is associated with semantic type "markdown" that signifies to the Content Authoring UI and any front-end application that this text string can include Markdown mark-up syntax.

Supported Semantic Types

The list of supported semantic types is detailed below, beginning with the group of semantic types that may be applied to strings.

String Semantic Types

Semantic type text defines a natural language plain text string.

Semantic type symbol defines a non-natural-language plain text string such as a product SKU.

Semantic type markdown defines a text string marked up with Markdown syntax.

Semantic type uri defines a Uniform Resource Identifier (URI), which must be used in conjunction with “format”:“uri”.

Semantic type date-time defines a RFC3339 date, which must be used in conjunction with “format”:date-time”.

Semantic type email defines an email address, which must be used in conjunction with “format”:email”.

Boolean and Number Semantic Types

Semantic type boolean extends the "boolean" primitive type for true-false values.

Semantic type number extends the "number" and "integer" primitive types for numeric values that may have minimum and maximum allowed values, e.g.

"_semanticType":"http://semantic-type.cms.amplience.com/number",
"minimum":50,
"maximum":100

Asset Semantic Type

Semantic type asset extends the "object" primitive type to reference media assets such as images and video. When using this semantic data type you must include "allOf" validation that references the "di-asset-link" schema, and you must constrain the type of media to image (or video, or both) by adding an "enum" validation to the "mediaType" property as shown here:

 See the Image Asset code...

Array / List Semantic Types

Arrays of primitive types can be defined quite simply by associating the list semantic type with the "array" primitive type (and in this case associating the text semantic type with the "string" primitive types contained as "items" within the array):

 See the Array of Primitives code...

Taking this a stage further, arrays work by adding constraints to the items that tell the system what can go into the array. You must provide the correct semantic type for the "items” in the array; for example the semantic type asset that defines each of the array entries as a "di-asset-link" as shown here:

 See the Asset Array code...

We support mixed sets of asset / di-asset-link and content / content-link (as shown below) so that you can create an array of slides or images.

 See the Mixed List code...

  

Semantic Types Rendering in the Content Authoring User Interface

The use of semantic types allows the Content Authoring user interface to render content type input forms in particular ways, such as rendering a boolean type as a check-box or toggle control. In the case of arrays (of semantic type list), the UI can allow the user to add additional list entries (e.g. text strings or images) up to the maximum number of items allowed.

 Read about Schema Validation...

Content Authoring Schema Validation

Schema developers can specify validation for the items defined within the schema as described here. Validation serves two purposes:

  1. To constrain the values that content editor users can enter as content into form fields.
  2. To trigger the Content Authoring UI to present form fields in a particular way; e.g. as a drop-down list for enumerated items. 

Minimums and Maximums Validation

We support minLength / maxLength validation for string items, and minItems / maxItems validation for arrays. These kinds of validation are illustrated in the following schema code extract.

Note that we do not validate the validation itself. For example: where validation defines minLength and maxLength (or minItems and maxItems) to constrain form fields, we do not check that the schema developer entered valid values for those validations; i.e. that minLength < maxLength.

Combining Schema Validations with "allOf", "anyOf", "oneOf" and "not"

We support the JSON Schema "allOf", "anyOf", "oneOf" and "not" keywords for combining schemas. These keywords correspond with traditional boolean AND, OR, XOR and NOT operators as follows:

allOf (AND) means that the given data must be valid against all of the included sub-schemas.

anyOf (OR) means that the given data must be valid against at least one of the included sub-schemas.

oneOf (XOR) means that the given data must be valid against exactly one of the included sub-schemas.

not (NOT) means that the given data is valid if it does not validate against any of the sub-schemas.

In the following schema code for a mixed asset array, each of the array items must be oneOf an "asset" or "content"; with an "asset" item being allOf a "di-asset-link" and media type "image" whereas a "content" item must be allOf a "content-link" and content URI.

Enum Validation

When applied to string (as in the schema code shown below), the enum semantic type will cause a drop-down list to be rendered in the Content Authoring content type form.

Note that in this example it is the enum semantic type that triggers the UI to render a drop-down list, and not the JSON "enum" keyword that simply constrains the values that may be accepted for the input string. The JSON "enum" keyword may also be used in other ways to constrain items, such as in the earlier example of constraining a "mediaType" to be an "image".  

 Read about Schema Icons...

Content Authoring Schema Icons

Within the Content Authoring tool, developer-created schemas are represented by icons as shown here:

The icon used to represent a particular schema is set in the "icons" section of the "meta" section of the schema, as shown here for the "Article" content type schema:

All icons have the same base URL suffixed with the name of the particular icon image, so the paths to the other available icons would be:

You can determine the icon URL for any particular content type by opening the schema for editing in the Schema Editor, for example if you would like to reference the same icon in another content type schema.

 Read about Library Cards and Visualization...

Content Authoring Library Cards and Visualization

The Content Library displays content items using "cards" that provide preview representations as shown below. These cards offer improved content navigation and identification compared with simple content file names.

 

As with a content type schema's icon, the card that is used to visualize any content for a particular content type is defined in the "meta" section of the schema:

The uri property references the HTML page of the card that will be used to provide a preview rendering of any content for this content type schema, and the optional mapping property defines the mapping between content type fields and card display fields. Content schemas are written in JSON format and use the JSON Pointer standard for identifying a specific value, such as an image at the specified index in an array. You'll need to use this notation in your card's mapping section if you use nested content types. You can find an example in the Gallery section of the Content Authoring- Built-in Library Cards page.

See the cards tutorial for more details of how to configure cards for your content.

While there are many built-in cards, it is also possible to define your own, and to host them pretty much anywhere that is accessible via a URI. For a list of the built-in cards together with examples of their use, see Content Authoring- Built-in Library Cards

Visualization

The basic library cards idea can be extended with a visualization. A visualization provides a preview of content that is as close as possible to how it will appear on your production site. If a visualization has been added to a content schema, then it will be displayed in the content editing window, as shown below. You can use the device menu to preview the content at different sizes or detach it and view it in its own window.

A visualization is a specific category of card and is specified in the "card" section of the content type schema. When a visualization is added for a content type, the card section must be represented as an array and the uri parameter for the visualization entry will be the uri of the web app that implements the visualization. In the example below, the visualization uri is 

https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/Visualizations/viztutorialpoi.html

Note the first entry, specifying the library card, must include entries for id, category and default: 

"id": "defaultCard",
"category": "card",
"default": true,

otherwise the visualization will not be displayed.

See the visualizations tutorial for a step by step guide to adding visualizations to your content types.

 

 Read about the Content Delivery API and SDK...

Content Authoring Delivery API and SDK

The Content Delivery API and SDK together allow you to retrieve published content to be rendered by a front-end application.

Delivery API

The Delivery API allows you to access published content via a simple HTTP GET request, which returns the content in JSON-LD format.

Request

The Delivery API can be accessed via the URL https://c1.adis.ws/cms/content/query? suffixed with the a URL encoded query of the following form (where id is the unique identifier of the content to be retrieved) :

{"sys.iri": "{id}"}

Here is the AJAX / jQuery client-side Javascript code for a fully formed content query:

The 'scope' parameter specifies the objects that are returned by the API:

scope 
treereturns the full dependency tree
rootreturns only the root object

if no value is specified, then scope will be set to 'tree'.

Note that whereas this example uses “sys.iri”:”iri” to query a single content-identifying IRI, it is possible instead to use the MongoDB syntax "$in" operator to query a list of IDs as shown in this JSON code:

The ID of a particular content object, plus the URL used to access it via the API, can be determined by clicking the "Get Asset Link" (chain-link) icon for the content in the Content Library as shown here:

Response

Clicking the "View LIve Delivery URL" link shown in the previous picture causes the content to be queried and displays the result in a web browser window like this:

The API response uses the lightweight linked data JSON-LD format (see http://json-ld.org/) that allows applications to follow links between one piece of data and another. The results are placed in an @graph array, which is easier to see in the following screenshot of the Delivery API test application at http://apps.dev-artifacts.adis.ws/cms-delivery-playground/master/3/index.html?apiBase=https://c1.adis.ws/cms/content/query:

 

SDK

The SDK exposes an inlineContent method on the amp namespace which flattens the content graph returned as the API response. It can be invoked from Node or a web browser (>=IE8) as follows.

Node

var amp = require('cms-javascript-sdk');
amp.inlineContent({{content}});

Browser

<script type="text/javascript" src="cms-javascript-sdk.min.js"></script>
<script type="text/javascript">
amp.inlineContent({{content}});
</script>

Combined API and SDK Example

The following combined code snippet retrieves content via the API, inlines it using the SDK, and logs out the content to the browser console log.

 See the combined API and SDK code sample...

For a detailed step by step example, see the Content Authoring Developer Tutorial Part 1: Quick Start

Delivery API - Default Cache Settings

The Amplience CDN architecture caches delivery API responses in the following manner:

  • Edge Servers - 300 seconds (5 minutes)
  • Mid Tier Servers - 300 seconds (5 minutes)

Therefore, when updating existing content, the maximum time you will have to wait to see the updated directly from the delivery API is 10 minutes

 Read about Dynamic Media...

Content Authoring Dynamic Media

Dynamic Media allows dynamic imaging and dynamic video to be delivered into any channel and device format from a single master asset.

URL Structure

Images and video are retrieved using a simple URL structure comprising the media type, account name, and the name of the asset you wish to return.

Images: /i/{account}/{image}

Videos: /v/{account}/{video}

Sets: /s/{account}/{set}

Parameters

A range of parameters can be appended to the URL in order to dynamically modify the retrieved asset(s). Such modifications are performed on-the-fly without affecting the original asset, and there are no restrictions on how many parameters may be appended to each URL.

Parameter example: /i/{account}/{image}?{list of parameters}

Real life example: /i/playground/flower1?w=300

Multiple Parameter example: /i/playground/flower1?w=300&crop=100,100,200,200

More Information

More information about Dynamic Media can be found at http://playground.amplience.com/di/app/#/intro.

 Read about Front-End Developer Tooling...

Content Authoring Front-End Developer Tooling

Upon selecting the "Get content ID / link" icon (1) for a content item, the pop-up dialog includes a hyperlink to "View in JSFiddle" (2).

Clicking the link allows you to use the JSFiddle online editor (as shown below) to make changes to front-end HTML, Javascript and CSS code and to see the results of those changes.

 Running the Fiddle and then clicking on the "View JSON" message allows you to see JSON-LD content response, like this:

 

 Read about the Built-in Library Cards...
Cards are used in Content Authoring to present a visual summary of content in order to make it easier to identify in the content library. Content Authoring provides a set of built in cards that show content in different ways, allowing you to choose an appropriate card for each content type. 

As explained in the Cards and Visualisations tutorial, the card to use for a particular content type is specified in the content type schema, by including that card's URI. Each card is designed to display different content elements. Some cards include a mixture of images and text, while the Handlebars card is much more flexible, allowing you to use a handlebars template and CSS file to render your own representation of the content.

Mapping

To use each card, apart from Handlebars, you need to specify a 'mapping' section in the content schema. This section maps the content elements defined in the content schema, to the appropriate sections of the card. For example, if a card displays an image, then the 'image' element might be mapped to the "background" element in your content schema, as shown below.

Content schemas are written in JSON format and use the JSON Pointer standard for identifying a specific value, such as an image at the specified index in an array. You'll need to use this notation in your card's mapping section if you use nested content types, such as a carousel that contains an array of slides. Each slide would then contain an image and you'd access each image as shown in the example below. In this example, the slides are contained in an array called "imageblock". The complete example is shown in the Gallery section below.

Examples of each of the built-in cards, together with the mapping section and example content schemas are shown below.

 

The library cards are updated on a regular basis to include performance improvements and add new features. To ensure that you are using the latest version of each card, use the URIs shown on this page. These URIs include 'latest' in the card's path.

Gallery

Gallery is the library card added to the schema by default when you create a new content type. It's also what we use in the tutorial.

uri:  //apps.dev-artifacts.adis.ws/cms-cards/master/latest/gallery/index.html

mapping: headline, image0. Optionally image1, image2, image3

The gallery card displays a piece of headline text, together with between 1 and 4 images. The images are arranged in a grid layout. In the first example, we're just showing the background image and the headline.

To use the Gallery card, adding headline and image 0 (and optionally image1,2 and 3) to the card section of the content schema.

The complete content schema used in this example is shown below.

 

 Click here for the content schema...


Displaying multiple images

To display two or more images using the gallery card, add the images to the mapping section. In this example we are using a carousel that contains a list of slides, each containing a single image. This uses the JSON Pointer standard as explained in the introduction.

This specifies that four images should be displayed. The gallery card will layout these images in a grid.

 Click here for the content schemas...
 Click here to expand the carousel schema..
 Click here to expand the slide schema...

 

 

 

Text

The Text library card displays the headline text centred on the card rendered at 24 point. This card is useful in the cases where you want to identify a piece of content based on its text rather than images.

uri:  //apps.dev-artifacts.adis.ws/cms-cards/master/latest/text/index.html

mapping: headline

To use the Text card the only field required in the mapping section is the headline.

The content schema for this example is shown below.

 Click here for the content schema...

Summary

The Summary card displays a headline and subheading, together with an image. 

uri:  //apps.dev-artifacts.adis.ws/cms-cards/master/latest/summary/index.html

mapping: headline, sub, image

To use the Summary card include the mapping for the headline, sub and image. Note that the image must be included for the library card to display correctly.

The content schema for this example is shown below.

 Click here for the content schema...

Photo

uri: //apps.dev-artifacts.adis.ws/cms-cards/master/latest/photo/index.html

mapping: image

The Photo library card just shows a single image, centred on and filling the card.

To use the Photo card just include the mapping for image in the content schema. 

The content schema for this example is shown below.

 Click here for the content schema...

Handlebars

uri: //apps.dev-artifacts.adis.ws/cms-cards/master/latest/handlebars/index.html

mapping: For the Handlebars card, no mapping is required, since the card is rendered using a handlebars template and CSS file.

In this example we have chosen to render the headline, sub heading, background image and the "call to action" button. While the button is not functional in the library card, it does provide a more accurate representation of the content and shows the flexibility you have when using a handlebars template.

To use the handlebars card, add a "params" section to the card definition in the content schema:

cssThe URL for the CSS file. This is an optional parameter
templateURLThe URL for the handlebars template

Further optional parameters can be specified:

preRenderThe URL for a JavaScript file to be run before the card is rendered
postRenderThe URL for the JavaScript file to be run after the card is rendered

The complete content schema, CSS file and handlebars template used in this example are shown below:

 Click here for the content schema...

 

 

 Click here for the Handlebars template...
 Click here for the CSS file...
 Read about Creating Your Own Library Cards...

 

This page provides background reference information for developers who want to create their own library card for use in the Content Library in Content Authoring. If you wish to create your own card, please contact your Customer Success Manager for more details.


About Cards

As discussed in the Cards and Visualisations tutorial, Cards in the Content Library provide a graphical representation of a piece of content. In most cases developers will use one of the built-in cards such as the Gallery or Summary card and specify which card to use in the Content Type schema. For more advanced uses there is also a handlebars card that provides you with a lot of flexibility and allows you to add your own CSS styling, handlebars template and JavaScript code to render content. The built-in cards are described in detail in the built-in cards page. The built-in cards are generally sufficient for most cases, but if you use your own templating technologies or want to use some specific libraries of code, then there may be cases where you want to write your own library card.

This page takes you through step but step the process of creating your own library card, using a simple version of the Gallery card as an example.

The card to use to display content is specified in the 'card' section of the content type schema. In this example we have created a custom card called 'tutorialcard', uploaded this to AWS and referenced it from the schema. The card consists of an HTML file, together with some CSS and JavaScript. The card accepts mapping elements: a background image and some headline text to be displayed below the image.

When a library card is shown in the Content Library, the card web app is responsible for rendering content within the an iFrame on the card itself. This area excludes the title, the publish status icon and the contextual menu and the custom tutorial card is shown with a blue border in the image below.

When you write your own card, you will be responsible for rendering a representation of the content within this iFrame. Note that cards need to be designed to be responsive, since size of the cards will vary as the user grows or shrinks the content library window. 

Step 1: Decode URL

Cards are single page applications that adhere to a a basic URL convention

<URL of card>?src=<encoded url of content API GET request>

This URL includes sufficient information to render its representation of the content within the iFrame.

An example of this URL is shown below.

 Click here for an example URL with query parameters…

As you can see the URL is quite long. The reason for this is that the encoded URL represents the URL of the GET request to be made to the Delivery API and also includes a time based, single use token that is used to retrieve the content.  

The 'src' element is then extracted from the URL and decoded. An example of a decoded 'src' element is shown below.

 Click here for an example decoded src element...
 Click here for some sample code…
This code will extract the query component from the URL and decode it using the standard JavaScript decodeURIComponent function. The query is then sent as an AJAX Get request to the Content API.

 

Step 2: Request Content

The decoded URL is then sent as the content of an AJAX GET request to the Delivery API. An example of the code of some standard code to send the Get request is shown below.

 

 Click here for an example AJAX GET request...

This code uses the Q promise library, but you probably have your own code for making an AJAX request and handling the result.

Assuming the request is successful, the JSON content of the item to be shown on the card is returned, including the JSON schema. The schema is required because it contains the 'mapping" section that specifies which content elements to include on the card.

An example of the response from the Content API is shown below. 

 Click here for an example of the JSON content and schema...


Step 3: Flatten Content

The content graph is then converted into a content tree using the amp.inlineContent method. Here's an example of the converted content tree:

Here is some example code that shows how to build the content tree. Note that the content schema is also stored, since this will be needed to map the content elements to be displayed on the card to the actual content.

 Click here for some sample code…

This code takes the content returned by the AJAX Get request and returns the flattened content and the schema.

Step 4: Store the schema

'schemas' is returned as an array, so you will first need to retrieve the schema that applies to this piece of content. Use the 'type' field as the index into the schemas array. For this content it is:

  "@type": "http://schema.cms.amplience.com/448506a3-cf6b-4103-b592-697da7195ac7"

So we can retrieve the schema we need using the following code:

var schema = schemas[content["@type"]];

And then access the mapping:

var map = schema.meta.card.mapping

and create the map as  explained in Step 5 below.

Step 5: Extract mapping information

As covered in the Cards & Visualisations tutorial, in the schema when you specify the card to be used for the content, you also include mapping information. This tells the card which content element to map to which area within the card. In our example we just specify two mappings: headline and image. 

 

This mapping is now used to set headline and strapline to the actual assets to be displayed on the card. The mapped content will look something like:

To produce this mapping we combine the content with the mapping parameters defined in the content schema. The code below provides an example of how to do this.

The example uses the standard JSON.pointer implementation to combine the mapping and the content into an array of key value pairs. The key being the mapping parameter and the value the content it maps to, in this example the URL of the image and the headline text. You might choose a different technique to produce the mapped content that's shown above.

In the example code, the map parameter is the mapping from the content schema as shown in Step 4.

while content is the inlined content from Step 3.
 Click here for some code that creates the map..

 

Step 6: Render card content

Once the content map is produced, each element is then extracted and added to the card. In this example the background image URL is:

https://ext1.adis.ws/url/portal/f3cf94f8-5486-4a18-8451-a99f99c2fea9 

The following code shows how to construct this URL from the mapped content by combining the defaultHost, endpoint and name fields.

 Click here for example code to construct the image URL...

Once the URL is constructed it can then be added to the card. One approach is to represent the image with a CSS element and then set that element's 'src' parameter to the image URL. In the simplified code below the CSS element is '.image':

    imgElm =  document.querySelector('.image');
imgElm.src = url

You would also need to include a default image or some text to be used if the background image cannot be loaded. To apply Dynamic Imaging commands to the image, just add these to the URL as query parameters in the normal way.

Adding the headline text would take a similar approach, retrieving a 'headline' CSS element and setting this to the text from the mapped content:

document.querySelector('.headline').innerHTML = mapped.headline;

The text would need to be "sanitised" to remove any potentially dangerous characters. Some sample code to do this can be found here.

 

 

  • No labels