Developing visualizations

A visualization lets your users preview an individual piece of content by embedding your app in the content editing interface. Dynamic Content tells your app which content item the user wants to view and your app fetches that content and renders it. The visualization is displayed in an iFrame side by side with the content form.

Visualizations make use of a virtual staging environment (VSE) to allow you to preview content before it's published. The visualization environment will usually be configured for you at the beginning of your project and can be configured from the "Visualization settings" menu in the Dynamic Content app.

On this page we'll explain how to develop a simple visualization and how to specify it when registering or updating a content type. We'll use the example of the tutorial banner and provide a web app that is designed just to preview content created with that content type.

Specifying the visualization for a content type

To add a visualization to a content type, open the "Register content type" window, either when creating a new content type or updating an existing one.

Click the "Visualizations" tab. A list of your visualizations is displayed. To add a new visualization, click the "+" icon.

Add a visualization by clicking the '+' icon
Add a visualization by clicking the '+' icon

Give the visualization a label. This allows the user to choose this visualization if you've added multiple visualizations to a content type.

In the example below we're giving the visualization the label "banner viz", but you can use what ever you like.

The visualization URL

Next enter the templated visualization URL. The URL includes tokens for the id of the content to be visualized and the virtual staging domain. These tokens are evaluated and sent to the visualization as query parameters. You can then use the virtual staging domain and the content id to build up a delivery URL to retrieve the content to be visualized.

When you have finished adding the visualization, if you want to add an additional visualization, click the "+" icon again and fill in the fields.

Enter the visualization label and templated URL
Enter the visualization label and templated URL

Here's the templated URL for the tutorial banner example:

https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/tutorialbannervizl.html
?api={{vse.domain}}&content={{content.sys.id}}

The URI the specifies the visualization web app and includes the following templated parameters:

  • "api": the VSE domain
  • "content": the unique content ID used to retrieve this item from Dynamic Content

Tokens supported by visualizations

The following is a list of the available tokens that you can include in the visualization URL.

  • {{content.sys.id}} The content id of the content being visualized.
  • {{vse.domain}} The visualization staging domain.
  • {{locales}} If you support field level localization and include the locales token in your URL, the user selected locale is sent to your visualization as a parameter. You can then retrieve the localized content.
    See visualizing localized content for a full example.
  • {{snapshot.id}} The id of the snapshot being visualized. This is not usually needed in visualizations. When you view a visualization of a snapshot added to a slot in an edition then the snapshot id is included in the virtual staging domain sent to your visualization so in most cases you don't need to access this directly.

Example 1: Content Delivery 2

The section includes the visualization for the tutorial banner content type written using the Content Delivery 2 API.

Retrieving the content

The virtual staging domain and the content ID is used to construct a URL to send to the Content Delivery 2 API to retrieve the content to be visualized. Using the virtual staging domain to retrieve unpublished content is straightforward, you just need to replace the production content delivery 2 URL with the virtual staging domain and everything else stays the same.

Here's an example of some code to construct the URL. Note that depth=all and format=inlined are specified as query parameters so that the content and all its dependents will be returned in inlined format.


const contentDeliveryUrl = `//${getQueryVar('api')}/content/id/${getQueryVar('content')}?depth=all&format=inlined`;

An example of a complete query URL used to retrieve some content is shown below:

//kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io/content/id/8672257c-8f16-42e7-b8cc-14e0a117ba2d?depth=all&format=inlined

This requests content using the VSE domain kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io with the ID 8672257c-8f16-42e7-b8cc-14e0a117ba2d

This query is then sent in a GET request to the Content Delivery 2 API. Here's the code used in the tutorial banner example:

  var deliveryRequest = $.ajax({url: contentDeliveryUrl});
  // render the content or display error response
  deliveryRequest
    .done(renderContent)
    .fail(showErrorMessage);

Rendering the content

The content is returned from the Content Delivery 2 API in inlined format. In order to render the content in the visualization window you need to do the following:

  • Combine the JSON with a handlebars template to generate the HTML to render the content. We use handlebars in the examples
  • Combine the HTML with CSS to display the content in the visualization window

Example code to perform these steps from the tutorial banner visualization is shown below.


function renderContent(content) {
  // fetch the Handlebars template from the DOM
  const templateSource = $('#tutorial-template').html();
  const template = Handlebars.compile(templateSource);
  // render the content using the template
  const html = template(content);

  $('#contentRender').html(html);
}

The handlebars used to render the tutorial banner is shown below.

