Licensing

1. Make sure to read the full Licensing Terms.
2. Purchase an In-Stock License for each of your products that include LayerSlider.
3. Register your work (e.g. WordPress theme) to acquire an In-Stock usage permission: kreaturamedia.com/in-stock/

For Envato Market authors

In addition to the licensing terms, you may want to consider the following to comply with Envato's requirements.

Envato has many different assets dealing with licensing and usage terms. You can find these in their entirety on the following URLs: Theme Submission Requirements – Item Promotion Guidelines – Bundled Plugins.

• Explain the difference between bundled and standalone versions

  You should include an easy-to-find disclaimer and a reference to the following help article explaining customers the difference between bundled and standalone plugins: https://help.market.envato.com/hc/en-us/articles/213762463

Bundling in themes

Introduction

This guide mainly focuses on Envato authors bundling LayerSlider in WordPress themes. However, the same principles can be applied to other platforms, as some of the features aren't WordPress specific.

As of 9th September 2013, Envato requires authors to load bundled WordPress plugins in themes with the TGM Plugin Activation class. This helps authors to include 3rd party components easily and handle their dependencies and updates automatically.

Setting up TGM Plugin Activation class

1. Download the latest version of TGM Plugin Activation class using their download generator. Make sure to select the appropriate options. After selecting "Theme" or "Child Theme", you'll likely want to select the "ThemeForest" distribution option.
2. After the download, you should visit their Installation and Configuration pages for more information about using TGMPA.
3. There is also a working example in the downloaded package.
4. Check their FAQ if you have further questions.

Example TGM plugin parameters

Below you can see an example configuration for LayerSlider. You can copy and paste this code, however, make sure to change the source and version properties to the correct values.

// LayerSlider config
array(
	'name' 					=> 'LayerSlider WP',
	'slug' 					=> 'LayerSlider',
	'source' 				=> get_stylesheet_directory() . '/plugins/layerslider.zip',
	'required' 				=> false,
	'version' 				=> '6.0.0',
	'force_activation' 		=> true,
	'force_deactivation' 	=> true,
	'external_url' 			=> 'https://layerslider.com/'
)

Maximizing compatibility

There are a few settings under LayerSlider → Options → Advanced that you might want to change in order to offer a better experience for your customers with your theme. For example, the "Include scripts in the footer" option should be enabled on all sites, but we're still keeping it disabled by default to maximize compatibility with outdated themes that don't support wp_footer().

Another use case is when your theme has a built-in feature to use CDNs, compress or combine JavaScript files, etc. In those cases it might be needed to enforce certain settings to avoid printing scripts mid-page. To keep file sizes minimal, LayerSlider has some additional modules as external files, which are loaded conditionally based on the slider settings. Depending on how you capture and update scripts (if any), you might also want to enable the "Always load all JavaScript files" option to avoid issues with caches and dynamically loaded files.

The below example shows how you can override and enforce certain settings, which are guaranteed to work with your theme. For the full list of potential options, refer to the table below. Make sure to replace Theme Name with the actual name of your theme.

/*
* LS_Config::forceSettings() was added in LayerSlider 6.7.5
* Make sure to include the method_exists() condition,
* otherwise it will cause a fatal error on older versions.
*/

if( method_exists( 'LS_Config', 'forceSettings' ) ) {

	LS_Config::forceSettings( 'Theme Name', array(

		'include_at_footer' 			=> true,
		'conditional_script_loading' 	=> true
	));
}

This is how the above code would look like for your users:

Disabling activation features

Product activation requires a valid license key / purchase code that the majority of your customers will not have. The following function changes LayerSlider interface to hide or change some of the activation related features, banners and messages. It also displays a clearly outlined disclaimer explaining the difference between the theme-bundled and directly purchased versions and emphasizes that activation is optional.

<?php

if( function_exists( 'layerslider_set_as_theme' ) ) {
	layerslider_set_as_theme();
}
?>

Disabling promotions

LayerSlider offers customization services from a 3rd party company: WPKraken. While this is not at a prominent place at all and shouldn't bother users, we understand if you would like to hide it. To do that, please paste the below example code into your theme's functions.php file.

<?php

if( function_exists( 'layerslider_hide_promotions' ) ) {
	layerslider_hide_promotions();
}
?>

Constants & variables

This section lists and describes the constants and global variables of LayerSlider, which can be useful for writing custom code, improving theme integration and making custom solutions built on top of LayerSlider.

List of plugin constants

List of global variables

Working with sliders

We have a new static class that you can use comfortably to work with sliders. Our older functions for this purpose are still available, but we might remove them in future versions, and we highly recommend you to use the new solution.

Class methods

• (int) An integer to find a slider by its database ID,
• (string) A string to find a slider by its slug,
• (array) An array of integers that corresponds to slider IDs
• (array) The filter array to provide a list of sliders based on your filters.

