Search

Searching DEVELOPERS

Export Page

Here we explain the key concepts that underpin the use of Content Authoring from the perspective of the software developer.

 Read about the "Data Modelling" concept...

Content Authoring Concepts - Data Modelling

One of the first steps when using Content Authoring is to define the content data you wish to store. This process usually involves breaking down specifications, wireframes and designs into components that can be implemented using primitive data types. These components are encoded as JSON schemas which define the content type templates that will be to content creators as screen forms.

Let's take a very simple example of a carousel shown schematically as a wireframe here:

The wireframe above comprises:

  • A title.
  • Image content.
  • Navigation arrows.
  • Slide selector dots.

When modelling the data for this wireframe, we make the following assumptions:

  • The title applies across all slides, not unique to each slide.
  • Each slide contains only an image.
  • The navigation arrows and screen selectors are user interface properties that do not require any specific content.

In the table below, you can see our example data model that defines a title string plus multiple slides in an array.

FieldTypeValidationAcceptance Criteria
carouselTitleString
  • Mandatory
  • Maximum of 255 characters.
  • Content is entered in plain text format.
  • Schema will not save without a title.
  • Use can enter alpha, numeric and special characters.
carouselSlidesArray
  • Mandatory
  • Minimum of 1 slide.
  • Maximum of 5 slides.
  • Slides can be re-used.
  • Slides must be imaged from the Amplience Dynamic Media platform.
  • Slides can be re-ordered.
  • Slides can be removed.

The JSON schema that implements the data model, and which includes appropriate validation (see Content Authoring - Schema Validation), is given here:

 See the JSON Schema code...

The content type form that is generated for this schema in the Content Authoring app is as shown below. Note the correspondence between the form fields and the original modelled data fields.

In the example screen shown above, the content editor user has populated the content type form with a title and a number of images. When published, the JSON-LD response for this content is as follows.

The URL for this content response, which would be used to retrieve the content into a front-end application via the Delivery API is https://c1.adis.ws/cms/content/query?fullBodyObject=true&query=%7B%22sys.iri%22%3A%22http%3A%2F%2Fcontent.cms.amplience.com%2Fa276f425-8802-4f99-a6a4-96ba18cc1ba4%22%7D&scope=tree&store=playground

 Read about the "Schema Relationships" concept...

Content Authoring Concepts - Schema Relationships

There are two methods for combining content:

  • Nested / Linked content, whereby the linked item is independent and may be shared by a number of assets that all link to it.
  • Inline content, which forms part of the whole and is indivisible from it, thereby providing reuse of structure but no reuse of content. 

Nested / Linked Content allows the user to create and add other content types to an existing content item; for example the user may wish to compile a carousel made up of several different image slides. This approach to linking otherwise independent content allows for re-use, by making the linked content available via the Content Browser as an independent item. One effect of this is that an update to the linked content will be reflected in all the content that links to it; e.g. all carousels that show a particular image slide will change if the image slide is updated. In technical terms, this is like linking objects "by reference" in an association arrangement.

Inline Content works by embedding one content type within another one by (the developer) embedding one schema within another one, which in technical terms is like linking the objects "by value" in an aggregation / composition arrangement. It is applicable to simple compositions where a particular set of fields and validation are required for inclusion in a particular content type but without the values being shared across multiple content objects. 

Analogies

Web pages tend to be linked into many other web pages, hence the content contained within a particular page (which exists in its own right) may be shared or re-used across other pages. This is nested or linked content. 

In contrast, the chapters of a novel are unique to that particular novel. So while the definition of a chapter (as a thing with a title and a number of prose paragraphs) may be reused across all novels and even non-fiction books (because they all have chapters), no two books contain the same chapters.

Content Authoring Concrete Examples

Theory is all well and good, but the distinction is best illustrated with a couple of concrete examples in the context of Content Authoring.

Nested / Linked Content

The Product Article content type allows you to include one or more existing Articles as shown in the following picture. These Articles are independent of the Product Article into which they are being included, and the content editor includes them by browsing for them using the Content Browser. Any Article may be nested into / linked to more than one Product Article.

Inline Content

Various content types including carousel slides and images may require the exact same standardised "call to action" with a fixed number of fields (Image Url , Call to Action Label, Call to Action Url) and associated validation as shown below, but with distinctly different values in each case. So the same structure may be reused across several schemas, but not the content entered into that common structure.

Inline content never exists in its own right independent of the containing content, and hence cannot be reused via the Content Browser of the Content Authoring application.

When to Use Each Kind of Included Content

When deciding between nested content and inline content, the things you should consider include:

Granularity: Do you merely want to break down a big unwieldy schema into smaller parts for clarity, and to factor out potentially reusable definitions? This would be inlining.

Reuse: Do you also want the content items defined by these sub-schemas to be shared among multiple content items? This would be nesting or linking.

Ownership / Lifetime: Do the items defined by the sub-schemas somehow "belong" to the containing schema, such that they should cease to exist at the same time? This would be inlining.

In context of the Content Authoring workflow, it is the developer who determines what schema structures get reused through inlining whereas it is the content editor who decides what content gets reused via nesting / linking.

 Read about the "Validation" concept...

Content Authoring Concepts - Validation

Validation can be applied to schema attributes. These validations allow the data model to be constrained to contain information only in formats that renderers can understand. Enforcing the data model through validation can reduce the need for testing by ensuring the safety of content for front-end display.

Some validation examples are:

  • Maximum number of characters for a title in a schema.
  • The maximum number of slides allowed in a carousel.
  • A schema must have at least one image.
  • A field must be in a URL format.

Validation rules can be applied individually or as combinations to ensure that the content is consistent for the end consumer.

