8. Advanced Customization & API

Created by Danny Wong, Modified on Sun, 9 Aug, 2020 at 4:28 PM by Danny Wong

USING THE TRANSITION BUILDER

LayerSlider WP supports various types of slide transitions. The Transition Builder offers you an easy-to-use visual editor to create custom transitions for your own needs. Transitions created with the editor will automatically appear in the list of available transitions when you're editing a slider.

Tips & tricks

We can recommend the same tips as we mentioned in the Slider Builder section:

Hover over an option field with your mouse cursor to reveal more information.
Watch the preview. The best way to learn is to instantly see how each option affect the transition you're building. Just play with the settings and observe the differences to understand their role.
We have sample transitions, too! They should be already added to the Transition Builder when you first visit the page. You can see the settings we've used to build these samples. You can also import any of the 200+ pre-defined 2D/3D transitions we're using in the plugin.

Building 3D transitions

3D transitions are made up with 3 animation steps to create more complex transitions with multiple actions. The "animation" step is required, but the "before animation" and "after animation" steps are optional. You can use them to do some preparation before the animation starts or restore back some settings after it is finished.

To help you better understand what are these steps, here is a simple example:

Before the animation starts, you may want to scale down columns
Then rotate them to left
Finally, you want them to scale up back

If you want a really simple transition, you don't have to use all the steps. In this case, please make sure to untick the "Enabled" checkboxes for the corresponding steps.

ABOUT LAYERSLIDER WP SKIN EDITOR

The LayerSlider WP skin editor offers you a graphical way on your WP admin area to modify LayerSlider skins without the need to work with files on FTP. The Skin Editor automatically detects additional content, so you can customize skins from other sources as well.

Editing a skin requires some basic CSS knowledge, please do not attempt to modify a skin if you aren't familiar with CSS. Malformed or invalid CSS code can break your slider appearance.

Please note, updating the plugin (including auto-updates) will override the plugin folder along with your modifications. Consider using the CSS Editor or back-up your modifications before updating.

ABOUT LAYERSLIDER WP CSS EDITOR

With this editor, you can enter custom CSS code, which will be included on pages containing LayerSlider sliders. This gives you a chance for much more complex customizations that the Slider Builder interface cannot provide. Your CSS code will also be included in the Slider Builder, thus the Preview mode should pick them up and show the appropriate result on-the-fly.

Using CSS requires some web development experience. Please do not attempt to use this editor if you're not familiar with CSS. Malformed or invalid CSS code can break the appearance of sliders or your site.

ABOUT LAYERSLIDER API

LayerSlider is built on standard web technologies like HTML, CSS, and Javascript, and offers a way to extend the capabilities of the plugin through the LayerSlider API. Please note, this requires programming skills and web development experience, thus we cannot recommend it to users without the necessary knowledge.

LayerSlider 6 introduced a whole new API model with new events and methods. To view the API documentation for older releases, please navigate to the Legacy API section. The legacy API cannot be used in LayerSlider 6, it is documented only to provide you a way of porting (if needed).

Event reference

Event callbacks is a way to receive notifications and run custom code when certain actions occur in sliders. The following events can be used under the Event Callbacks tab of the Slider Builder.

