LayerSlider WP for developers

Responsive WordPress Slider Plugin

Version: 5.1.1 | Released: 7th March 2014

Table of Contents

Current Chapter: Overview

It's for developers

This documentation is made explicitly for developers to make their lives easier by describing how the plugin internals are working. If you are not a programmer, please read the Documentation for End-Users, you don't need to follow any of the instructions here.

Overview

This documentation covers the things you need to know about incorporating LayerSlider WP in a larger work such as a WordPress theme. It contains guides for bundling the plugin within your work, and it explains several ways to modify/extent the features and capabilities of the plugin.

Licensing terms

  1. You need to purchase an extended license of the plugin per themes which including the Item.
  2. You cannot redistribute the item "as-is", even if you modify it or you make a derivative version for another platform.

Please read the full licenses online on the following links:

Usage terms

Since the current licenses do not deal with re-selling Items, Envato lets authors to decide whether they grant permission for bundling Items or not. We have the following conditions, and you need to follow them:

  1. You cannot offer the plugin as a stand-alone item

    You can't include the plugin separately from your theme in the download package, you have to use the TGM Plugin Activation class. See the "Bundling" section for more information.

  2. You cannot provide an Item Purchase Code for your customers

    Since Envato doesn't have a "multi-use" or transferable license, your customers are not entitled to receive an Item Purchase Code with your theme and use the plugin separately from your work.

  3. Updating the plugin is your own responsibility

    Since your customers can't receive updates from us, you need to handle this on your own. The TGM Plugin Activation class makes it simple, and we are providing the necessary tools to make it quick as well.

  4. You need to handle LayerSlider related support requests after your customers

    We would like to hear your thoughts and suggestions to fix issues and improve our items based on your feedback, but we cannot provide free support for your customers, this is your own responsibility.

  5. Use our preferred settings for TGM plugin installation

    With the above mentioned licensing terms you need to configure the plugin in TGM to automatically activate & deactivate it whenever your users are switching themes.

Introduction

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

Download the latest version of TGM Plugin Activation class from their website. Follow their guides and examples to incorporate it into your theme properly.

Example TGM plugin configuration

Below you can see an example configuration for LayerSlider. Remember, we are requiring you to set the force_deactivation option to true in accord our licensing and usage terms.

// LayerSlider config

array(
	'name' => 'LayerSlider WP',
	'slug' => 'LayerSlider',
	'source' => get_stylesheet_directory() . '/plugins/layerslider.zip',
	'required' => false,
	'version' => '5.1.0',
	'force_activation' => true,
	'force_deactivation' => true
)

Disabling the auto-update feature

You should disable the auto-update features since it requires a valid Item Purchase Code that you can't provide to your customers. To do that, you can use the layerslider_ready action hook to override the corresponding global variable as it can be seen in the below example.

<?php

    // Register your custom function to override some LayerSlider data
    add_action('layerslider_ready', 'my_layerslider_overrides');
    function my_layerslider_overrides() {

        // Disable auto-updates
        $GLOBALS['lsAutoUpdateBox'] = false;
    }
?>

Database functions to work with sliders

  • (mixed) lsSliderById( int $ID )

    Get a slider by its database ID. Returns an associative array with the slider details (see below) on success, or false on failure.

  • (array) lsSliders([mixed $limit = 50 [, bool $desc = true [, bool $withData = false ]]] )

    Returns the most recent sliders on success, or an empty array otherwise. Every parameter are optional. This function does not return the $data object for sliders by default, you need to set the third parameter to "true" for that.

Returning slider data

The records returned by the above functions are associative arrays with the following contents:

Type Key Description
int $id The database ID of sliders.
string $name The user defined name of sliders (if any).
array $data The slider data object containing all of its settings.
int $date_c UNIX timestamp for date of creation.
int $date_m UNIX timestamp for date of last modification.
This API is a working draft. Minor changes will likely happen in future versions.

