LayerSlider Responsive WordPress Slider Plugin

# LayerSlider

## Responsive WordPress Slider Plugin

### Documentation for WordPress Theme Developers

- Overview
  - Thank you
- Requirements
  - Introduction
  - Licensing terms
  - Our terms
- Step-by-step guide
  - Setting up TGM Plugin Activation class
  - Including LayerSlider in your theme
  - Configuring TGM for plugin installation
  - Configuring LayerSlider externally
  - What's next?
  - What to expect in the future
  - Working with database and sliders
- Changelog
- Contact

### Overview

This documentation covers all the things you need to know to integrate LayerSlider WP into your WordPress theme. Please note that this documentation is made for developers, and it doesn't deal with the plugin itself. For information about installing and using the plugin, please read the other documentation.

### Thank you

Thank you for purchasing LayerSlider WP. If you have any questions beyond the scope of this documentation, please do not hesitate to contact us.
We are excited that you chose LayerSlider WP for your theme, if you want to share your work with us, we would love to see it.

# Requirements

#### 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.

#### Licensing terms

- You need to purchase an extended license per themes.
- You cannot redistribute the item "as-is", even if you modify it or you make a derivative version for another CMS.

#### Our terms

- 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.
- 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 or use the plugin separately from your work.
- 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 really easy with a minute of work.
- 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.
- 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 when your users are switching themes.

# Step-by-step guide

### Setting up TGM Plugin Activation class

Download the latest version of TGM Plugin Activation class from their website. The DL package has an example configuration, you just need to copy those into your theme's directory and include the the example.php in your functions.php file. In our example we put them into a folder called "plugins", so our code looks like this:

    <?php
    	require_once dirname( __FILE__ ) . '/plugins/example.php';
    ?>

You can put those file anywhere in your theme you want with a name of your own choosing, but make sure you are referencing to the current path. The example PHP file will include the TGM Activation class, and you can use it all of the other plugins you want to include in your theme.

### Including LayerSlider in your theme

Copy the of the "installable" ZIP of LayerSlider into the same directory you have set up for the TGM Activation class next to the example plugin ZIP.

### Configuring TGM for plugin installation

The example.php file already contains a sample configuration and you only need to add LayerSlider as a new array item.

Below you can see a sample array item to configure TGM for plugin installation. Make sure you are referencing for the correct source path. We are require you to set the force_deactivation option to true. To follow convention, you should only set the plugin as required if it is absolutely necessary for your theme to work properly, TGM will offer it to install anyway.

When you include an updated plugin, you need to update the version number, so TGM can recognize it and offer the update for your users.

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

### Configuring LayerSlider externally

We have an action hook with you can override the plugin's defaults externally from your theme. Since Envato now requires TGM, you need to update your code you may used previously. Our auto-update feature require an Item Purchase Code that your users won't have, and you should disable auto-updates and hide its settings from the LayerSlider admin page.

    <?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;
        }
    ?>

### What's next?

LayerSlider WP is now properly integrated into your theme and ready to use by your customers. However, if you want to make them really happy, there are some other things you should consider. For example, it is always a good idea to offer an option in the WP page editor where your users can choose a slider to display.
Unfortunately, this documentation doesn't include techniques like this. We are assume that you are a developer who understands how WordPress works and should be able to archive these kind of features on your own.

### What to expect in the future

In future versions we will add a full and stable API for developers to change any settings the plugin have (including sliders), load your own skins, and to run custom filters before the slider is being displayed. Our goal is to offer the necessary tools for theme authors to control the plugin externally without modifying a single line in the original version.

### Working with database and sliders

#### Get a slider by its ID

    mixed lsSliderById( mixed $id )

With this function, you can get a slider by its database ID. The $id parameter is required. Returns an associative array with the slider details (see below) on success, or false on failure.

#### Get the most-recent sliders

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

This function returns the most recent sliders. Every parameter is optional. The $limit argument defaults to 50 entry. Without specifying the $desc parameter, the function returns the slider in descending order of creation. This function does not return the $data object for sliders by default, you need to set the third parameter to "true" for that. Returns an empty array on failure or if no sliders were found.

#### Returning data

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

Type | Key | Purpose
--- | --- | ---
int | $id | The database ID of the slider
string | $name | The user defined name of the slider if any
array | $data | The slider data object that contains all the settings
int | $date_c | UNIX timestamp of the creation
int | $date_m | UNIX timestamp of last modification

### Changelog

Important: Please note that this changelog doesn't deal with the plugin itself, it is made for developers and it only lists the changes that affects them, and may requires modifications in their work.

4.6.3

- Introduced beta release channel for authors.

4.6.1

- Updated documentation based the new Envato theme submission requirements

4.6.0

- Added tools for authors:
  - Extended the loading sample script with version-check to avoid problems caused by missing re-activation
  - Added "layerslider_ready" hook to override some required settings in the plugin without modifying its files
  - Added public functions to get sliders from database
- Other important changes:
  - Added WPML support
  - Resolved the Isotope and jQuery Transit incompatibility

4.0.0

- Auto-updates The new version includes auto-updates, but it requires an item purchase code (which your users won't have) and it isn't working with integrated plugins, so you should disable it. Check the step-by-step guide for more information about disabling auto-updates.
- Tons of changes LayerSlider WP 4.0.0 is our next major release, it includes tons of new features, improvements and other changes. You should check the changelog in the other documentation for more info about the new version.

3.6.0

- Localization ready You can find the .PO file if you want to translate the entire plugin (including the admin user interface) in the languages folder.
- Language support You can now create multilingual sliders with popular translation plugins like qTranslate.
- Multisite ready LayerSlider WP 3.6.0 is now supports network-wide activation and it automatically handles the database when a Super Admin adds a new site to the network.

3.5.0

- New data storage: LayerSlider WP doesn't use the WP options API anymore, it has a separate database table now. The data structure also changed, we are now using JSON serialization. If you are working with LayerSlider WP data for example to offer an option to your users to select a slider which will be shown on a page, you need to change your code for the new data storage. You can find an example at the end of this documentation.
  Please note that LayerSlider WP 3.5.0 is compatible with the old data storage, your users will be prompted to convert their data associated with the plugin with a banner on the top of the page.

### Contact us!

## If you like our works.
If you need a help in using one of our CodeCanyon items.
If you have a great idea which we can work together.