LS_Sliders filter array

Examples

Find a specific single slider by its database ID.

$sliders = LS_Sliders::find( 31 );

Find a specific single slider by its slug.

$sliders = LS_Sliders::find( 'fullwidthdemo' );

Find multiple sliders by their IDs.

$sliders = LS_Sliders::find( array( 12, 15, 23 ) );

Find sliders with custom filters and return results with modifiers.

$sliders = LS_Sliders::find( array(
	'orderby' => 'date_m',
	'limit' => 30,
	'data' => false
) );

Returning slider objects

About Slider Groups

The Slider Groups feature is introduced in v6.9.0. It allows users to have a sort of folders for their sliders. These groups are special entries in the same wp_layerslider table, thus you might want to filter them out or handle them differently than regular sliders.

The LS_Sliders class described above already supports handling groups. There is nothing to do on your part if you're using this class for listing sliders. The default behavior is to disable grouping and exclude group entries from the list. The result is the same as with any previous version of LayerSlider.

However, if you're using custom queries, you need to make sure to exclude group entries by yourself. Since these entries are present in the same table but have slightly different properties, it can cause compatibility issues if you aren't handling them the way it's supposed to. At the very least, you don't want to list these hidden entries for your customers portraying them as regular sliders.

The LS_Sliders class has been updated to cover all these new features and you can also build custom solutions on top of it. Below is the list of API methods that are exposed to you to handle groups yourself. Don't forget, the Working with sliders section above has also been updated and there are additional filters and data points you can rely on.

We also have a new LS_SliderLibrary JavaScript API. It's a shockingly easy way to implement slider pickers with minimal code and it supports all the new features.

Methods

LS_SliderLibrary API

Basic usage

The key concept behind the LS_SliderLibrary API is to offer a pre-made and feature-rich slider picker/selector, so developers can focus on the things that really matter to them.

When called, the LS_SliderLibrary API displays the same modal window that the LayerSlider Gutenberg block uses with features like Slider Groups and others already implemented.

First, you need to enqueue the Slider Library assets by calling the ls_enqueue_slider_library() PHP function. This will load any dependencies needed to use the Slider Library.

<?php ls_enqueue_slider_library(); ?>

Then, you can access the Slider Library via JavaScript with the following code:

LS_SliderLibrary.open({

	onChange: function( sliderData ) {
		// Do stuff here with sliderData
	}
});

The onChange callback will be triggered whenever a slider has been selected by the user. The sliderData parameter contains the id, name, preview image, slide count and other basic information about the selected slider. If you need more information about the selected slider, you can always use the LS_Sliders PHP class to find the slider by its ID.

The Slider Library will automatically close itself after selecting a slider, but you can also call LS_SliderLibrary.close() if needed.

Customization

The modal window displaying the Slider Library uses the Kreatura Modal Window (kmw.js) script. You can pass custom properties to this script via the modalSettings and groupModalSettings properties, so you can change its title, appearance, animation settings, behavior, etc.

modalSettings and groupModalSettings both share the same available settings. The distinction is that when you open a Slider Group, it will create a separate sub-modal window and you can customize that separately as well.

This modal script is custom-made for internal use, thus the public documentation on how to use it is limited. However, you can always use your browser's JS console to list the available options. Just look for the kmw.modal.defaults and kmw.overlay.defaults global variables.

The LS_SliderLibrary.defaults global variable contains the default configuration for these modal windows.

Dos and Don'ts

• Don't change the modal id property.
• Don't target the modal or its elements via CSS directly.
• Do apply a unique class name with modalClasses and use it for CSS customization. You Don't want to accidentally override other modals or different implementations.

Examples

Finally, here's a more lifelike usage example:

LS_SliderLibrary.open({

	// Triggers when the user has selected a slider.
	onChange: function( sliderData ) {
		alert( 'Selected slider ID: ' + sliderData.id );
		alert( 'Selected slider name: ' + sliderData.name );
	},

	// Modal customization
	modalSettings: {
		title: 'Choose LayerSlider',
		modalClasses: 'my-custom-class',
		onBeforeOpen: function() {
			alert('The modal is opening!');
		},
	},

	// Group sub-modal customization
	// Uses the same settings as modalSettings
	groupModalSettings: {

	}
});

Working with sources

{
	"name": "Borderless Dark for 3D sliders",
	"version": "4.6.0",
	"requires": "4.5.5",
	"author": "Kreatura Media",
	"created": "2013-01-15",
	"updated": "2013-07-29",
	"note": ""
}

{
	"name": "Full width demo slider",
	"version": "5.3.0",
	"requires": "5.1.0",
	"author": "Kreatura Media",
	"url": "preview web address",
	"groups": "bundled,free",
	"created": "2013-12-23",
	"updated": "2013-12-23",
	"note": ""
}

Action hooks