Introducing the LS_Sliders class

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

  • (array) LS_Sliders::find( [mixed $filters] )

    Finds sliders with the provided filters and settings. See also the corresponding section below on this page for more information and examples. Accepts:

    • (int) ID of a slider,
    • (string) Slug of a slider,
    • (array) Array of slider IDs as integers
    • (array) The filter object, see below on this page
  • (int) LS_Sliders::count( void )

    Returns the total number of found sliders from the latest query with ignoring pagination settings.

  • (int) LS_Sliders::add( [string $title = 'Unnamed', [ array $data = array() ]] )

    Adds a new slider with the provided settings. All parameters are optional. The plugin will use the default settings if you provide partial/empty slider data.

  • (bool) LS_Sliders::remove( int $ID )

    Removes a slider by its database ID. Returns a boolean value to indicate success or failure. This method preserves the actual data in DB to restore it later.

  • (bool) LS_Sliders::delete( int $ID )

    Permanently deletes a slider by its database ID. Returns a boolean value to indicate success or failure.

  • (bool) LS_Sliders::restore( int $ID )

    Restores a previously removed slider by its database ID. Returns a boolean value to indicate success or failure.

LS_Sliders filter object

Type Key Default Description
string columns '*' Database columns expected to be returned.
string where '' (empty string) Standard MySQL WHERE statement
array exclude array('hidden', 'removed') Rows excepted to be exluded from search results.
string orderby 'date_c' The order result by a column.
string order 'DESC' The order of returned data.
int limit 10 Limit the number of returned sliders.
int page 1 Get results for a specific page when using pagination.
bool data true Returns the data object of sliders.

Examples

Find a slider by its database ID.

$sliders = LS_Sliders::find(2);

Find a 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

Type Key Description
int $id The database ID of sliders.
string $author The WP user ID of the slider author.
string $name The user defined name of sliders (if any).
string $slug The slider's slug (if any).
mixed $data The slider's data object containing all of its settings. It may returned as a string or completely excluded from results depending on your filters.
int $date_c UNIX timestamp for date of creation.
int $date_m UNIX timestamp for date of last modification.
This API is not yet available. It will likely be introduced in one of our upcoming updates.

Working with sources

The sources API will let you to load customized contents into the plugin externally. This includes skins, transitions, sample sliders, Google fonts, and any other material you might want to use to adjust the plugin according the needs of your work.

Private actions

Some additional action hooks are already used in the plugin internals, but these are not stable yet and can change at any time. They will be added to the list above when they are ready.

Public action reference

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

  • layerslider_installed

    Runs only on the first installation, even if the plugin was removed previously.

  • layerslider_activated

    Runs when the plugin has been activated.

  • layerslider_updated

    Runs when the plugin was updated and a new version is recognized. This method also works when a user overrides the plugin folder on FTP.

  • layerslider_deactivated

    Runs when the plugin has beed deactivated.

  • layerslider_uninstalled

    Runs when the plugin has beed uninstalled.

  • layerslider_ready

    Runs when the plugin has loaded and it is ready to process custom code. This hook fires on every page refresh, and it might slow down pages.

  • layerslider_before_slider_content

    Runs before printing slider content. This action can be used to print custom HTML before the slider containment element.

  • layerslider_after_slider_content

    Runs after printing slider content. This action can be used to print custom HTML after the slider containment element.

Actions examples

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

<?php

add_filter('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_filter('layerslider_before_slider_content', 'my_ls_before_content');
add_filter('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>';
}

?>
The structure of the defaults object is not yet final. Consider potential risks before using it.
Although the filter API is stable, the slider data to be processed may change over time.

Private filters

Some additional filters are already used in the plugin internals, but these are not stable yet and can change at any time. They will be added to the list above when they are ready.

Public filter reference

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

  • (array) layerslider_pre_parse_defaults( array $slider )

    Runs before parsing defaults. It contains the raw slider data, which includes legacy property names, and it should not be used.

  • (array) layerslider_override_defaults( array $defaults )

    Provides an easy way to change the default slider settings. It applies on the admin interface, but it will take effect in generating the slider markup as well. This filter won't override previously created sliders.

  • (array) layerslider_post_parse_defaults( array $slider )

    Runs after the slider data was parsed based on the defaults, and the plugin is ready to override settings without any later influences. Use this filter wisely, it can break previously created sliders since it is the final step before printing the markup.

Filters example

The following example uses the layerslider_override_defaults filter to change some default settings related with 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']['fullWidth']['value'] = true;
	$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;
}

?>

Release log for developers

This section contains only changes, which could affect developers and their custom solutions built on top of the plugin.

Make sure to read the documentation for End-Users as well.

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.