Cinema8 Widget API: runtime 1
The earlier way of writing widgets, with c8PlayerApi and the page’s jQueryThis page describes runtime 1, the earlier Widget API. Widgets and question templates written this way keep working unchanged, and you can still edit them. New widgets are written with Widget API v2: each widget is drawn in its own sealed box, cleans up after itself and reads typed properties. To move a widget over, see Coming from runtime 1.
Widgets are reusable components that run inside the Cinema8 player. A runtime 1 widget is three parts (HTML with Handlebars, CSS, JavaScript) that run in the player’s page.
See also: Widget Playground (runtime 1)
Widget Basics
- Widgets are embedded on the video timeline.
- They support dynamic properties, actions, and runtime control.
- You can configure widgets via Creative Studio.
Common Widget Properties
All widgets inherit:
namestart,endvisibleonStart,onEnd,onClickposition(percentage-based)
You can also define your own custom props (e.g., text, color, video).
Supported Property Types
- Text (string)
- Text Area (multiline string)
- Color (hex string)
- Image (URL)
- Video (URL)
- Boolean
- Text List (array)
- Image List (array)
- Select (dropdown)
- Action (clickable)
Accessing Parameters
HTML
Use Handlebars templates:
<p>{{text}}</p>Lists:
<ul>
{{#each textList}}
<li>{{this}}</li>
{{/each}}
</ul>JavaScript
c8PlayerApi.getWidgetProps()
c8PlayerApi.getWidgetProp('textArea')Unique IDs:
$('.c-{{uid}} .widget-button').click(() => {
console.log(c8PlayerApi.getWidgetProp('text'))
})CSS
.c-{{uid}} {
background: {{color}};
padding: 1rem;
}Using {{uid}}
Ensures unique styling and DOM selection:
- HTML:
<div class="c-{{uid}}"> - CSS:
.c-{{uid}} {} - JS:
$('.c-{{uid}}')
Accessing Runtime Data
c8PlayerApi.getTrackProps()
c8PlayerApi.getTrackProp('duration')Authenticated user:
const user = c8PlayerApi.getAuthenticatedUser()Video Control APIs
c8PlayerApi.play()
c8PlayerApi.pause()
c8PlayerApi.currentTime()
c8PlayerApi.volume(0.5)
c8PlayerApi.subtitle("en")
c8PlayerApi.audioTrack(1)
c8PlayerApi.qualityLevel("auto")Variable Storage
c8PlayerApi.setVariable('score', 10)
c8PlayerApi.getVariable('score')Persistent variables:
c8PlayerApi.setVariable('userChoice', 'A', true)Saving Data
c8PlayerApi.postData({ feedback: 'Great!' }).then(console.log)Retrieve data:
c8PlayerApi.getData().then(console.log)Runtime Events
c8PlayerApi.on("play", () => { ... })
c8PlayerApi.on("pause", () => { ... })
c8PlayerApi.on("visibilityChange", visible => { ... })
c8PlayerApi.on("variableChange", (key, prev, next) => { ... })Executing Actions
c8PlayerApi.executeWidgetPropActions('onImageHover')Using Clickable Props
Enable “isClickable” in Studio and bind:
<li data-onclick-ref="textList">Item</li>Handlebars Helpers
<#Handlebars>
Handlebars.registerHelper("uppercase", val => val.toUpperCase())
</#Handlebars>Then in HTML:
{{uppercase text}}Need help? Visit the Widget Playground (runtime 1) for examples, or write new widgets with Widget API v2.