Public action hooks reference

Read the WP Codex entry for more information about using actions.

Actions hook examples

The following example uses the layerslider_installed action to add demo content when the plugin was installed for the first time.

<?php

add_action('layerslider_installed', 'my_layerslider_demos');
function my_layerslider_demos() {

	// Method 1: Using importUtil
	include LS_ROOT_PATH.'/classes/class.ls.importutil.php';
	$import = new LS_ImportUtil('<path_to_your_export_file>');

	// Method 2: Using LS_Sliders::add()
	LS_Sliders::add($title, $dataArray);
}

?>

This example uses the layerslider_before_slider_content and layerslider_after_slider_content actions to print out a custom slider wrapper.

<?php

add_action('layerslider_before_slider_content', 'my_ls_before_content');
add_action('layerslider_after_slider_content', 'my_ls_after_content');

function my_ls_before_content() {
	echo '<div class="my-layerslider-wrapper">';
}

function my_ls_after_content() {
	echo '</div>';
}

?>

Filter hooks

Public filter reference

Read the WP Codex entry for more information about using filters.

Filter hook examples

The following example uses the layerslider_override_defaults filter to change some default settings related to appearance.

<?php

add_filter('layerslider_override_defaults', 'my_override');
function my_override($defaults) {

	// Uncomment these to see all settings
	// echo '<pre>';
	// var_dump($defaults);
	// echo '</pre>';

	// Override some defaults
	$defaults['slider']['type']['value'] = 'fullwidth';
	$defaults['slider']['skin']['value'] = 'myskin';

	return $defaults;
}

?>

Another example of using the layerslider_override_defaults filter to apply the same transition on slides by default.

<?php

add_filter('layerslider_override_defaults', 'my_override');
function my_override($defaults) {

	$defaults['slides']['2dTransitions']['value'] = '5';

	return $defaults;
}

?>

Example of completely removing the generator HTML meta tag from the page source.

<?php

add_filter('ls_meta_generator', function( $str ) {
	return '';
});

?>

LayerSlider JavaScript API

This API is used to interact with live sliders on the front-end. You can find it in the End-User documentation. We've placed it there because this developer documentation focuses on WordPress-oriented plugin APIs and integration, while the LayerSlider JavaScript API is used for slider customization. This page is just here to let you know about this additional API that might be an interest to you.

Release log

Changes in LayerSlider 7.2.2

Fixed the 'data' property in LS_Sliders::find(). When set to false, this method no longer sends back any data.

Changes in LayerSlider 7.0.0

LayerSlider 7 is a huge update with tons of changes, both visible and under the hood. Nevertheless, it should behave and work the same from a developer standpoint. If you're bundling LayerSlider with your theme, there shouldn't be anything to do. Minor changes we can highlight:

• Required WordPress version changed from 3.5 to 4.4.
• Required PHP version changed from 5.3 to 5.4.
• "Sliders" are now called "Projects" to represent all the different types of work you can build with LayerSlider, such as sliders, popups, hero scenes, image galleries, slideshows, animated page blocks, etc.
• By default, layers are now using the <ls-layer> custom HTML element to prevent inheriting unwanted style settings.
• We've completely moved away the "inherit from site" default values when it comes to font-size, font-family, and other style settings. This is to keep the back-end and front-end appearance in sync.

We expect that the changes mentioned in the last two point should dramatically reduce support inquiries. Inherited styles from 3rd parties was a common issue. However, these changes may also affect some people who didn't set custom fonts.

These cases should be very rare. However, if someone has too many projects to update them, you can offer a CSS solution something like the following:

.ls-container .ls-layer,
.ls-container .ls-l {
	font-family: inherit !important;
}

LayerSlider has a CSS Editor where users can easily paste CSS codes like this.

Changes in LayerSlider 6.11.0

Very important release containing crucial fixes.

• This release maximizes compatibility with the TGMPA class that is used to bundle plugins in themes. Mainly, it addresses an issue that could prevent users receiving LayerSlider updates from theme authors.
• Added deprecation warnings when using the lsSliderById() and lsSliders() functions.
• Slider IDs are now always randomized in the generated markup to avoid collisions in various cases.
• Read the release log in the End-User Documentation. A lot has changed and some might be relevant to you and your custom made solutions.

Changes in LayerSlider 6.10.2

• When LayerSlider detects outdated and unsupported versions of PHP, it now avoids loading the plugin altogether and displays a permanent notice instead. This notice informs users about the need to upgrade the PHP version on their sites and provides instructions on what they should do. Currently, we require PHP 5.3.0, but we might change that to around the PHP 5.6.0 territory in the future.
• When there are multiple copies of LayerSlider activated on a site, it leaves one copy active and suppresses all other copies to avoid issues. In a case like that, it displays a permanent notice to users explaining the situation and providing instructions on what they should do. This is drastically different from our old solution, that was a hard bail by calling PHP's die() function with an error message. While this is a much better solution, keep in mind that it also allows multiple copies of LayerSlider to be active simultaneously and deciding which copies get suppressed highly depends on the loading order.

