# LayerSlider

## Responsive WordPress Slider Plugin

### Documentation for WordPress Theme Developers

- Overview
  - Thank you
  - Changelog
- About licensing terms
  - Restrictions in licensing terms
  - The preferred way
  - Benefits
  - Disadvantages
- Step-by-step guide
  - Copy the plugin into your theme folder
  - Including and activating LayerSlider WP
  - Setting the plugin's path and disabling auto-updates
  - So what's next?
  - One final example

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

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

# About licensing terms

### Restrictions in licensing terms

The Envato licensing terms and conditions prohibits you to include the plugin as a standalone item. This means that you cannot ask your users to treat it as a separate item for installation, you have to integrate it into your theme.

### The preferred way

The preferred way it that you must hide the plugin within your theme and load it manually in your functions.php file. This requires some modifications, but it can be done quickly and easily. Below there is a step-by-step guide to do this.

### Benefits

- It complies for the Envato licensing terms,
- It is automatic, your users don't have to bother with plugin installation,
- The plugin will be activated automatically,
- There won't be any dependency, every feature will work by default,
- And you can achieve deeper integration with many features built upon the plugin

### Disadvantages

- You need to do some extra work to achieve these benefits, but it only takes a few minutes

# Step-by-step guide

### Copy the plugin into your theme folder

First, you have to copy the plugin into your theme folder. This is located in your "/wp-content/themes/<your_theme>/" folder. In our sample we created a "plugins" folder in the theme root directory, this is the place where we copied LayerSlider WP. Later, you will need to edit some of the plugin files, so always keep in mind that we are referring to this location, but it can be different with your own file-structure.

### Including and activating LayerSlider WP

You can include and activate LayerSlider WP in your functions.php file. This file is located under your "/wp-content/themes/<your_theme>/" folder.
Please note that this code assumes there is a "plugins" folder in your theme root directory and LayerSlider WP is located in this folder. If you are using a different file-structure, you need to change the file path on line 8.
Also, in this code, please replace the "<unique_prefix>" part with your own unique name. The name of the theme is recommended.
We have extended the inner condition with a version-check branch to make sure the plugin is re-activated when needed. This helps you to avoid database-related issues if something changes in a new release.

    <?php

    /**************************/
    /* Include LayerSlider WP */
    /**************************/

    // Path for LayerSlider WP main PHP file
    $layerslider = get_stylesheet_directory() . '/plugins/LayerSlider/layerslider.php';

    // Check if the file is available to prevent warnings
    if(file_exists($layerslider)) {

    	// Include the file
    	include $layerslider;

    	// Get last version number, defaults to 1.0
    	$layerslider_last_version = get_option('layerslider_last_version', '1.0');

    	// Activate the plugin if necessary
    	if(get_option('<unique_prefix>_layerslider_activated', '0') == '0') {

    		// Run activation script
    		layerslider_activation_scripts();

    		// Save a flag that it is activated, so this won't run again
    		update_option('<unique_prefix>_layerslider_activated', '1');

    		// Save the current version number of LayerSlider
    		update_option('layerslider_last_version', $GLOBALS['lsPluginVersion']);

    	// Do version check
    	} else if(version_compare($GLOBALS['lsPluginVersion'], $layerslider_last_version, '>')) {

    		// Run again activation scripts for possible adjustments
    		layerslider_activation_scripts();

    		// Update the version number
    		update_option('layerslider_last_version', $GLOBALS['lsPluginVersion']);
    	}
    }

    ?>

If you did it right, you can see that the LayerSlider WP menu item appeared in your WP admin area. It won't work just yet, we need some further changes, so don't scare if you run into some issues.

### Setting the plugin's path and disabling auto-updates

LayerSlider needs to load some plugin resources such as CSS and Javascript files, so you have to specify the path of the plugin where these resources can be found.
Remember, we created a "plugins" folder with the contents of LayerSlider in our sample, but you may use a different file-structure, so you may have to rewrite this path.
Also, our auto-update mechanism requires an item purchase code for LayerSlider WP and it doesn't work with integrated plugins, so you should disable it. It is your responsibility to release theme updates with the most recent version of our plugin. It is always a good idea as we continuously improve the plugin and fix issues.
The most easiest and flexible way to override these settings is to set up function for the "layerslider_ready" hook in your functions.php file with the contents as appear below. This way the required modifications can be done without touching the plugin's source code, and you can update LayerSlider just by overriding its folder.
As WordPress actually loading the plugins first, you are safe to put these overrides without using a hook, but we strongly recommend you to do, as it can provide further functionality in future versions of the plugin.

    <?php

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

        // Define your function
        function my_layerslider_overrides() {

            // Items to override
            $GLOBALS['lsPluginPath'] = get_stylesheet_directory_uri() . '/plugins/LayerSlider/';
            $GLOBALS['lsAutoUpdateBox'] = false;
        }
    ?>

### So what's next?

LayerSlider WP is now integrated into your theme and it is fully functional. However, if you want to make your users 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. It is also can be wise that you offer an option to disable the plugin, since WordPress won't recognize it as a normal plugin and your users won't be able to deactivate it by default.
Unfortunately, this documentation doesn't include these techniques. We are assume that you are a developer who understands how WordPress works, so you should be able to archive these kind of features by yourself. We made this documentation to make your life easier without the need to analyze our codebase.

### Getting the sliders

#### Get a slider by its ID

    mixed lsSliderById( mixed $id )

With this function, you can get a slider by its datbase 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 returs 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

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