@amp-nova/dc-accelerators NPM

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.

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.

Right-click the "Start" button, then select "Control Panel".
Go to "Appearance and Personalization", then select "File Explorer Options".
Click the "View" tab.
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:

Open the Terminal found in Finder > Applications > Utilities.
In the Terminal, paste the following defaults write com.apple.finder AppleShowAllFiles YES and press enter.
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 tc@amplience.com 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 tc@amplience.com or contact your customer success manager.

AMP Amplience

cms-javascript-sdk dc-accelerators-content-types handlebars lory.js showdown

@infinitebrahmanuniverse/nolb-_amp @everything-registry/sub-chunk-62 @zalastax/nolb-_amp

1.0.2

3 years ago

Dynamic Content Accelerators

Table of Contents

Configuring the Basepath

Windows

Mac

Unix

Installation

Demo

Render Depencencies

Content Packages

Setting up the Transformation Templates

Setting up the Content Types

Locations for Icons, Cards and Visualisations

Roundel

Icon

Card

Link

Icon

Card

Image

Icon

Card

Visualisation

Text

Icon

Card

Visualisation

Video

Icon

Card

Visualisation

Card

Icon

Card

Visualisation

Card list

Icon

Card

Visualisation

Banner

Icon

Card

Visualisation

Slider

Icon

Card

Visualisation

Split block

Icon

Card

Visualisation

Promo

Icon

Card

Visualisation

Promo List

Icon

Card

Visualisation

External block

Icon

Card

Visualisation

Snippet

Icon

Card

Blog Post

Icon

Card

Visualisation

Page

Icon

Visualisation

Slot-accelerators

Generated Builds

Dependencies

Helper Scripts

3rd-party Libs

Building Minified and Concatenated Files

Development