Changes in LayerSlider 6.9.4

• Fixed the LS_SliderLibrary JavaScript error caused by the changes in WordPress 5.3. If you've used this API to provide a custom slider picker to your customers, please release an update as soon as you can.

Changes in LayerSlider 6.9.0

• This release introduces Slider Groups, which are essentially special records in the same wp_layerslider database table. The LS_Sliders class and the legacy lsSliders() function adapts to these changes automatically. However, if you're making custom queries, make sure to filter out records where flag_group equals to 1. Check out the Working with sliders section to learn more.
• There's a new and very easy way to implement slider pickers. The LS_SliderLibrary JS API allows you to enjoy all the new features with minimal code, so you can focus on what really matters to you.

Changes in LayerSlider 6.8.0

• You can now override slider settings via the shortcode or the PHP function. This can be useful if you want to make small changes in certain situations without duplicating the slider. For example, you might want to change the slider skin on some pages to fit better to a different page style. Check the Overriding settings section for more information.

Changes in LayerSlider 6.7.5

• The theme bundling guide now includes a "Maximizing compatibility" section. The newly introduced changes allows your theme to override and enforce certain LayerSlider settings, such as loading scripts at the footer, etc.

Changes in LayerSlider 6.6.7

• Updated licensing terms and theme integration guide.

Changes in LayerSlider 6.6.3

• Added filter hook: layerslider_skin_url
• Added filter hook: layerslider_attr_list
• Updated some examples.

Changes in LayerSlider 6.6.0

• Fixes for overriding default settings like skins that not always worked as expected.
• Fixes in the LS_Sources class that affected externally loaded skins and other materials.

Changes in LayerSlider 6.5.8

• Documented the ls_meta_generator filter hook.

Changes in LayerSlider 6.4.0

• Added layerslider_slider_init filter hook to provide an option to change the JavaScript slider initialization code.
• Added additional parameters to layerslider_slider_markup filter hook to provide context with more information about the affected slider.

Changes in LayerSlider 6.2.0

• Added layerslider_root_url filter to override paths in case the plugin is loaded externally from a custom location. See Filter Reference to learn more.

Changes in LayerSlider 6.0.0

• Updated the Bundling in themes section
• The layerslider database table will now be created on the fly to provide better support for multisite installations. Make sure to use one of the actions hooks to execute your install/update code, as the DB table may not be accessible at any time.
• Bundled demo sliders can now be tagged to work with our new Import Templates modal window. Read the updates Working with sliders section.
• Make sure to read the End-User documentation as well, since version 6.0.0 has countless new features, improvements and other changes.

Changes in previous versions

Version 5.6.2

• The layerslider_slider_markup filter hook no longer contains the JS init code

Version 5.6.0

• Fixed the layerslider_slider_markup filter hook

Version 5.5.0

• Added a new section for listing constants and global variables used by LayerSlider.
• Improved some example codes

Version 5.4.0

• Added filter to override the slider markup before output

Version 5.3.2

• LS_Sliders::add() now accepts a 3rd parameter to set the slider slug
• Slider slugs are now added properly after importing

Version 5.3.1

• Fixed LS_Sources::urlForSkin() returning invalid URLs on certain installations.
• Dropped multibyte functions in LS_Sources methods, using strtolower() to have lowercase handles instead. The result may vary depending on the server locale.

Version 5.3.0

• Added LS_Sources class to load skins and demo sliders externally.
• The LayerSlider shortcode is now registered globally, thus page builder solutions can pick it up automatically.
• Added new API method 'redraw' to update the slider's layout and contents.

Version 5.2.0

• From now on automatic updates can be enabled on two websites at the same time with a purchase code
• Disabling the auto-update in themes now only warns the users about the feature requirements instead of hiding the box

Version 5.1.0

• Read the release log in the regular docs
• Updated documentation with fixes and extended content
• Changed import/export method, affects samples
• LS_Sliders::find() now accepts slider slug
• LS_Sliders::find() now accepts slider array of IDs
• Fixed $title param of LS_Sliders::add()
• Updated layerslider database table
• Fixed detecting version changes and running upgrade scripts

Version 5.0.x

• Read through all the new docs (including the one for End-Users). Version 5.0.0 has major changes under the hood.
• Old slide & layer transitions are deprecated. They will still work on front-end pages, but might be dropped completely in future versions. You should take this under consideration when changing the defaults.
• Some of the new APIs are still experimental and will likely change. Use them for your own risk.

Major changes till 5.0.0

• Using the Options API for storing sliders is deprecated since v3.6.0, and backwards compatibility will be dropped in the near future.