Building the Amplience blog (pt.2): Visualization & preview

  • Product updates
  • Engineering
How we utilised Dynamic Content's Visualization and Preview features when creating the Amplience Product Blog.
9 mins reading time
Ben Pearey | September 30, 2019

In the previous blog post Building the Amplience blog - Part 1  we covered how we implemented a NextJS blog site using Dynamic Content to drive the data. This blog takes what we did previously and demonstrates how we integrate some additional cool Dynamic Content features.

Visualizing blog content with Dynamic Content

Visualization is a great tool built into Dynamic Content which provides on-demand, side-by-side views of content as it is edited.

Creating a Visualization entry point

To get this working in the blog we needed to provide an entry point (via a URI) that would accept a Virtual Staging Environment (VSE) domain and a content item ID. In next.config.js we defined a new export path with the expected page and query string params keys:

Now any request made to /visualization.html will forward vse and content to the visualization NextJS page.

Handling Visualization requests

To handle Visualization requests in the blog app we created a VisualizationPage.

This component is a NextJS page that acts like a top-level controller. It has a primary role of capturing the VSE domain and content ID from the request’s query string. Once these details have been retrieved, it can render the default layout (without a header and footer if you set contentOnly to false) and the Visualization component.

Processing Visualization requests

Now that we have the information we need to generate a Visualization, we can start to render output via the Visualization component. One of the main observations regarding this component is that it is built as a standard React component. This allows us to utilise React’s lifecycle hooks, so we can make client-side requests to the Content Delivery API and get the latest unpublished content.

The component was built to render Visualizations for the following content types:

  • blog-post.json

  • text.json

  • image.json

  • video.json

Whenever the component mounts or updates (componentDidMount or componentDidUpdate) it will attempt to get the latest unpublished content for the supplied content ID.

First we call the Content Delivery API, passing the VSE domain and content ID. We then check to see if the content returned is content (text, image, video) or a blogPost. Once we've established what content we have the component state is set accordingly. With the state set we can render the contents respective component via the React.Component render function.

Here we check the state to see if either content or blogPost have been defined and render appropriately.

Integrating the blog's visualization into Dynamic Content

Adding the blog’s visualization to a Dynamic Content content type is a straightforward task. Simply:

  1. Login into Dynamic Content

  2. Navigate to: Development > Content Types

  3. Open the desired content type (blog-post, image, text or video)

  4. Click 'Add a visualisation'

  5. Add your visualization to the 'Visualization URI' e.g. https://<your-domain>/visualization.html?vse={{vse.domain}}&content={{content.sys.id}}

  6. Save your changes

Now when you are editing content using that content type you should be able to see your visualization in action.
For more information on configuring a Visualization checkout our docs: 

Visualizations Amplience Documentation Hub.

Previewing the blog site using Dynamic Content

Preview is similar to visualizations and is another great tool that helps content authors view content before it is published. While visualizations are great for viewing new unpublished content types, Preview takes it one step further and allows you to look at a snapshot of your entire blog at a given time in the future.

There are two areas to keep in mind when implementing Preview in the blog: Preview for existing routes (updating existing pages or blog posts) and Preview for new routes (new blog posts that are yet to be published)

Previewing existing routes

Previewing existing routes is a fairly straightforward task (this mainly applies to the landing page and already published blog pages). To get the Preview content we can simply update the getInitialProps function on the NextJS page to allow us to pass a staging environment to the Content Delivery Service.

Here we check to see if a VSE domain has been passed via the props (from the query string). If we have a VSE domain then we pass this on to the service that makes the Content Delivery Service request as the stagingEnvironment. This is used in the Content Delivery Service SDK config and override the default production base URL.

Previewing new routes

When we create a new blog post there is no corresponding export path in our blog, so using the method above would result in a 404 not found error. To allow us to Preview new, unpublished blog pages we need to do things a little differently. Firstly, we define a new export path specifically for Preview content in next.config.js:

Once we have the export path setup we need a page to support it. For this we created a PreviewPage NextJS page component.

In a similar way to the Visualization page, we check for the necessary query string values of a VSE domain and content ID. As the PreviewPage is a preview of the entire app we need to display the full layout, so we do not set the contentOnly flag on the layout component. We then render the Visualization component inside the layout. The Visualization component already does everything that we need to get staging content and render a blog post so we can simply re-use that component for Preview.

Maintaining query string values while navigating

When navigating in Preview mode we need to maintain the query string as we click between pages. To do this we need to capture the current query string and construct the anchor tag href to contain the VSE domain.

Here we use the NextJS useRouter function to grab the current route information, including the query string. From this we can determine whether we are in preview mode (query.vse is present) and build up the path and query string as needed.

Integrating the blog's Preview into Dynamic Content

Adding the blog's Preview to Dynamic Content is simple and can be achieved with the following steps:

  1. Login to Dynamic Content

  2. Navigate to Setting (cog icon) > Preview

  3. Click the blue plus icon to create a new Preview

  4. Give it a name of your choosing and this for the application URL: https://<your-domain>/?vse={{vse.domain}}

When you click the Preview button, the preview is launched, showing what how the blog site will appear on the chosen date.
For further details on Preview see our docs: 

Previewing content · Amplience Documentation Hub.

What we learned

Being tasked with creating the Amplience Product blog has been a great learning experience for us. It has given us an opportunity to work really closely with JAMStack and discover how it best integrates with Dynamic Content products. Here are some of the things we learned when building the blog site.

Managing dynamic routing and client-side requests

A key feature of NextJS is how it takes a hybrid approach to data loading. In static mode NextJS does the following by default:

  1. On load, present a purely static render of the page (generate at build time)

  2. Re-render the page by executing the pages getInitialProps - depending on how the page is loaded

This allows NextJS to provide lightning fast initial load times but also keeps the pages reactive. This behavior was mostly a benefit, but not in certain scenarios. One area that had us scratching our heads for a while was why it was making client-side requests to our services to get content. Our content would not be changing between builds of the blog so we would be wasting requests getting content we already had.

It turns out using the <Link /> NextJS components to link between pages utilises the next router which in turn, triggers a call to getInitialProps for the linked page (when loaded). There was a lot of digging through the next code base and soul searching to work out what was going on. But in the end the solution was simple: we noticed that loading the pages directly didn't trigger getInitialProps and then we had the lightbulb moment. If we switched out the NextJS link components for standard anchor tags we no longer got the unwanted calls of getInitialProps. To make things a little more reusable we created a <StaticLink /> component so we could easily change the behaviour of our standard anchor tags.

Get the code

Head over to our GitHub repo to find the complete source code for the blog site, including the preview and visualization functionality that we showed you how to implement in this blog post.