Set up an HTML5 Template for Broadsign Publish

This page describes how an admin can set up a Broadsign Publish message template.

Note: To take advantage of the templates functionality in Broadsign Publish, you need at least version 12.1 of Broadsign Control Player. For more information, see Broadsign Control Player in the Broadsign Control documentation.

Overview

A template is simple web page, an HTML package you can provide to your local users so that they can customize it while still making sure that the content fits on any screen and respects your branding guidelines.

You can download an example of template file.

In this document you will find the following sections:

HTML Package Structure: You need to provide Broadsign with an HTML package that has a specific file structure.
Configure the Template: Configure the settings that your users will see.
Update the HTML File: Change the appropriate fields in your HTML file.
Update the params.json file: Populate the parameters of your params.json file (see also params.json Reference).
Set up the Template for New Image Choice : Modify a template so that the end user can choose between the default image or upload/pick a new one from its library.
Set up the Template for Image Choice from a List: Modify a template so that the end user can select between a set number of images in a drop-down field.
Set up the Template for New Audio Choice : Modify a template so that the end user can choose between the default audio file or upload/pick a new one from its library.
Set up the Template for Audio Choice from a List: Modify a template so that the end user can select between a set number of audio files in a drop-down field.

Note: In the HTML package, files other than the HTML and JSON files (e.g., CSS, fonts, etc.) are the sole responsibility of the developer.

Note: To ensure that any animation in your templates starts during playback, and not during pre-buffering, Broadsign Publish automatically adds the "BroadSignPlay()" feature. For more information, see BroadSignPlay().

HTML Package Structure

The following illustrates a suggested way to organize the assets in your HTML5 package.

Note: The index.html and params.json files are mandatory and must sit at the root of the package.

Copy

package
     |
     + - index.html
     + - params.json
     + - extra html1
     + - extra html2
     + - assets
     |        |
     |        + - css
     |        |        |
     |        |        + - css1
     |        |        + - css2
     |        + - fonts
     |        |        + - font1
     |        + - js
     |        |        |
     |        |        + - js_1_
     |
     + - images
     |         |
               + - image1
               _              + - _image2

Configure the Template

To configure the template, you will need to edit the .html file (see Update the HTML File) and .json file (see Update the params.json file).

Update the HTML File

The elements that you want to configure in the HTML file must have the data-publish-id span tag. For example:

Copy

<p><span data-publish-id="subtitle-1"></span></p>

The following is a sample HTML document with the tags included:

Copy

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
		<meta name="description" content="">
		<meta name="author" content="">
		<link href="https://fonts.googleapis.com/css?family=Oswald:200,300,400,500,600,700" rel="stylesheet">
		<title></title>
		<style>[...]</style>
	</head>
	<body>
		<div class="wrapper">
			<div id="container" class="clear">
				<section class="clear">
					<figure>
						<figcaption>
							<p><span data-publish-id="subtitle-1"></span></p>
							<h2><span data-publish-id="title"></span></h2>
							<p><span data-publish-id="subtitle-2"></span></p>
							<footer class="more"><span data-publish-id="footer"></span></footer>
						</figcaption>
					</figure>
				</section>
			</div>
		</div>
	</body>
</html>

Update the params.json file

In the params.json file, adjust the parameters of the various HTML elements.

You can download a example of params.json file.

Warning: The fields in your params.json file must correspond to the fields in your HTML file.

You can:

Set the orientation (i.e., portrait or landscape).
Name the field.
Add the default text that will appear in each field (e.g., “Book an appointment now!”).
Set the “mandatory” parameter to “true” (if required) or “false” (if optional).
Set the maximum or minimum length possible in each field (e.g., 50 characters).
Set the choice of images that the user will have.
Set whether your users can choose the offered image or pick a new image.
Set whether your users can choose the offered audio file or pick a new audio file.
Set a predefined template duration, in seconds, in a message.

Note: You can add responsive code to your HTML5 package to adjust orientation based on device.

For more details about the fields and their descriptions, see params.json Reference.

The following is a sample params.json file that corresponds to our HTML file:

Copy

{	
	"orientation": "landscape",	
	"duration":10,	
	"fields": [
		{
			"id": "subtitle-1",
			"label": "Subtitle",
			"mandatory": false,
			"maxLength": 50		
		},
		{
			"id": "title",
			"default": "Book a free consultation with one of your doctors",
			"label": "Title",
			"mandatory": true,
			"maxLength": 50		},
		{
			"id": "subtitle-2",
			"default": "Defy your age without surgery",
			"label": "Subtitle",
			"mandatory": false,
			"maxLength": 50
		},
		{
			"id": "footer",
			"default": "2017 Dermapure. All rights reserved.",
			"label": "Footer",
			"mandatory": false,
			"maxLength": 50
		}
	]
}

params.json Reference

