Visualizations

A visualization is a web app that provides a preview of content of a particular type, displayed in both the content editing window in the production view and the slot editing window in the planning view.

Visualizations make use of a virtual staging environment (VSE) to allow you to preview content before it's published. The visualization 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.

In this section we'll explain how to develop a visualization and how to specify it when registering or updating a content type.

When a content type is registered with a hub, one or more visualizations can be specified. For content types with multiple visualizations, users can choose which one to use to preview the content.

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 "Add a visualization button" and enter the templated visualization URI in the field provided, as shown in the image below. Note that you must provide the complete URI, including all the templated variables. Give the visualization a label.

Adding a visualization
Adding a visualization

If you want to add an additional visualization, click the "Add a visualization" button again and fill in the fields.

The visualization for a content type is specified as a templated URI, including tokens such as the Virtual Staging Environment (VSE) domain and content ID, that are filled in by the platform at runtime and sent to the visualization as query parameters.

Here's the templated URI 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

The following sections explain how a typical visualization web app is structured.

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>

Visualization example

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.

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.

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

results matching ""

    No results matching ""