Skip to content

Lucit Template Play and Stop Content Hooks Guide

Overview

Play and stop content hooks let a Lucit template run custom JavaScript at specific points in the Render App playback lifecycle. Use these hooks to prepare state, coordinate custom media or timers, report playback events, and clean up when playback stops.

Hooks are additive. Registering a hook does not replace or override the Render App's standard animation, video, messaging, play, or stop behavior.

Add lifecycle hook registrations in the template's JS tab in the Code Editor at Templates → {Template} → Canvas → Action Bar → <> → JS.

API Reference

Register play and stop hooks

registerPlayContentHook(name, fn, phase);
registerStopPlayContentHook(name, fn, phase);

Both functions accept the same parameters:

Parameter Type Description
name string A unique, descriptive name for the hook registration.
fn function The callback to execute at the selected lifecycle phase.
phase string One of before, start, or after.

The stop hook API is named registerStopPlayContentHook, while the function that initiates the stop lifecycle is named stopPlayContent.

Lifecycle Phases and Execution Order

The meaning of a phase depends on whether it is registered for play or stop.

Phase Play hook timing Stop hook timing
before Before existing animations and videos are stopped and playback begins. Before existing animations and videos are stopped.
start After animations and videos start. After animations and videos stop.
after After the Render App sends the Content Played message. After the Render App sends the Content Stopped message.

When playContent() runs, the sequence is:

  1. Run before play hooks.
  2. Stop existing animations and videos.
  3. Start animations and videos.
  4. Run start play hooks.
  5. Send the Content Played message.
  6. Run after play hooks.

When stopPlayContent() runs, the sequence is:

  1. Run before stop hooks.
  2. Stop existing animations and videos.
  3. Run start stop hooks.
  4. Send the Content Stopped message.
  5. Run after stop hooks.

The after play phase means that playback has been initiated and the played message has been sent. It does not mean that all animations or videos have finished. The after stop phase runs after the standard stop path and stopped message complete.

Registering Play Hooks

Use registerPlayContentHook for behavior associated with playback beginning.

registerPlayContentHook("resetCustomScene", function () {
  document.querySelectorAll(".custom-active").forEach(function (element) {
    element.classList.remove("custom-active");
  });
}, "before");

registerPlayContentHook("startCustomTimer", function () {
  window.customPlaybackStartedAt = Date.now();
}, "start");

registerPlayContentHook("reportPlayback", function () {
  console.log("Content playback was initiated");
}, "after");

Typical uses by phase:

  • before: reset custom animation state, clear overlays, or prepare custom media trackers.
  • start: start an external timer or synchronize custom UI with animations and videos.
  • after: report that playback was initiated or react after the played message was sent.

Registering Stop Hooks

Use registerStopPlayContentHook for behavior associated with playback stopping.

registerStopPlayContentHook("pauseCustomTimer", function () {
  window.customPlaybackStartedAt = null;
}, "before");

registerStopPlayContentHook("disableLiveUpdates", function () {
  document.body.classList.remove("live-updates-enabled");
}, "start");

registerStopPlayContentHook("resetCustomScene", function () {
  document.querySelectorAll(".custom-active").forEach(function (element) {
    element.classList.remove("custom-active");
  });
}, "after");

Typical uses by phase:

  • before: pause custom timers or capture state before animations and videos stop.
  • start: disable live updates or clean up temporary DOM state after media stops.
  • after: reset UI or synchronize external state after the stopped message was sent.

Complete Paired Example

Register separate play and stop hooks when a custom behavior must be started and cleaned up with content playback:

registerPlayContentHook("startClock", function () {
  if (window.customClockIntervalId) {
    clearInterval(window.customClockIntervalId);
  }

  window.customClockIntervalId = setInterval(function () {
    const clock = document.querySelector("[data-custom-clock]");
    if (clock) {
      clock.textContent = new Date().toLocaleTimeString();
    }
  }, 1000);
}, "start");

registerStopPlayContentHook("stopClock", function () {
  if (window.customClockIntervalId) {
    clearInterval(window.customClockIntervalId);
    window.customClockIntervalId = null;
  }
}, "before");

This example also guards against repeated play calls creating multiple intervals.

Authoring Guidelines

  • Give each registration a unique, descriptive name so logs and debugging remain clear.
  • Use only the supported before, start, and after phase values.
  • Keep callbacks short and focused on side effects. Move complex behavior into a named helper when needed.
  • Make callbacks safe to run across repeated play and stop cycles. Clear intervals, listeners, and temporary DOM state that the template creates.
  • Use play and stop hooks as a pair when a play hook allocates a resource that must be released.
  • Do not override window.playContent() or window.stopPlayContent() to add custom behavior. Register hooks instead so standard Render App behavior remains intact.
  • A hook error is caught and logged by the Render App and does not stop the standard playback lifecycle. Test callbacks independently because a logged error can still leave custom template state incomplete.