INIT EVENTS	DESCRIPTION
sliderWillLoad	Fires as soon as a LayerSlider instance has been created, but before processing any user data or rendering the UI. This gives you a chance to perform any task before LayerSlider tries to parse the markup and user settings. Since this event occurs in mid-initialization, you must bind this event on the target element before calling .layerSlider().
sliderDidLoad	Fires when a LayerSlider instance is fully initialized and its UI elements become accessible for DOM manipulation. You should bind this event on the target element before calling .layerSlider() to avoid timing issues.
RESIZE EVENTS	DESCRIPTION
sliderWillResize	Fires before resizing and rendering sliders due to a viewport/orientation etc. change. Keep in mind that running slow code in this event can lead to performance issues, as it is called subsequently in multiple times.
sliderDidResize	Fires after sliders have been resized and rendered due to a viewport/orientation etc. change. Keep in mind that running slow code in this event can lead to performance issues, as it is called subsequently in multiple times.
SLIDESHOW EVENTS	DESCRIPTION
slideshowStateDidChange	A changed slideshow state can occur for various reasons, such as starting media playback, hovering over the slider, manually pausing the slideshow, etc. This event fires at any state change. Since there are multiple states, it's not guaranteed that there is an actual change in playing/pausing the slideshow. Slideshow states can be retrieved from the Event Data object passed to the callback handler.
slideshowDidResume	This event fires when the slideshow resumes from a paused state. Please note that slide timers and layer transitions are not bound to the slideshow directly. Depending on the `pauseLayers` option, the slide's animation timeline can continue its progress towards the end of the slide and wait for slide change until the slideshow resumes from its paused state. You can examine the passed Event Data object to identify which settings is applied.
slideshowDidPause	Fires when the slideshow pauses from a playing state. As mentioned in the previous event, the `pauseLayers` option decides which (if any) animations can continue playing in the background. The slideshow paused state only guarantees the prevention of changing slides. You can examine the passed Event Data object to identify which settings is applied.
SLIDE CHANGE EVENTS	DESCRIPTION
slideChangeWillStart	This event signals whenever the slider wants to change slides, and is your last chance to divert or intervene in any way. The proposed slide indexes and other relevant information is in the passed Event Data object. Return false to prevent slide change, or return an integer to switch to that slide instead of the proposed one.
slideChangeDidStart	This is the last notification before the slider commences a slide change. At this point you can no longer divert or intervene, its only purpose is letting you know the next slide index and other relevant data in advance.
slideChangeWillComplete	Fires before completing the slide change. Since at this point the slide change is still in progress, the current slide's index is still pointing to the previous slide. Please note, layers animation may occur earlier in execution depending on the `timeShift` option. See the Slide Timeline Events section if you're looking for an event like that.
slideChangeDidComplete	Fires after a slide change has completed and the slide indexes have been updated. Please note, layers animation may occur earlier in execution depending on the `timeShift` option. See the Slide Timeline Events section if you're looking for an event like that.
SLIDE TIMELINE EVENTS	DESCRIPTION
slideTimelineDidCreate	Fires when the current slide's animation timeline (e.g layer transitions on the slide) has been created. This event lets you know when the GSAP timeline object becomes accessible for interfacing.
slideTimelineDidUpdate	Fires rapidly (at each frame) throughout the entire slide while the animation timeline (e.g. your layers on the slide) is playing. This includes reverse playback as well.
slideTimelineDidStart	Fires when the current slide's animation timeline (e.g. your layers) has started. This event signals the exact time in execution when the first (earlier) layer becomes visible and transitions are taking place.
slideTimelineDidComplete	Fires when the current slide's animation timeline has completed (e.g. layer transitions) and the slider is ready to change slides. However, changing slides is not yet guaranteed at this point, as it depends on slideshow states and other factors. This event only concerns transitions occurring on the slide, thus it is possible to divert the slider or intervene in any way before changing slides. The proposed slide indexes and other relevant information is in the passed Event Data object. You can return `false` to prevent a potential slide change.
slideTimelineDidReverseComplete	Fires when all animations on a reversed slide have reached their starting point and the slide is ready to be played from the beginning.
MEDIA EVENTS	DESCRIPTION
mediaDidStart	A media element on the current slide has started playback. Toggling play / pause do not affect this event.
mediaDidStop	A media element on the current slide has stopped playback. Toggling play / pause do not affect this event.
POPUP EVENTS	DESCRIPTION
popupWillOpen	Fires when the Popup starts its opening transition and becomes visible.
popupDidOpen	Fires when the Popup completed its opening transition.
popupWillClose	Fires when the Popup stars its closing transition.
popupDidClose	Fires when the Popup completed its closing transition and became hidden.
DESTROY EVENTS	DESCRIPTION
sliderDidDestroy	Due to technical reasons, destroying a slider may not happen instantaneously. This event lets you know when the slider destructor has finished and it is safe to remove the slider from DOM after calling the `destroy` API method.
sliderDidRemove	This event is fired as the last step when destroying a slider and the second parameter `true` was passed in the `destroy` API method indicating to remove the slider.

Event Data object

Most event handler functions will have the same 2 pre-defined variables passed. Those are the jQuery Event object and our custom slider data object. You can name these variables by your choice, but we will refer to them as event and slider in our examples.

