Developer documentation for LayerSlider WP

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

- Licensing FAQs
- Extended license

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

We highly recommend you to disable the automatic updates feature, since it requires a valid Item Purchase Code for LayerSlider that your customers won't have. To do that, you can use the `layerslider_ready` action hook to override the corresponding global variable as it can be seen in the example below.

Version 5.2.0 or newer will only warn users about the feature requirements instead of completely hiding the auto-update box. This helps users avoiding difficulties if they have a separate license for LayerSlider and would like to use this feature.

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

#### About plugin constants and 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

Name | Purpose
--- | ---
LS_ROOT_FILE | Filesystem path for the plugin's main file, which can be used to identify its slug and base name. Ex.: /path/to/your/site/wp-content/LayerSlider/layerslider.php
LS_ROOT_PATH | Filesystem path for the plugin's folder. Useful when you want to include specific files located in the LayerSlider folder. Does not include a trailing slash. Ex.: /path/to/your/site/wp-content/LayerSlider
LS_ROOT_URL | Web URL pointing to the LayerSlider plugin directory. Does not include a trailing slash. Ex.: http://yourdomain.com/wp-content/LayerSlider
LS_PLUGIN_VERSION | The installed version of LayerSlider. Ex.: 5.4.0
LS_PLUGIN_SLUG | The plugin's slug. Essentially it's the name of the plugin folder. Ex.: LayerSlider
LS_PLUGIN_BASE | The plugin base name. Usually used by internal WP functions. Ex.: LayerSlider/layerslider.php
LS_MARKETPLACE_ID | LayerSlider's Envato Market item ID.
LS_DB_TABLE | The LayerSlider database table name that stores your sliders. Always use in conjunction with $wpdb->prefix to support multisite installations. Consider using LS_Sliders class instead of custom queries.
LS_TEXTDOMAIN | The textdomain used by LayerSlider for gettext calls.

#### List of global variables