Besides constraining the data that can be entered into content fields, validation can also serve to provide the user with feedback in the form of textual hints like this:

The result in this case would look like this:

Validation constructs adhere to JSON-Schema validation: http://json-schema.org/latest/json-schema-validation.html, and more information is available in the reference section Content Authoring - Schema Validation.

 Read more about the "Consuming Content" concept...

Content Authoring Concepts - Consuming Content

The whole point of a headless CMS is to serve up content to front-end applications, web sites, and other clients in a presentation-independent way. The implication therefore, is that there must be a way (or ways) for client applications to retrieve content from the Amplience CMS. In this context, we provide:

  • An Application Programming Interface (API)
  • A Software Development Kit (SDK)
  • A content previewing capability based on the concept of "cards".

The API

In simple terms, the Content Delivery API is accessed by formulating a URL of the form shown below, where the highlighted characters are the unique asset ID of the content to be retrieved.

The result takes the form of a JSON-LD graph (shown below) that must be flattened for rendering by the front-end application.

The SDK

The SDK provides an inlineContent() method that can be used to "inline" the JSON-LD response data retrieved via the API. Some sample code to output the inlined response data to the web browser log window would look like this:

// Use the SDK to inline the content from the graphs.
 var inlineResult = amp.inlineContent(data);

// This is the new content
console.log("This is the result inlined:");
console.log(JSON.stringify(inlineResult));
console.log("---");

if(inlineResult && inlineResult.length === 1){
// Now log out the text from the inline content
console.log("The text is here:");
console.log(inlineResult[0].text);
console.log("---");

The Content Cards

Our own Content Authoring app uses the concept of "cards" to provide sample representations published and not-yet-published content in the Content Library. While not representative of how content will or should be displayed by front-end applications, we do make these cards available to other systems that may wish to provide preview representations of content. For example, you may wish to incorporate out content previews into you existing CMS business tooling.

Each content type schema defines the card that should be used to preview its content, plus the mapping between the schema fields and the card fields:

As shown schematically here, a card template HTML page (in this case for the "gallery" card) can be used to display the content retrieved from the CMS Administration API:

Note that unlike the Delivery API that provides unauthenticated access to published content, the Admin API that returns unpublished content to be previewed in cards is authenticated. It is beyond the scope of this section to detail this second API and its authentication.

The end result is a card that provides a rendering of the content. Here is a selection of built-in cards that render content in different ways:

Further Reading

More information about consuming content can be found in Content Authoring - Delivery API and SDK and Content Authoring - Development Demonstrations.

 

 Read more about the "Updating Content Types" concept...

Content Authoring Concepts - Updating Content Types

There will be occasions during a project lifecycle where content types will need to be updated. These could be simple alterations such as a new icon or some better hints in the UI for the business user, but can also be more intrinsic changes to the data model. Below are some example use cases and impacts.

Overall risk

Updating a content type is like updating the structure and attributes in a database table. Minor changes can have no impact but certain changes can lead to data (content) loss without appropriate backups and migration.

Overall Recommendations

The points below may seem fairly generic and applicable to all implementations, but they are also valuable for Amplience content authoring.

1: Specify first

Creating content types can be extremely easy in Amplience so there is often an urge to skip the specification stage. This can be great, but it is easier to deal with change if there is a specification so that impacts and dependencies can be known up front. This will also speed up content type development time as the stories and expectations will be better known and suitable to test.

2: Test early - Fail fast - better results.

At the start of a project, always populate content with low value, throw away dummy content. This allows all parties to approve the content type structures and the end result / display of the content. Changes can be made with minimal risk.

3: Phase content production

Following dummy content, produce a few real examples of content use for stakeholder approval. Generally, this will require fewer content type changes but will provide better testing for front end renders.

4: Validate where necessary

Validation is a great feature to ensure that content created can fit in bounds of the rendering templates on the front end application. They assists with the NFR's for development too. It is not always necessary to validate all fields as certain content (such as paragraph text) can flow depending on the size of the article.

5: Backup

Always create a backup before making any changes to content types.

6: Versions

If in doubt, it is best to take a copy of your existing content type and create a new version with the changes. For example "My Content Type" could remain as is, and new content could be created with a content type called "My Content Type V2"

Scenarios:

Changing content type meta data.

The content type meta data contains information such as:

  • Name
  • Description
  • Icon
  • Card
  • Visualisation(s)

These are all internal Amplience attributes and can be changed at any time without affecting the content itself.

Changing a property name

A content type is made up of a series of properties. These properties are effectively the fields in the database where the content is stored.

This is also the name of the property in the CMS API and is how front end code knows what to render.

Changing a property name will result in:

  • Previously populated content for the modified field being removed from all instances of that content type
  • Published content will continue to use the old name until re-published ( either by itself or as a dependency for another publish ).
  • User will need to re-visit the content instance and add the attribute for that field again and re-publish.

Changing a property label

Changing any of the property label attributes will affect the front end form which the business users see when creating content, but will not change the structure of the published content.

Adding a new property

Adding a new property to your content type will not affect any existing content. Please note that any front end code will need to be updated in order to show your new property.

Removing a property

The property will no longer be visible to the content editor but existing published content will continue to serve the old field until re-published (either by itself or as a dependency for another publish).

Changing a property type

This carries the largest risk. Changing data types can lead to corruption of data and corruption of the form itself. Generally instead of changing a data type it would be recommended to add a new field with a new data type.

Changing Validation on a property

Changing the validation on a property will not remove the existing content if it is invalid, it will still remain. In fact even if you re-edit the content, the legacy content will remain and be classed as valid UNLESS you edit the property itself. If you edit the property itself, the latest content must adhere to the validation otherwise the content will not save.

 

  • No labels