Developing your own cards
The custom card web app is specified as a templated URI, including parameters such as the VSE domain and content ID, that are filled in by the platform at runtime and sent to the card as query parameters.
The way a card app is organised is very similar to a visualization and for more details about retrieving and rendering content see the visualizations page. On this page we'll walk you through setting up a custom card for a content type and include some examples.
On this page
Setting up the custom card URI
To set up a content type to use a custom card you add its URI to the card field as shown in the example below.
Here's the templated URI for the tutorial banner example:
The URI the specifies the visualization web app URL and includes the following templated parameters:
- "api": the VSE domain
- "content": the unique content ID used to retrieve this piece of content from the CMS
Retrieving and rendering content
The basic structure of a card app is as follows:
- The VSE domain and content ID are used to construct a URL to send to the Content Delivery API to retrieve the content in JSON-LD format
- The JSON-LD content is converted into a content tree
- The JSON content tree is then combined with a template (such as handlebars) to create the HTML to render the content on the card
- There are some important prerequisites
For more details about how to extract the parameters from the templated URI sent to the web app and render the content, take a look at the developing a visualization page.
Example card: tutorial banner
The tutorial banner custom card app is very similar to the visualization, but with some important differences:
- only the background image is rendered. The text and call to action button are not included
- to optimise performance, Dynamic Media parameters are used to reduce the image quality and adjust the width so that the image load faster. The parameters added to the image URL are: ?w=341&qlt=25
Download the tutorial banner content card app.
Example card: carousel
The carousel content card needs to render content representing one or more carousel slides. This could be displayed as a grid of images, but in this example we're making use of the code from the visualization that automatically cycles through the slides. This is an example of a card that doesn't just show static content.
Download the carousel content card preview.
- 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 card preview to be displayed