Every slider data object will contain the same properties, regardless of the used event. However, it's possible that some values are not yet set depending on the current point of execution. The data object contains the most relevant information, but we've also included the entire LayerSlider instance data source, which you can use to access or modify properties on the fly, as well as to add new methods to implement new features.

We encourage everyone to use the browser developer tools and examine the returned data by using console.log() to see potentially undocumented data. Here is an example that you can paste into your browser's JavaScript console. Please make sure to use the right selector when targeting the slider container element on which the LayerSlider instance was created.

1 2	`var` `data = jQuery('#slider').layerSlider('eventData');` `console.log( data );`

Please note, the slider. prefix in every property name refers to the passed variable to callback functions, which can be named differently.

SLIDER PROPERTIES	TYPE	VALUE
slider.data	Object	The complete data source object of the current LayerSlider instance. Since this is a reference, you can access and modify any part of the object. You can event add new methods to implement new features this way.
slider.userData	Object	The parsed (e.g. defaults included) slider options which have been set by the user in the init code.
slider.target	DOMNode	The slider container element, on which LayerSlider was initialized.
slider.state	Object	The slider states object, which indicates whether the slider is preloading images, changing or animating slides etc.
slider.isBusy	Boolean	Returns a boolean value indicating whether the slider is busy to complete background tasks (see `slider.state`).
slider.api()	Function	The shortcut to execute API commands. Example: slider.api('next');
EVENT PROPERTIES	TYPE	VALUE
slider.event.target	DOMNode	The affected element from which the event originates. For example, in case of a media event, it might be an HTML <video> element. In most cases it defaults to the slider container.
FIRST (STARTING) SLIDE PROPERTIES	TYPE	VALUE
slider.slides.first.index	Integer	The index of the first (starting) slide. The count starts from 1 instead of zero.
slider.slides.first.data	Object	Contains slide-related settings as well as custom slide properties set in the Slider Builder or through the `data-ls` attribute.
slider.slides.first.deeplink	String	Deeplink of the first (starting) slide (if any).
PREVIOUS SLIDE PROPERTIES	TYPE	VALUE
slider.slides.prev.index	Integer	The index of the previous slide. The count starts from 1 instead of zero. Please note, this value is updated after the `slideChangeDidComplete` event.
slider.slides.prev.data	Object	Contains slide-related settings of the previous slide as well as custom slide properties set in the Slider Builder or through the `data-ls` attribute.
slider.slides.prev.deeplink	String	Deeplink of the previous slide (if any).
CURRENT SLIDE PROPERTIES	TYPE	VALUE
slider.slides.current.index	Integer	The index of the current slide. The count starts from 1 instead of zero. Please note, this value is updated after the `slideChangeDidComplete` event.
slider.slides.current.data	Object	Contains slide-related settings of the current slide as well as custom slide properties set in the Slider Builder or through the `data-ls` attribute.
slider.slides.current.deeplink	String	Deeplink of the current slide (if any).
slider.slides.current.layersIn	jQery Collection	A jQuery collection of DOM nodes, which contains layers appearing on the current slide, including static layers.
slider.slides.current.layersOut	jQuery Collection	A jQuery collection of DOM nodes, which contains layers leaving on the current slide. This includes static layers, since they aren't bound to their origin slide.
slider.slides.current.timeline	GSAP TimelineMax	The current slide's animation timeline, which you use to easily manipulate animations. Slow them down, repeat them, reverse them. You can do GreenSock functions to easily achieve surprising effects.
NEXT SLIDE PROPERTIES	TYPE	VALUE
slider.slides.next.index	Integer	The index of the proposed next slide. The count starts from 1 instead of zero. The next slide can change at any time by a user action or API commands.
slider.slides.next.data	Object	Contains slide-related settings of the proposed next slide as well as custom slide properties set in the Slider Builder or through the `data-ls` attribute.
slider.slides.next.deeplink	String	Deeplink of the next slide (if any).
slider.slides.next.layersIn	jQuery Collection	The same as `slider.slides.current.layersIn` for the proposed next slide. The next slide can change at any time by user action or via API commands.
slider.slides.next.layersOut	jQuery Collection	The same as `slider.slides.current.layersOut` for the proposed next slide. The next slide can change at any time by user action or via API commands.
MISCELLANEOUS SLIDE PROPERTIES	TYPE	VALUE
slider.slides.count	Integer	The number of slides in a slider.
slider.slideChangeTimeline	GSAP TimelineMax	The slide transition animation timeline, which is used when changing slides. You can use GreenSock functions to easily manipulate the transition.
SLIDESHOW PROPERTIES	TYPE	VALUE
slider.slideshow.state	Object	An object of slideshow states, which determines whether the slider is paused or not. There are several states such as media playback, hovering over the slider, manually pausing the slideshow, etc.
slider.slideshow.sequence	Array	An array containing slide indexes, which indicates the pre-determined order of slides. This takes into account of random slideshows, and provides a reliable value without user action.
slider.slideshow.direction	String	'prev' or 'next' indicating whether the slideshow is playing forwards of backward depending on the `twoWaySlideshow` option.
slider.slideshow.isPaused	Boolean	Boolean indicating if the slideshow is paused at the time of execution. Depending on the `pauseLayers` setting, the slide animation timeline may still continue its progress towards the end of the slide. This means that layer transitions and progress timers may not be interrupted, but the slider will not commence to the next slide until resuming the slideshow.
CYCLES PROPERTIES	TYPE	VALUE
slider.cycles.max	Integer	The number of cycles that the user set.
slider.cycles.current	Integer	The number of cycles that the slider has performed at the time of execution.

