Events and Event Callbacks
Code in the Project Editor or your own script can run when a project loads, changes slides, plays a video, or opens as a popup. It receives the project’s state and can stop or redirect a slide change.
On this page
LayerSlider’s events are jQuery events of the project’s element, the container that holds the project on the page. You can handle them in 2 places: as Event Callbacks, written in the Project Editor, or with jQuery’s .on() in a script of your own.
Events
The table lists the events in the order of the Event Callbacks window.
| Event | When it fires |
|---|---|
sliderWillLoad |
When the project’s script starts, before any other event and before LayerSlider reads the project’s settings and builds the project |
sliderDidLoad |
When the project has been built, before its first slide starts playing |
sliderWillResize |
Before LayerSlider sizes the project: while the project loads, each time the browser window is resized, and when the project’s container changes its width |
sliderDidResize |
After LayerSlider has sized the project, at the same moments |
slideshowStateDidChange |
At every change of the slideshow’s state, also at each slide change, not only when the slideshow pauses or resumes |
slideshowDidPause |
When the slideshow goes from playing to paused, also when a project waits to be scrolled into view |
slideshowDidResume |
When the slideshow goes from paused to playing, also when the project starts its slideshow |
slideChangeWillStart |
When a slide change is about to begin, before anything moves |
slideChangeDidStart |
When the slide transition has begun |
slideChangeWillComplete |
Shortly before the change completes, while slides.current is still the slide that is leaving |
slideChangeDidComplete |
After the change has completed: slides.current is the new slide, and slides.prev the one before |
slideTimelineDidCreate |
When the layer timeline of the slide about to play has been built, for the first slide too |
slideTimelineDidUpdate |
On every frame while the slide’s layer timeline plays, also while it plays backward |
slideTimelineDidStart |
When the slide’s layer timeline starts playing: for the first slide, and again after every slide change |
slideTimelineDidComplete |
When the slide’s layer timeline reaches the end of the slide, right before the slideshow moves on |
slideTimelineDidReverseComplete |
When the slide’s layer timeline, played backward by the reverse command, reaches the start of the slide |
mediaDidStart |
When a video layer starts playing for the first time. Resuming the video after a pause doesn’t fire this event again |
mediaDidStop |
When a video layer that has started ends, or when a slide change stops it. A pause doesn’t fire this event |
mediaPlayStateDidChange |
When a video layer starts, pauses, resumes, or ends, and when a slide change stops it |
mediaMuteStateDidChange |
When the project’s sound is muted or unmuted |
popupWillOpen |
When a popup starts to open |
popupDidOpen |
When the popup’s opening transition has ended |
popupWillClose |
When the popup starts to close |
popupDidClose |
When the popup’s closing transition has ended and the popup is hidden |
sliderDidDestroy |
When the destroy command has finished |
sliderDidRemove |
After destroy with true, right after sliderDidDestroy, as the project leaves the page |
These events don’t pass the event data to a handler:
sliderWillLoad,sliderDidDestroy, andsliderDidRemovepass only the jQuery event.slideTimelineDidCreatepasses an object with 3 keys.slideTimelineis the slide’s layer timeline,layersOnSlideTimelinea jQuery set of the slide’s layers and its background, andslideTimelineDurationthe slide’s duration as a number of seconds.slideTimelineDidUpdatepasses the slide’s layer timeline itself.
Stopping or redirecting a slide change
Two events use what a handler returns. From slideChangeWillStart, return false to cancel the slide change. To change to another slide instead, return its number, and the slideshow goes on from that slide.
From slideTimelineDidComplete, return false to keep the slideshow on the slide.
After a false, the slideshow doesn’t try again by itself. To move on, send the project the next command, and the slideshow goes on from the next slide.
The event data
A handler receives the jQuery event, whose target is the project’s element, and, for most events, the event data, an object that describes the project at that moment. this is the project’s element too.
These are the keys of the event data that a handler uses most:
| Key | What it is |
|---|---|
slides.current |
The slide shown, with index, deeplink, layersIn, layersOut, and timeline |
slides.prev |
The slide shown before, with index and deeplink |
slides.next |
The slideshow’s next slide, with index, deeplink, layersIn, and layersOut. During slideChangeWillStart of a change sent from code, such as layerSlider( 3 ), it’s still the slide that would have come next |
slides.count |
The number of slides |
index |
A slide’s number, counted from 1, as in slides.current.index |
deeplink |
The value of a slide’s Deep Link field, or null when it’s empty |
layersIn, layersOut |
jQuery sets of a slide’s layers that come in and that go out |
timeline |
In slides.current, the slide’s layer timeline: a TimelineMax of LayerSlider’s own copy of GSAP 2, not of a gsap that your page loads |
slideshow.state |
The slideshow’s state: the flags running and paused, and changed, a counter that goes up at each slide change |
isBusy |
true while the project preloads images or changes slides. A slide change asked for during that time is ignored |
event.target |
In mediaDidStart, mediaDidStop, and mediaPlayStateDidChange, the video layer’s video element, and in the other events the project’s element. In a handler written as function( event, slider ), this key is slider.event.target, and event.target is the project’s element |
userData |
The settings the project runs with: its own, merged with LayerSlider’s defaults |
api() |
A function that sends a command to this project only, such as api( 'next' ) |
Event Callbacks in the Project Editor
In the Project Editor, go to Project Settings › Event Callbacks. In the Event Callbacks window, write your code in the event’s box.
In a box’s first line, such as function( event, slider ) {, event is the jQuery event and slider the event data, or what the event passes instead.
The callbacks are saved with the project and reach your site when you click Publish. Save keeps them in the draft, which only the editor shows. The callbacks also run in the editor’s previews.
If a callback isn’t valid JavaScript, the Event Callbacks window marks its event with a warning, but Publish puts it on the page all the same. On the page, the browser then reports a SyntaxError, and the project doesn’t start.
Listening from your own script
Find the project by its ID, as [id^="layerslider_12_"], and bind your handlers with jQuery’s .on(), as the examples do. The article on the JavaScript API shows where to find the ID, and how to select a project by its slug instead.
If the page shows the project more than once, the handler runs for each copy, and this is the copy that the event is about.
To receive sliderWillLoad and sliderDidLoad too, bind before the project starts, for example in a jQuery ready handler. Print your script after jQuery: from wp_footer at priority 99, it comes after jQuery wherever WordPress puts jQuery. A listener for the window’s load event comes too late for a project that starts with the page.
If a handler doesn’t run
A handler runs when it’s bound on the project’s element itself, with the event’s name as the table gives it. These handlers don’t run:
- A handler whose event name has only a namespace of your own, such as
'sliderDidLoad.mytheme' - A handler delegated from
documentwith a selector for the project - A handler bound on a parent element of the project
Bind on the project itself instead, as the examples do. To give a handler a namespace of your own, add layerSlider to it, as in 'sliderDidLoad.layerSlider.mytheme': the handler runs, and .off( '.mytheme' ) removes it.
If a handler throws an error, the project goes on, and the browser’s console shows the error after a line with the event’s name, such as LayerSlider: Error while calling event "slideChangeDidComplete":.
If your code was written for LayerSlider 8, see which changes in LayerSlider 9 affect it.
Examples
Each example goes in a script printed from wp_footer at priority 99. Change 12 to your project’s ID, and 15 to your popup’s.
The first example adds the class summer-sale-ready to the page’s body when the project has loaded.
jQuery( function() {
const $project = jQuery( '[id^="layerslider_12_"]' );
$project.on( 'sliderDidLoad', function() {
jQuery( 'body' ).addClass( 'summer-sale-ready' );
} );
} );The second example writes the number of the slide shown into the data-summer-slide attribute of body each time a slide starts, the first slide included.
jQuery( function() {
const $project = jQuery( '[id^="layerslider_12_"]' );
$project.on( 'slideTimelineDidStart', function( event, slider ) {
jQuery( 'body' ).attr( 'data-summer-slide', slider.slides.current.index );
} );
} );The third example keeps the slideshow on the project’s last slide.
jQuery( function() {
const $project = jQuery( '[id^="layerslider_12_"]' );
$project.on( 'slideTimelineDidComplete', function( event, slider ) {
if ( slider.slides.current.index === slider.slides.count ) {
return false;
}
} );
} );The fourth example stops the project’s slideshow while a popup is open, and starts it again when the popup has closed.
jQuery( function() {
const $project = jQuery( '[id^="layerslider_12_"]' );
const $popup = jQuery( '[id^="layerslider_15_"]' );
$popup.on( 'popupWillOpen', function() {
$project.layerSlider( 'stop' );
} );
$popup.on( 'popupDidClose', function() {
$project.layerSlider( 'start' );
} );
} );Events on the first slide
For the first slide of a project that’s in view when the page loads, no slide change event fires. Those events start with the project’s first change of slides. To run code on every slide, the first included, use slideTimelineDidStart, as the second example does.
A project outside the view when the page loads waits until it’s scrolled into view, because the Start Only in Viewport switch in Project Settings › Slideshow is on by default. When the project comes into view, it gets a slideChangeDidComplete for its first slide, without a slideChangeWillStart or slideChangeDidStart before it.
A project far down the page
A project far below the first screen doesn’t load with the page. Its sliderWillLoad fires as the page loads, but its sliderDidLoad can come well after the page’s load event, even if nobody scrolls. LayerSlider starts the projects closest to the viewport first, and a project far down the page waits, even when it’s the only project on the page.
To have such a project load with the page, go to Project Settings › Performance, choose Highest in the Load Priority list, and publish the project. The project’s slideshow still waits until the project is scrolled into view.