<script id="tutorial-template" type="text/x-handlebars-template">
 {{#with content}}
   <div class="banner">
    <div class="banner-editorial">
      <div class="banner-header">{{headline}}</div>
      <div class="banner-subheader">{{strapline}}</div>      
    </div>
        <!-- construct image URL from the data. Chose to default to HTTPS -->

        <img class="banner-background-image" src="https://{{background.defaultHost}}/i/{{background.endpoint}}/{{background.name}}">    
        <a class="banner-call-to-action" href="{{calltoactionurl}}">{{calltoactiontext}}</a>
  </div>  
  {{/with}}    
  </script>

Complete example

You can download the complete tutorial banner visualization for Content Delivery 2, including the code shown on this page and the utility methods that you can use in your own code.

Example 2: Original Content Delivery API

The following sections explain how a typical visualization web app is structured using the example of a visualization for the tutorial banner example. This example uses the original Content Delivery API. Note that the original Content Delivery API returns data in JSON-LD format which you will need to convert to inlined format, so there are a few more steps in this example.

Note that to simplify this example you could use the Content Delivery SDK which will return the JSON content in inlined format without the need for any conversion. The Content Delivery SDK can be used with both Content Delivery 2 and the original Content Delivery API.

Retrieving the content

The virtual staging domain and the content ID is used to construct a URL to send to the Delivery API to retrieve the content to be visualized.

Here's an example of some code to construct the URL:


  const encodedQuery = encodeURIComponent(JSON.stringify({'sys.iri':`http://content.cms.amplience.com/${getQueryVar('content')}`}));
  const contentDeliveryUrl = `//${getQueryVar('api')}/cms/content/query?store=store&query=${encodedQuery}`;

The URL contains the standard Delivery API endpoint and the store from which to retrieve the content. The encodeURIComponent method is a standard utility method that is included with the full visualization example.

An example of a complete query URL used to retrieve some content is shown below:

//1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io/cms/content/query?fullBodyObject=true&query=
%7B%22sys.iri%22%3A%22http%3A%2F%2Fcontent.cms.amplience.com
%2F862e0be0-d085-4ca0-b789-67fe1c65688f%22%7D&scope=tree&store=store

and in decoded form:

//1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io/cms/content/query?fullBodyObject=true&query= {"sys.iri":"http://content.cms.amplience.com /862e0be0-d085-4ca0-b789-67fe1c65688f"}&scope=tree&store=store

This requests content using the VSE domain 1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io with the ID 862e0be0-d085-4ca0-b789-67fe1c65688f

This query is then sent in a GET request to the Content Delivery API. Here's the code used in the tutorial banner example:

  var deliveryRequest = $.ajax({url: contentDeliveryUrl});
  // render the content or display error response
  deliveryRequest
    .done(renderContent)
    .fail(showErrorMessage);

Rendering the content

The content is returned from the Content Delivery API in JSON-LD format. In order to render the content in the visualization window you need to do the following:

  • Convert the JSON-LD content into a content tree using the "inline" method of the CMS SDK
  • Combine the JSON with a handlebars template to generate the HTML to render the content. You can use whichever templating technology you chooose, but we use handlebars in the examples
  • Combine the HTML with CSS to display the content in the visualization window

Example code to perform these steps from the tutorial banner visualization is shown below.


function renderContent(data) {
  // use the Amplience CMS JavaScript SDK to manipulate the JSON-LD into a content tree
  const contentTree = amp.inlineContent(data)[0];
  // fetch the Handlebars template from the DOM
  const templateSource = $('#tutorial-template').html();
  const template = Handlebars.compile(templateSource);
  // render the content using the template
  const html = template(contentTree);

  $('#contentRender').html(html);
}

The handlebars used in the tutorial banner is shown below:

    <script id="tutorial-template" type="text/x-handlebars-template">
       <div class="banner">
        <div class="banner-editorial">
          <div class="banner-header">{{headline}}</div>
          <div class="banner-subheader">{{strapline}}</div>      
        </div>
              <img class="banner-background-image" src="https://{{background.defaultHost}}/i/{{background.endpoint}}/{{background.name}}">    
            <a class="banner-call-to-action" href="{{calltoactionurl}}">{{calltoactiontext}}</a>
      </div>      
      </script>
    <script>

Complete example

You can download the complete tutorial banner visualization, including the code shown on this page and the utility methods that you can use in your own code.

Using the visualization

The example below shows the tutorial banner content being previewed in the content editing window. See the Using visualizations page for more details on how users make use of visualizations to preview a content item.

The tutorial banner visualization
The tutorial banner visualization

Prerequisites

  • You must have a virtual staging environment specified in your settings in order to show visualizations for any content.
  • The current user's IP address must be in the whitelist of approved IP addresses in order for the visualization to be displayed

Content Delivery 2

Content Delivery API

Blog Post: Preview native apps with Dynamic Content & Appetize.io

results matching ""

    No results matching ""