API methods

The below API methods can be used to control sliders externally, modify their behavior, or wire them up with 3rd party solutions. By using the right combinations of API events and commands, you can implement new features or extended the capabilities of the plugin with custom code. Please note, API events are exposed to the API commands in the same way as anything else. Be aware that most API methods will trigger the appropriate API events as well.

METHOD NAME	DESCRIPTION	EXAMPLE
(integer)	Initiate a slide change to the specified slide number. The count starts from 1. The example on the right side shows how to switch to the third slide.	$('#slider').layerSlider(3);
nextSlide or next	Skips to the next slide in the sequence.	$('#slider').layerSlider('next');
previousSlide or prev	Changes to the previous slide.	$('#slider').layerSlider('prev');
replaySlide or replay	Restarts the slide, replays all layer transitions from the beginning.	$('#slider').layerSlider('replay');
reverseSlide or reverse	Play the slide and all transitions backwards, then pause at the beginning of the slide. Pass `true` as a second parameter to continue replaying the slider normally afterward.	$('#slider').layerSlider('reverse', true);
resetSlide	Immediately sets the current slide back to its starting state and pauses it.	$('#slider').layerSlider('resetSlide');
stopSlideshow or stop	Stops the slideshow. Depending on the `pauseLayers` setting, the slide animation timeline may still continue its progress towards the end of slide. This means that layer transitions and progress timers may not be interrupted, but the slider will not commence to the next slide until resuming the slideshow.	$('#slider').layerSlider('stop');
startSlideshow or start	Resumes the slideshow and re-enables the slider to change slides when reaching the end of animation timeline. Since transitions may occur even in a paused state depending on the `pauseLayers` setting, it possible that the timeline has already reached its end point when calling this command.	$('#slider').layerSlider('start');
pauseSlider or pause	Stops the slider by freezing every animation taking place at the time of execution, including slide transitions when changing slides.	$('#slider').layerSlider('pause');
resumeSlider or resume	Resumes the slider and continues playing frozen animations.	$('#slider').layerSlider('resume');
toggleSlider or toggle	Toggles between `pauseSlider` and `resumeSlider` by respecting the current state.	$('#slider').layerSlider('toggle');
playMedia	Start playback of any visible media element on the current slide.	$('#slider').layerSlider('playMedia');
pauseMedia	Pause playback of any visible media element on the current slide.	$('#slider').layerSlider('pauseMedia');
unmuteMedia	Unmutes playback of any visible media element on the current slide. Using this event may require user interaction (i.e. click, tap, etc on page) due to browser restrictions.	$('#slider').layerSlider('unmuteMedia');
openPopup	Opens initialized Popups waiting in the background to be launched.	$('#slider').layerSlider('openPopup');
closePopup	Closes the Popup.	$('#slider').layerSlider('closePopup');
data	Returns the entire data object that the slider uses.	var data = $('#slider').layerSlider('data');
eventData	Returns the Event Data object filled with the relevant values at the time of execution.	var data = $('#slider').layerSlider('eventData');
userInitOptions	Returns the slider options provided by the user in the init code.	var data = $('#slider').layerSlider('userInitOptions');
defaultInitOptions	Returns the full list of the default slider options.	var data = $('#slider').layerSlider('defaultInitOptions');
sliderInitOptions	Returns the parsed slider options (extended by user data) used to initialize the slider.	var data = $('#slider').layerSlider('sliderInitOptions');
originalMarkup	Returns the original HTML markup that the slider was initialized on.	var data = $('#slider').layerSlider('originalMarkup');
redrawSlider or redraw	Recalculates the slider styles and repaints the slider. Useful when you want to manually trigger responsive calculations to update the slider UI.	$('#slider').layerSlider('redraw');
destroy or kill	Destroys the LayerSlider instance by canceling timers, removing events, freeing up allocated memory. Passing a second parameter `true` will also remove the slider element from the DOM. Due to technical reasons, destroying a slider may not happen instantaneously. See the `sliderDidDestroy` and `sliderDidRemove` events for more information.	$('#slider').layerSlider('destroy', true);