Parameter	Description
allowFreeRatio	Boolean. If “true”, your users can change the aspect ratio of the new image. This changes the behavior of the cropper. If “false”, your users can only use the default aspect ratio. See Set up the Template for New Image Choice for more details.
allowNewAudio	Boolean. If “true”, your users can choose or pick a new audio file. If “false”, your users can only use the default audio file. See Set up the Template for New Audio Choice for more details.
allowNewImage	Boolean. If “true”, your users can choose or pick a new image. If “false”, your users can only use the default image. See Set up the Template for New Image Choice for more details.
aspectRatio	Set the aspect ratio of the image (for example, 16:9). See Set up the Template for New Image Choice for more details.
choices	List of images or audio files from which the end-user can choose when creating a message. These images or audio files must be available on the domain. See Set up the Template for Image Choice from a List or Set up the Template for Audio Choice from a List for more details.
default	The default alphanumeric text string that will appear in the field. Your users are able to update this string, if they want.
duration	Predefined template duration, in seconds, in a message to use, for instance, when the animation design in a template is based on a specific duration. When creating a message with the Message Creation Wizard, the message duration will be read-only and a tool tip explains that the user cannot change the duration. For more information, see Message Creation Tutorial. Note: The Maximum message duration still applies. Fore more information, see Set the Maximum Message Duration.
id	Identifier of the field. It must correspond to the id of the element in your HTML file. For example: Copy `data-publish-id="subtitle-1"`
label	The field label (e.g. “Subtitle”).
mandatory	Boolean. If “true”, your users must enter a value in the field. If “false”, your users can leave the field blank.
maxLength	The maximum length, in characters, permitted in the field.
orientation	Set the orientation (that is, portrait or landscape). Note: This setting applies only to the orientation of the message in Broadsign Publish. It will not modify the orientation of the image on the player.
type	Type of content used in the message. Available types are `audio` and `image`.

Set up the Template for New Image Choice

The image picker allows the end user to choose between the default image or upload/pick a new one from its library.

Note: The end user is only able to choose or pick a new image if the following parameter is present and set to true for the given image field "allowNewImage": true.

The HTML file must have a div class that will contain the image offered to the end user:

Copy

<div class="imageContainer">
	<img data-publish-id="image" class="image" src="./img/image1.jpg" alt="main image" />
</div>

The params.json file must have a corresponding section that allows the end user to choose between the default image or upload/pick a new one from its library:

Copy

{	
	"id": "image",
	"label": "image",
	"default": "./img/image1.jpg",
	"type": "image",
	"allowNewImage": true,
	"allowFreeRatio": false,
	"aspectRatio": "16:19"
}

Set up the Template for Image Choice from a List

Image choice from a list allows the end user to select between a set number of images in a drop-down field. To configure the template, you will need to edit the .html file and the .json file.

The HTML file must have a div class that will contain the choice of images offered to the end user:

Copy

<div class="imageContainer">
	<img data-publish-id="image" class="image" src="./img/image1.jpg" alt="main image" />
</div>

The params.json file must have a corresponding section that contains the choice of images offered to the end user:

Copy

{	
	"id": "image",
	"label": "image",
	"default": "./img/image1.jpg",
	"type": "image",
	"choices": [
		{ "label": "image 1", "value": "./img/image1.jpg" },
		{ "label": "image 2", "value": "./img/image2.jpg" },
		{ "label": "image 3", "value": "./img/image3.jpg" },
		{ "label": "image 4", "value": "./img/image4.jpg" }	
	]
}

Set up the Template for New Audio Choice

The audio picker allows the end user to choose between the default audio file or upload/pick a new one from its library.

Note: The end user is only able to choose or pick a new audio file if the following parameter is present and set to true for the given image field "allowNewAudio": true.

The HTML file must have a div class that will contain the audio file offered to the end user:

Copy

<div class="imageContainer">
	<img data-publish-id="Music" class="audio" src="./img/music1.mp3" alt="main audio file" />
</div>

The params.json file must have a corresponding section that allows the end user to choose between the default audio file or upload/pick a new one from its library:

Copy

{	
	"id": "Music",
	"label": "Choose your audio",
	"default": "./audio/music1.mp3",
	"type": "audio",
	"allowNewAudio": true
}

Set up the Template for Audio Choice from a List

Audio choice from a list allows the end user to select between a set number of audio files in a drop-down field. To configure the template, you will need to edit the .html file and the .json file.

The HTML file must have a div class that will contain the choice of audio files offered to the end user:

Copy

<div class="imageContainer">
	<img data-publish-id="Music" class="audio" src="./audio/music1.mp3" alt="main audio" />
</div>

The params.json file must have a corresponding section that contains the choice of audio files offered to the end user:

Copy

{
	"id": "Music",
	"label": "audio",
	"default": "./audio/music1.mp3",
	"type": "audio",
	"choices": [
		{ "label": "Music 1", "value": "./audio/music1.mp3" },
		{ "label": "Music 2", "value": "./audio/music2.mp3" },
		{ "label": "Music 3", "value": "./audio/music3.mp3" },
		{ "label": "Music 4", "value": "./audio/music4.mp3" }
	]
}