Name | Purpose
--- | ---
$GLOBALS['lsPluginPath'] | [DROPPED] This variable is no longer available. Use the LS_ROOT_URL constant instead.
$GLOBALS['lsPluginVersion'] | [DROPPED] This variable is no longer available. Use the LS_PLUGIN_VERSION constant instead.
$GLOBALS['lsAutoUpdateBox'] | Disables the auto-update feature, since it's unavailable for theme users. Use in conjunction with action hooks. See section Bundling in themes for more information and examples.

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() [, string $slug = '' ]]] )`

  Adds a new slider with the provided settings and slug. All parameters are optional. The plugin will use the default slider 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.

#### About the LS_Sources class

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 asset you might want to use to adjust the plugin according the needs of your work.

#### Feature availability

Externally loaded skins have full feature availability. They will show up in the slider settings for the users to choose them, and all the other features (e.g.: the LayerSlider skin editor) will work in the same way as the built-in ones.

#### Structure of loadable skins

Every skin needs to have its own separate folder. The lowercase base name of the skins' folder will be used as a handle to manage the loaded skins. You need to avoid adding multiple skins with the same folder name, as the later ones will override previously added skins. This also means that you cannot use the names of the built-in skins, which are: borderlessdark, borderlessdark3d, borderlesslight, borderlesslight3d, carousel, darkskin, darkskin, defaultskin, fullwidth, fullwidthdark, glass, lightskin, minimal, noskin, v5.

Each skins folder needs to contain a `skin.css` file, which will be loaded by the slider when it's needed. The `skin.css` file name is used to validate the folder, and you cannot use another name or file type.

#### Skin metadata

Inside your skins' folder, you can add an additional `info.json` file that LayerSlider will detect automatically and will use to get additional information for your skin. A typical JSON would be:

    {
    	"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" : ""
    }

Make sure to provide valid JSON data instead of a Javascript object literal.

Currently not every metadata is being used by LayerSlider, but we highly recommend you to keep all of them up-to-date, as future releases might introduce changes based on these informations. For more examples about the info.json file, please see our skins in the /static/skins/ directory.

#### API methods

- (void) `LS_Sources::addSkins( string $path )`

  Adds the skins from the directory provided. $path is the directory that holds all of your skins. When a skin.css file is found inside $path it's assumed to be a direct skin directory and LayerSlider won't attempt to find children skin folders. As an additional measure of security, please use absolute paths in all cases.

      LS_Sources::addSkins( get_template_directory().'/ls-skins' ) // Loads all skins from the ls-skins directory
      LS_Sources::addSkins( get_template_directory().'/ls-skins/myskin' ); // Loads only "myskin" from the ls-skins directory

- (void) `LS_Sources::removeSkin( string $handle )`

  Removes a previously added skin by its lowercase folder name as being $handle.

      LS_Sources::removeSkin('myskin');

- (array) `LS_Sources::getSkin( string $handle )`

  Returns skin information by its lowercase folder name as being $handle.

      $skin = LS_Sources::getSkin('myskin');
      var_dump($skin); // Check what's inside

- (array) `LS_Sources::getSkins( )`

  Returns all skins.

      $skins = LS_Sources::getSkins();
      var_dump($skin); // Check what's inside

- (string) `LS_Sources::pathForSkin( string $handle )`

  Returns an absolute path for the skin's directory by its lowercase base name as being $handle. The returned path has a trailing slash.

      $path1 = LS_Sources::pathForSkin('myskin');
      $path2 = LS_Sources::pathForSkin('borderlessdark');
      // $path1 is /path/to/your/site/wp-content/themes/kreatura/ls-skins/myskin/
      // $path2 is /path/to/your/site/wp-content/plugins/LayerSlider/static/skins/borderlessdark/

- (string) `LS_Sources::urlForSkin( string $handle )`

  Returns an absolute URL for the skin's directory by its lowercase base name as being $handle. The returned URL has a trailing slash.

      $url1 = LS_Sources::urlForSkin('myskin');
      $url2 = LS_Sources::urlForSkin('borderlessdark');
      // $url1 is http://mysite.com/wp-content/themes/kreatura/ls-skins/myskin/
      // $url2 is http://mysite.com/wp-content/plugins/LayerSlider/static/skins/borderlessdark/

#### Feature availability

Externally loaded demo sliders have full feature availability. They will show up in the list of importable sliders and can be used in the same way as the built-in ones.

#### Structure of importable demo sliders

Every demo slider needs to have its own folder. The lowercase base name of the sliders' folder will be used as a handle to manage the loaded demo sliders. You need to avoid adding multiple sliders from the same folder name, as the later ones will override previously added sliders. This also means that you cannot use the names of the built-in demo sliders, which are: carousel, fullwidth, v5.

Each slider folder needs to contain a `slider.zip` file, which will be used to import the demo content. The `slider.zip` file name is used to validate the folder, and you cannot use another name or file type.

If `preview.png` is found in the demo slider folder, it will be used in the list of importable sample sliders to display a preview image of your work. Preview images should have 150x150px dimensions and use PNG format with transparency.

Demo slider folders should also have an additional `info.json` file that contains matadata for your slider. See the details in the next section.

For working examples, please see our sample sliders in /demos/ within the LayerSlider plugin directory.

#### Slider metadata

Inside your demo sliders' folder, you can add an additional `info.json` file that LayerSlider will detect automatically and will use to get additional information for your slider. A typical JSON would be:

    {
    	"name" : "Full width demo slider",
    	"version" : "5.3.0",
    	"requires" : "5.1.0",
    	"author" : "Kreatura Media",
    	"created" : "2013-12-23",
    	"updated" : "2013-12-23",
    	"note" : ""
    }

Make sure to provide valid JSON data instead of a Javascript object literal.
The version number for `requires` needs to be at least 5.1.0, since this version introduced the new ZIP archive import/export solution.

Currently not every metadata is being used by LayerSlider, but we highly recommend you to keep all of them up-to-date, as future releases might introduce changes based on these informations. For more examples about the info.json file, please see our sliders in the /demos/ folder within the plugin's directory.

#### API methods

- (void) `LS_Sources::addDemoSlider( string $path )`

  Adds the demo sliders from the directory provided. $path is the directory that holds all of sliders. When a slider.zip file is found inside $path it's assumed to be a direct demo slider directory and LayerSlider won't attempt to find children folders. As an additional measure of security, please use absolute paths in all cases.

      LS_Sources::addDemoSlider( get_template_directory().'/ls-sliders' ) // Loads all demo sliders from the ls-sliders directory
      LS_Sources::addDemoSlider( get_template_directory().'/ls-sliders/myslider' ); // Loads only "myslider" from the ls-sliders directory

- (void) `LS_Sources::removeDemoSlider( string $handle )`

  Removes a previously added demo slider by its lowercase folder name as being $handle.

      LS_Sources::removeDemoSlider('myslider');

- (array) `LS_Sources::removeDemoSlider( string $handle )`

  Returns demo slider information by its lowercase folder name as being $handle.

      $slider = LS_Sources::getDemoSlider('myslider');
      var_dump($slider); // Check what's inside

- (array) `LS_Sources::getDemoSliders( )`

  Returns all previously added demo sliders.

      $sliders = LS_Sources::getDemoSliders();
      var_dump($sliders); // Check what's inside

- (string) `LS_Sources::pathForDemoSlider( string $handle )`

  Returns an absolute path for the demo slider's directory by its lowercase base name as being $handle. The returned path has a trailing slash.

      $path1 = LS_Sources::pathForDemoSlider('myslider');
      $path2 = LS_Sources::pathForDemoSlider('fullwidth');
      // $path1 is /path/to/your/site/wp-content/themes/kreatura/ls-sliders/myslider/
      // $path2 is /path/to/your/site/wp-content/plugins/LayerSlider/static/demos/fullwidth/

#### Managing sample transitions

This API is not yet available.

#### Managing Google Fonts

This API is not yet available.

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

- (void) `ls_meta_generator( string $html )`

  This filter can be used to remove or modify the generator meta tag inserted by LayerSlider.

- (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 later influences. Use this filter wisely, as it can break previously created sliders, since the users won't be able to change or prevent these overrides.

- (string) `layerslider_slider_markup( string $markup )`

  This is the final step before printing the slider markup. This filter can be useful to work with the generated HTML string instead of the raw slider data.

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

- Added `ls_meta_generator` filter hook

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