Examples

Switch slides with custom controls:
1
<a href="javascript:void(0);" onclick="$('#slider').layerSlider(2);">Change to slide 2</a>
Combining callbacks and API methods:
The following example will bring up an alert message after every slide change with the current slide number. It can be used with the slideChangeDidComplete event callback.
1
2
3
function(event, slider) {
alert('The current slide is: ' + slider.slides.current.index);
}
Using API Events from external code:
LayerSlider relies and makes use of jQuery's event handling capabilities. This means that all jQuery-related event handling features and functions can be used, such as .on(), .off(), live and delegated events, attaching multiple events with namespaces, etc. You need to bind these events to the slider container element.
1
2
3
jQuery('#layerslider').on('sliderDidLoad', function( event, slider) {
console.log( event, slider );
});

LEGACY API - OBSOLETE, DO NOT USE

This version of the API was used in LayerSlider 5 and earlier versions. It is no longer supported, DO NOT use it for current/future project. We're keeping this in the documentation in order to provide you a way of porting to the new API if needed.

Event reference

EVENT	DESCRIPTION
cbInit	Fires when LayerSlider has loaded.
cbStart	Calling when the slideshow has started.
cbStop	Calling when the slideshow is stopped by the user.
cbPause	Firing when the slideshow is temporary on hold (e.g.: "Pause on hover" feature).
cbAnimStart	Calling when the slider commencing a slide change (animation start).
cbAnimStop	Firing when the slider finished a slide change (animation end).
cbPrev	Calling when the slider will change to the previous slide by the user.
cbNext	Calling when the slider will change to the next slide by the user.

Slider data

PROPERTY	VALUE
data['prevLayerIndex']	Returns the index of the previous slide
data['curLayer']	Returns the jQuery object of the current slide
data['curLayerIndex']	Returns the index of the current slide
data['nextLayer']	Returns the jQuery object of the next slide
data['nextLayerIndex']	Returns the index of the next slide
data['layersNum']	Returns the number of slides in the slider
data['isAnimating']	Returns true if the slider is animating at the time of execution

To list all properties in the data object just paste this code snippet into a callback function and check your browser's Javascript console:

1

2

3

for(key in data) {
    console.log(key + ' = ' + data[key]);
}

API methods

METHOD	DESCRIPTION	EXAMPLE
(integer)	The slider will change to the specified slide. It starts with 1.	$('#slider').layerSlider(3);
next	The slider will change the next slide.	$('#slider').layerSlider('next');
prev	The slider will change the previous slide.	$('#slider').layerSlider('prev');
stop	Will stop the slideshow.	$('#slider').layerSlider('stop');
start	Will continue or start the slideshow.	$('#slider').layerSlider('start');
data	Returns the slider data object	var data = $('#slider').layerSlider('data');
userInitData	Returns the object of the slider options which has been set by the user in the init code	var data = $('#slider').layerSlider('userInitData');
defaultInitData	Returns the full list of the default slider options	var data = $('#slider').layerSlider('defaultInitData');