shinyLottie (version 1.0.0)

lottie_addEventListener: Add Event Listener to 'Lottie' Animation

Description

Adds an event listener to a 'Lottie' animation within a 'shiny' application. It is also possible to apply multiple event listeners to a single animation.

Usage

lottie_addEventListener(
  animation,
  event,
  target,
  ...,
  session = shiny::getDefaultReactiveDomain()
)

Value

If used within a reactive context, the function will execute the necessary 'JavaScript'. Otherwise, it will return a script tag containing the 'JavaScript'.

Arguments

animation

A 'Lottie' animation object created by the lottie_animation function or its name.

event

The event to listen for (e.g. "mouseenter", "mouseleave" etc.).

target

The target for the event listener, either "animation" or "container".

...

Additional optional event listener properties, including:

state

A character string corresponding to an animation state (either "play", "pause", or "stop").

loop

Logical value indicating whether the animation should loop.

speed

A numeric specifying the desired animation speed.

direction

Either 1 for forward playback or -1 for reverse playback.

setSubFrame

A logical value specifying whether a 'Lottie' animation should loop (TRUE) or not (FALSE).

playSegments

A numeric vector or list of numeric vectors indicating the segment(s) to be played.

forceFlag

Logical value indicating whether to force the animation to play the specified segments immediately (TRUE) or wait until the current animation completes (FALSE).

custom_js

Custom 'JavaScript' to execute when the event is triggered.

functionName

Optional name for the event handler function (can be useful when referencing the event listener, such as with lottie_removeEventListener).

session

The 'shiny' session object. Defaults to the current reactive domain.

Details

This function has several usage options:

• Supplying an animation object created by the lottie_animation function, and placing the resultant list object in the 'shiny' UI.

• Outside of a reactive context, supplying the name of the animation and placing the resultant script object in the 'shiny' UI.

• Within a reactive context, supplying the name of the animation.

When run within a reactive context, sends a custom session message "lottie_js_runJS" containing the function arguments.

Target Options

• "animation": Attaches the event listener directly to the 'Lottie' animation instance. This is necessary when using a Lottie-specific event (e.g. "onComplete"). See https://airbnb.io/lottie/#/web for further details.

• "container": Attaches the event listener to the container div of the 'Lottie' animation. This should be used when using a generic HTML event, such as "mouseenter" or "mouseleave".

Examples

if (FALSE) { # interactive()
library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  # Create an 'animation' event listener that prints a message to the
  # browser console after each loop
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ) |>
  lottie_addEventListener(
    event = "loopComplete",
    target = "animation",
    custom_js = "console.log('Animation Complete!');"
  ),
  # Create a 'container' event listener that plays an animation when
  # hovering over the button, and another that pauses the animation
  # when hovering stops
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "button",
    width = "200px",
    height = "100px",
    loop = TRUE,
    autoplay = FALSE,
  ) |> lottie_button(inputId = "lottieButton", label = "Lottie",
                     height = "200px", width = "200px") |>
    lottie_addEventListener("mouseenter", "container", state = "play") |>
    lottie_addEventListener("mouseleave", "container", state = "pause")
)

server <- function(input, output, session) {}

shinyApp(ui, server)
}