Dynamic Content Accelerators

This repository is intended as an accelerated starting point for implementing Amplience Dynamic Content. It contains the front-end render templates required to display the most commonly used content types.

Table of Contents

• Configuring the basepath
• Installation
• Demo
• Render Dependencies
• Content Packages
• Setting up the Transformation Templates
• Setting up the Content Types
• Locations for Icons, Cards and Visualisations
• Generated Builds
• Dependencies
  • Helper scripts
  • 3rd-party libs
• Building minified and concatenated files
• Development
• Bug / Feature Request
• Contacts

Configuring the Basepath

Before building the project, the basepath for the content types needs to be defined. This will be the location where the content types are stored. To configure this, open up the .replace.json file and change the content type basepath to the root URL where you are storing the content types.

In the file there is also a visualization basepath. This will be the location where you place the content in your dist folder after the project has been built. The visualization files are using this basepath to reference the correct css and javascript files in the project. The company tag can remain as "any", or be specified to a certain company store tag.

If you can't view the .replace.json file, you need to activate the feature to view hidden files in your operating system. Information on how to show hidden files for Windows, Mac and Unix this is found below:

Windows

There are a few options to show hidden files on Windows, but one of the easier ones is to do it from the control panel.

1. Right-click the "Start" button, then select "Control Panel".
2. Go to "Appearance and Personalization", then select "File Explorer Options".
3. Click the "View" tab.
4. Scroll down a bit and change the "Hidden files and folders" setting to "Show hidden files, folders and drives".

This was tested on Windows 10.

Mac

For macOS releases since Sierra, there is a shortcut for showing hidden files. To use this simply open the finder window and press CMD + SHIFT + . If you press the command again it will hide the hidden files.

If using macOS older than Sierra, there is another way to show hidden files:

1. Open the Terminal found in Finder > Applications > Utilities.
2. In the Terminal, paste the following defaults write com.apple.finder AppleShowAllFiles YES and press enter.
3. Hold the "Option/alt" key, then right click on the finder icon in the dock and click "Relaunch"

Unix

For Unix-based systems, go to the directory where you want to view hidden files and press ctrl + h

Installation

Note that the installation requires Node version 6.14.3 or higher.

# Install dependencies 
$ npm install
$ npm install --global gulp-cli

# Build project
$ gulp

Open a page with desired render, e.g. localhost:9100/dist/renders/image/index.html

Demo

Here you can find the Dynamic Content Inventory, where all the accelerator modules are shown:

Dynamic Content Inventory

We have also created a demo page using these modules, with some added styling and functionalities. It can be found here:

Demo page

Render Depencencies

This diagram shows all the content types needed for the renders included in a homepage. The arrows indicate the dependencies of the different content types.

This diagram shows all the content types needed for the renders included in a blog. The arrows indicate the dependencies of the different content types.

Content Packages

Commonly used content type templates have been split up into separate packages. Individual packages can be found in dist/renders, here you can edit any render templates or styling prior to running a build. Note that the actual content types are stored in a different repository, which can be found here:

https://github.com/amplience/dc-accelerators-content-types

When the project is built using gulp, the content types will be pulled from Github and placed in dist/contentTypes. The IDs of these content types will be the same as the basepath configured in .replace.json. For example, the image.json content type will have the ID YOUR_BASEPATH_URL + /image.json

Setting up the Transformation Templates

Before setting up transformation templates, you need to add an empty image to the account. This image will act as a background for the layers in the transformation templates, before they are populated with images. The empty image empty.png can be found in the root repository.

To display image content correctly with roundels, the handlebars template makes use of a transformation template. This needs to be set up within your Amplience account before the renders will work properly.

• Log in to Amplience OnDemand and open up the "tools" menu.
• Select the "Transformation Templates" option in the menu.
• Click the "new" button in the top right of the screen.
• Set both the "Friendly Name" and "Template Name" to be "roundel".
• In the "Additional Parameters" box, enter these parameters:

myasset=empty&p1_img=empty&p2_img=empty&p3_img=empty&p4_img=empty&p5_img=empty&qlt=90&roundelRatio=1&layer0=[src=/i//{$prod_img}&w=1350]‌‌&layer1=[src=/i//{$p1_img}&w={376*$roundelRatio}&right=10&bottom=10&anchor=BR&visible={$p1_img!=$myasset}]‌‌&layer2=[src=/i//{$p2_img}&w={376*$roundelRatio}&left=10&bottom=10&anchor=BL&visible={$p2_img!=$myasset}]‌‌&layer3=[src=/i//{$p3_img}&w={376*$roundelRatio}&left=10&top=10&anchor=TL&visible={$p3_img!=$myasset}]‌‌&layer4=[src=/i//{$p4_img}&w={376*$roundelRatio}&right=10&top=10&anchor=TR&visible={$p4_img!=$myasset}]‌‌&layer5=[src=/i//{$p5_img}&w={376*$roundelRatio}&right={$root.layer0.info.canvas.width/2-376*$roundelRatio/2}&top={$root.layer0.info.canvas.height/2-376*$roundelRatio/2}&anchor=TR&visible={$p5_img!=$myasset}]

• Click "Create".
• Go back to your newly created transformation template in the menu, click on the cogwheel icon and select "Publish".

To add a point of interest transformation template, follow the same instructions with "Friendly Name" and "Template Name" set to "poi", and with these parameters in the "Additional Parameters" box:

scaleFit=poi&poi={$this.metadata.pointOfInterest.x},{$this.metadata.pointOfInterest.y},{$this.metadata.pointOfInterest.w},{$this.metadata.pointOfInterest.h}

To add a roundel transformation template for the banner accelerator, follow the same instructions with "Friendly Name" and "Template Name" set to "banner-roundel", and with these parameters in the "Additional Parameters" box:

myasset=empty&p1_img=empty&p2_img=empty&p3_img=empty&p4_img=empty&p5_img=empty&qlt=90&roundelRatio1=1&roundelRatio2=1&roundelRatio3=1&roundelRatio4=1&roundelRatio5=1&layer1=[src=/i//{$p1_img}&w={$root.layer0.info.canvas.width*$roundelRatio1}&left={$root.layer0.info.canvas.width-10}&bottom=10&anchor=BR&visible={$p1_img!=$myasset}]‌‌&layer2=[src=/i//{$p2_img}&w={$root.layer0.info.canvas.width*$roundelRatio2}&left=10&bottom=10&anchor=BL&visible={$p2_img!=$myasset}]‌‌&layer3=[src=/i//{$p3_img}&w={$root.layer0.info.canvas.width*$roundelRatio3}&left=10&top=10&anchor=TL&visible={$p3_img!=$myasset}]‌‌&layer4=[src=/i//{$p4_img}&w={$root.layer0.info.canvas.width*$roundelRatio4}&left={$root.layer0.info.canvas.width-10}&top=10&anchor=TR&visible={$p4_img!=$myasset}]‌&layer5=[src=/i//{$p5_img}&w={$root.layer0.info.canvas.width*$roundelRatio5}&right={$root.layer0.info.canvas.width/2-$root.layer0.info.canvas.width*$roundelRatio5/2}&top={$root.layer0.info.canvas.height/2-$root.layer0.info.canvas.width*$roundelRatio5/2}&anchor=TR&visible={$p5_img!=$myasset}]

To add a point of interest transformation template for the banner accelerator, follow the same instructions with "Friendly Name" and "Template Name" set to "banner-poi", and with these parameters in the "Additional Parameters" box:

layer0=[scaleFit=poi&poi={$this.metadata.pointOfInterest.x},{$this.metadata.pointOfInterest.y},{$this.metadata.pointOfInterest.w},{$this.metadata.pointOfInterest.h}&sm=c&aspect=1:1&w=768&h=768]

Setting up the Content Types

When the content types have been placed at the same basepath URL as you built the project with (see section "configuring the basebath"), you can start the process of registering the content types in Dynamic Content:

• Log in to the Amplience Dynamic Content platform and navigate to the development tab.

• Click on the button "Register content type".

• Add the content type URL and the content type label. It's important that the URL is the same as the URL where the content type is hosted. Using the image content type as an example again, the URL for it would be YOUR_BASEPATH_URL + /image.json. You can also add icons, cards, visualisations and associated repositories if needed.

• Add a content type icon. You can either choose one from Amplience or enter the URL where your own icon is located. The URLs for the icons can be found below.

• Add a content type card. You can either choose one from Amplience or enter the URL where your own card is located. The values for the cards can be found below.

• Choose associated repositories for the content types. The content type needs to be associated with a repository for you to be able to create content there. Content types should not be associated with slot repositories.

• Add a visualisation. The visualisation files for each specific render can be found in their respective render folders in dist/renders, located inside the package folder. For example, the image visualisation file is located in dist/renders/image/package. The render folders need to be hosted at your basepath location as well. When that has been done you need to add the URL for the visualisation.html file followed by the parameters "vse" and "content", i.e.

  ?vse={{vse.domain}}&content={{content.sys.id}}

  For example, if the basepath for the visualisation is

  YOUR_BASEPATH/dist/renders/image/package/visualisation.html

  then the URL for the visualisation would be

  YOUR_BASEPATH/dist/renders/image/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

  You also need to add a label for the visualisation.

• Click save.

• Repeat this process for all the content types needed for your render.

• Navigate to the production tab and select "Create content".

• Select the content type you wish to use for your content, fill out the content form and click save.

• Enter the name of the content and which folder to save it in and click save.

• Navigate back to the production tab. You can now view the content GUID. By clicking on the icon in the top right corner of the content you can, among other things, view the content or select the content ID.

Locations for Icons, Cards and Visualisations

Roundel

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-imagewithroundel.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /roundelPosition
  • image0: /roundel

Link

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-link.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the text card. The pointer you need to add for the card is:

  • headline: /label

Image

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-image.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the photo card. The pointers you need to add for the card are:

  • image: /image
  • imageAlt: /imageAltText

• Visualisation

  The visualisation file is located in dist/renders/image/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/image/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Text

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-text.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the text card. The pointer you need to add for the card is:

  • headline: /text

• Visualisation

  The visualisation file is located in dist/renders/text/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/text/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Video

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-video.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /_title
  • image0: /video

• Visualisation

  The visualisation file is located in dist/renders/video/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/video/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Card

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-card.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /cardName
  • image0: /cardImage/image

• Visualisation

  The visualisation file is located in dist/renders/card/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/card/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Card list

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-cardlist.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /header
  • image0: /cards/0/cardImage/image
  • image1: /cards/1/cardImage/image
  • image2: /cards/2/cardImage/image
  • image3: /cards/3/cardImage/image

• Visualisation

  The visualisation file is located in dist/renders/cardList/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/cardList/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Banner

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-banner.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /header
  • image0: /bannerImage/0/image

• Visualisation

  The visualisation file is located in dist/renders/banner/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/banner/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Slider

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-slider.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. Examples of the pointers you need to add for the card are:

  • headline: /_title
  • image0: /slides/0/bannerImage/0/image
  • image1: /slides/1/bannerImage/0/image
  • image2: /slides/2/bannerImage/0/image - image3: /slides/3/bannerImage/0/image

• Visualisation

  The visualisation file is located in dist/renders/slider/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/slider/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Split block

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-splitblock.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. Examples of pointers you need to add for the card are:

  • headline: /content/0/text
  • image0: /content/0/image
  • image1: /content/1/image
  • image2: /content/0/video
  • image3: /content/1/video

• Visualisation

  The visualisation file is located in dist/renders/splitBlock/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/splitBlock/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Promo

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-promobannersection.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /_title
  • image0: /icon

• Visualisation

  The visualisation file is located in dist/renders/promo/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/promo/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Promo List

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-promobanner.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /_title
  • image0: /bannerSection/0/icon
  • image1: /bannerSection/1/icon
  • image2: /bannerSection/2/icon

• Visualisation

  The visualisation file is located in dist/renders/promoList/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/promoList/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

External block

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-externalblock.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the text card. The pointer you need to add for the card is:

  • headline: /external

• Visualisation

  The visualisation file is located in dist/renders/externalBlock/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/externalBlock/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Snippet

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-blogsnippet.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /title
  • image0: /image/image

Blog Post

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-blogpost.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Card

  Choose the gallery card. The pointers you need to add for the card are:

  • headline: /title
  • image0: /snippet/image/image

• Visualisation

  The visualisation file is located in dist/renders/blogPost/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/blog/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Page

• Icon

  https://dev-solutions.s3.amazonaws.com/DynamicContentTypes/Accelerators/icons/icon-page.png

  The icons can also be found in /dist/icons if you want to host them somewhere yourself.

• Visualisation

  The visualisation file is located in dist/renders/page/package Put the render folder in your basepath that you defined in .replace.json. The url for the visualisation to register the content type with will then be BASEPATH + /renders/page/package/visualisation.html?vse={{vse.domain}}&content={{content.sys.id}}

Slot-accelerators

This content type contains the references to assign all the other content types to slots within the Dynamic Content platform. It is registered the same way as other content types in the development tab in Dynamic Content, but is associated with a slot repository rather than a content repository.

Generated Builds

Built renders are located in dist/renders folder. Here you can find unminified and minified css, handlebars templates and the visualisation html page. The libs folder contains JS dependencies for the render. Most of the files in the libs folder are taken from the dist/reusable folder, described below.

Dependencies

All JS dependencies for renders can be found in the dist/reusable folder. JS dependencies are composed of helper scripts and 3d party libs.

Helper Scripts

Helper scripts can also be found in src/reusable/js folder. Below is the list of scripts and their description:

• utils.js is needed to make AJAX requests to retrieve render data. It also has several methods to troubleshoot the renders.
• hanldebars_helpers.js is used to declare various handlebars helpers, to solve different tasks for handlebars templates.

3rd-party Libs

All 3d-party libs are pulled as npm dependencies and can be found in package.json

• handlebars.min.js is the handlebars templates library.
• cms-javascript-sdk.min.js is used to format the requested JSON content. Example usage:

amp.inlineContent(JSON.parse(data));

• showdown.min.js is used to parse text with markdown and convert it into semantic html.
• lory.min.js is a slider library and is used for slider renders.

Building Minified and Concatenated Files

# Install dependencies 
$ npm install
$ npm install --global gulp-cli

# Build minified project
$ gulp buildAllMin

This will build minified and concatenated files for all renders.

Development

Want to contribute? Great! To fix a bug or enhance an existing module, follow these steps:

• Fork the repository
• Create a new branch on your fork (git checkout -b feature/improve-feature)
• Make the appropriate changes in the files
• Add changes to reflect the changes made
• Commit your changes (git commit -am 'Improve feature')
• Push to the branch (git push origin improve-feature)
• Create a Pull Request to the develop branch

Bug / Feature Request

If you find a bug, kindly contact [email protected] and include your steps to reproduce the bug and the expected result. If you’d like to request a new function, feel free to do so by emailing the same address.

Contacts

If you have any problems, questions or comments please email [email protected] or contact your customer success manager.