1. Documentation
  2. Plugins
  3. WooSlider
  4. Codex

Using the WooSlider slideshows API

WooSlider provides an easy-to-use slideshows API for integrating custom slideshow types and custom settings for those types. This tutorial will cover the basics of creating and integrating a custom slideshow type into WooSlider. NOTE: The following tutorial contains a significant amount of developer jargon.

How does integration work with WooSlider? ↑ Back to top

WooSlider exposes several areas, via WordPress filters, for adding custom slideshow types, specifying the function used to generate the content and where to add custom settings for this slideshow. In this example, we’ll inspect all areas of this, using a custom static content slideshow as an example (while the same result can be achieved using the “slides” slideshow type and inserting the content into the WYSIWYG editor for each slide, this example assumes that very specific custom HTML is required- this could easily be replaced with a third-party API request or a query to the database).

Integration structure ↑ Back to top

Integrations with WooSlider are best handled via separate WordPress plugins. These should contain a structure where by the plugin acts on the “plugins_loaded” WordPress action hook, to ensure that WooSlider is fully loaded before the plugin needs to act. A boilerplate structure for this would be:

<?php
/*
Plugin Name: WooSlider - My Custom Slideshow
Plugin URI: http://your-plugin-website.com/
Description: This is my custom WooSlider slideshow.
Version: 1.0.0
Author: Your Name Here
Author URI: http://your-website.com/
License: GPL version 2 or later - http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/

add_action( 'plugins_loaded', array( 'My_Custom_Slideshow', 'init' ), 0 );

class My_Custom_Slideshow {
 /**
     * Initialize the plugin, check the environment and make sure we can act.
     * @since  1.0.0
     * @return  void
     */
    public function init () {
        // Make sure both WooSlider and WooCommerce are active.
        $active_plugins = apply_filters( 'active_plugins', get_option('active_plugins' ) );
        if ( ! in_array( 'wooslider/wooslider.php', $active_plugins ) ) return;
    } // End init()
} // End Class
?>

The above code creates a new WordPress plugin, declares a PHP class (you could just create normal PHP functions as well, if you prefer) and adds an action on “plugins_loaded” to run the “init()” method inside our custom class. NOTE: If creating multiple plugins for multiple custom slideshow types, the class name must be unique per plugin.

Adding our slideshow type to WooSlider ↑ Back to top

WooSlider exposes a “wooslider_slider_types” filter, passing to it an array of existing slider types. Each slider type contains the following information: key: The array key is the key to identify this slider type. name: The label by which we’ll identify the slider type. callback: The function used to generate the content for the slides. Carrying on with our above example, we’ll need to add a filter on “wooslider_slider_types”. To do this, we’ll add the following line to our “init()” method:

// Add the slideshow type into WooSlider.
add_filter( 'wooslider_slider_types', array( 'My_Custom_Slideshow', 'add_slideshow_type' ) );

This refers to a new method, “add_slideshow_type()”, which we need to add to our class. This method would look as follows:

/**
 * Integrate the slideshow type into WooSlider.
 * @since  1.0.0
 * @param  array $types Existing slideshow types.
 * @return array $types Modified array of types.
 */
public function add_slideshow_type ( $types ) {
    if ( is_array( $types ) ) {
        // Make sure to add an array, at our desired key, consisting of a "name" and the "callback" function to get the slides for this slideshow type.
        $types['my-custom-slideshow'] = array( 'name' => __( 'My Custom Slideshow Type', 'my-custom-slideshow' ), 'callback' => array( 'My_Custom_Slideshow', 'get_slides' ) );
    }
    return $types;
} // End add_slideshow_type()

As can be seen above, the “callback” parameter has been set to be the “get_slides()” method inside our new PHP class. We’ll need to add that method to our class.

/**
 * Get the slides for this slideshow type.
 * @since  1.0.0
 * @param  array  $args Arguments from the shortcode.
 * @return array        An array of slides to display in the slideshow.
 */
public function get_slides ( $args = array() ) {
    $slides = array();

    // Setup default arguments for this slideshow type.
    $defaults = array( 
                    'display_as_titles' => 'false'
                    );

    $args = wp_parse_args( $args, $defaults );

    $slides[] = array( 'content' => 'This is slide 01.' );
    $slides[] = array( 'content' => 'This is slide 02.' );
    $slides[] = array( 'content' => 'This is slide 03.' );
    $slides[] = array( 'content' => 'This is slide 04.' );

    // A bit of custom code to convert our text to headings, based on the arguments.
    if ( 'true' == $args['display_titles'] ) {
    foreach ( $slides as $k => $v ) {
    $slides[$k]['content'] = '<h2>' . $v . '</h2>';
}    }

    return $slides;
} // End get_slides()

In the above method, we’re using an example argument. This information will be passed through using our conditional popup fields. Lets add those.

Conditional fields ↑ Back to top

Conditional fields are made up of two parts- adding support for the fields, and displaying the fields in the shortcode generator, widget, etc. To add support for our new field, we’ll add the following line to our “init()” method:

// Add support for the type-specific fields when generating the WooSlider shortcode.
add_filter( 'wooslider_popup_settings', array( 'My_Custom_Slideshow', 'add_popup_fields' ) );

We’ll then need to add the “add_popup_fields()” method to our PHP class as well, which would be:

/**
 * Add support for our slideshow-specific fields when generating the shortcode.
 * @since  1.0.0
 * @param  array $fields Array of supported settings.
 * @return array Modified supported settings array.
 */
public function add_popup_fields ( $fields ) {
    if ( is_array( $fields ) ) {
        // Add a new key to the array of supported fields when generating the shortcode, with the value being set to the default value or an empty string.
        $fields['display_as_titles'] = '';
    }
    return $fields;
} // End add_popup_fields()

Now that WooSlider knows we’ve got this field available, we need to generate the HTML to work with this field. In this case, we’ll be using two new methods. Firstly, we need to let WordPress know that we’re looking to display the fields. To do this, we add some code to our “init()” method:

// Add the slideshow type's fields into the WooSlider popup.
add_action( 'wooslider_popup_conditional_fields', array( 'My_Custom_Slideshow', 'display_fields' ) );

This then refers to our “display_fields()” method, which we’d need to add to our PHP class.

/**
     * Display conditional fields for this slideshow type, when generating the shortcode.
     * @since  1.0.0
     * @return  void
     */
    public function display_fields () {
        global $wooslider;

        // Get an array of the fields, and their settings, to be generated in the popup form for conditional fields for this slideshow type.
        $fields = self::get_fields();

        // Make sure that the DIV tag below has a CSS class of "conditional-slideshowtype", where "slideshowtype" is our newly added type.
    ?>
    <div class="conditional conditional-my-custom-slideshow">
    <table class="form-table">
        <tbody>
    <?php foreach ( $fields as $k => $v ) { ?>
            <tr valign="top">
                <th scope="row"><?php echo $v['name']; ?></th>
                <td>
                    <?php
                        // Use WooSlider's admin object to generate the desired field according to it's type.
                        $wooslider->admin->generate_field_by_type( $v['type'], $v['args'] );
                    ?>
                    <?php if ( $v['description'] != '' ) { ?><p><span class="description"><?php echo $v['description']; ?></span></p><?php } ?>
                </td>
            </tr>
    <?php } ?>
        </tbody>
    </table>
    </div><!--/.conditional-->
    <?php
    } // End display_fields()

Important areas to note in the “display_fields()” method are the “conditional-my-custom-slideshow” CSS class. This uses the convention of “conditional-slideshowtype”, where “slideshowtype” is the key we used when adding our slideshow type to WooSlider. Another aspect to note here is that we’re using WooSlider’s field generator to create the fields. This requires the field data to be presented in a specific format, which we’ve done in our “get_fields()” method. We’d need to add this method to the PHP class now as well.

/**
 * Generate an array of the data to be used to generate the fields for display in the WooSlider admin.
 * @since  1.0.0
 * @return array Field data.
 */
private function get_fields () {
    $fields = array();

    $display_as_titles_args = array( 'key' => 'display_as_titles', 'data' => array() );

    $fields['display_as_titles'] = array( 'name' => __( 'Display text as titles', 'my-custom-slideshow' ), 'type' => 'checkbox', 'args' => $display_as_titles_args, 'description' => __( 'Display text as titles', 'my-custom-slideshow' ) );

    return $fields;
} // End get_fields()

What’s important to note in the above snippet are the various paramters we require for each field. The tier looks like this field each field:

array key -> name
  -> type (checkbox, text, select, images, range, textarea)
  -> args
  -> key
  -> data array (this would contain things such as options for "select" fields (as an array with a key of "options"))
  -> description

In this case, we have only a single field, so we only need to add one field for display.

Piecing it all together ↑ Back to top

We’ve jumped around a bit between adding new methods to our PHP class, adding items to our “init()” method and creating the plugin’s structure. As a completed code base, the plugin looks as follows:

<?php
/*
Plugin Name: WooSlider - My Custom Slideshow
Plugin URI: http://your-plugin-website.com/
Description: This is my custom WooSlider slideshow.
Version: 1.0.0
Author: Your Name Here
Author URI: http://your-website.com/
License: GPL version 2 or later - http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/

add_action( 'plugins_loaded', array( 'My_Custom_Slideshow', 'init' ), 0 );

class My_Custom_Slideshow {
     /**
     * Initialize the plugin, check the environment and make sure we can act.
     * @since  1.0.0
     * @return  void
     */
    public function init () {
        // Make sure both WooSlider and WooCommerce are active.
        $active_plugins = apply_filters( 'active_plugins', get_option('active_plugins' ) );
        if ( ! in_array( 'wooslider/wooslider.php', $active_plugins ) ) return;

        // Add the slideshow type into WooSlider.
        add_filter( 'wooslider_slider_types', array( 'My_Custom_Slideshow', 'add_slideshow_type' ) );

        // Add support for the type-specific fields when generating the WooSlider shortcode.
        add_filter( 'wooslider_popup_settings', array( 'My_Custom_Slideshow', 'add_popup_fields' ) );

        // Add the slideshow type's fields into the WooSlider popup.
        add_action( 'wooslider_popup_conditional_fields', array( 'My_Custom_Slideshow', 'display_fields' ) );
    } // End init()

    /**
     * Integrate the slideshow type into WooSlider.
     * @since  1.0.0
     * @param  array $types Existing slideshow types.
     * @return array $types Modified array of types.
     */
    public function add_slideshow_type ( $types ) {
        if ( is_array( $types ) ) {
            // Make sure to add an array, at our desired key, consisting of a "name" and the "callback" function to get the slides for this slideshow type.
            $types['my-custom-slideshow'] = array( 'name' => __( 'My Custom Slideshow Type', 'my-custom-slideshow' ), 'callback' => array( 'My_Custom_Slideshow', 'get_slides' ) );
        }
        return $types;
    } // End add_slideshow_type()

    /**
     * Add support for our slideshow-specific fields when generating the shortcode.
     * @since  1.0.0
     * @param  array $fields Array of supported settings.
     * @return array Modified supported settings array.
     */
    public function add_popup_fields ( $fields ) {
        if ( is_array( $fields ) ) {
            // Add a new key to the array of supported fields when generating the shortcode, with the value being set to the default value or an empty string.
            $fields['display_as_titles'] = '';
        }
        return $fields;
    } // End add_popup_fields()

    /**
     * Display conditional fields for this slideshow type, when generating the shortcode.
     * @since  1.0.0
     * @return  void
     */
    public function display_fields () {
        global $wooslider;

        // Get an array of the fields, and their settings, to be generated in the popup form for conditional fields for this slideshow type.
        $fields = self::get_fields();

        // Make sure that the DIV tag below has a CSS class of "conditional-slideshowtype", where "slideshowtype" is our newly added type.
    ?>
    <div class="conditional conditional-my-custom-slideshow">
    <table class="form-table">
        <tbody>
    <?php foreach ( $fields as $k => $v ) { ?>
            <tr valign="top">
                <th scope="row"><?php echo $v['name']; ?></th>
                <td>
                    <?php
                        // Use WooSlider's admin object to generate the desired field according to it's type.
                        $wooslider->admin->generate_field_by_type( $v['type'], $v['args'] );
                    ?>
                    <?php if ( $v['description'] != '' ) { ?><p><span class="description"><?php echo $v['description']; ?></span></p><?php } ?>
                </td>
            </tr>
    <?php } ?>
        </tbody>
    </table>
    </div><!--/.conditional-->
    <?php
    } // End display_fields()

    /**
     * Generate an array of the data to be used to generate the fields for display in the WooSlider admin.
     * @since  1.0.0
     * @return array Field data.
     */
    private function get_fields () {
        $fields = array();

        $display_as_titles_args = array( 'key' => 'display_as_titles', 'data' => array() );

        $fields['display_as_titles'] = array( 'name' => __( 'Display text as titles', 'my-custom-slideshow' ), 'type' => 'checkbox', 'args' => $display_as_titles_args, 'description' => __( 'Display text as titles', 'my-custom-slideshow' ) );

        return $fields;
    } // End get_fields()

    /**
     * Get the slides for this slideshow type.
     * @since  1.0.0
     * @param  array  $args Arguments from the shortcode.
     * @return array        An array of slides to display in the slideshow.
     */
    public function get_slides ( $args = array() ) {
        $slides = array();

        // Setup default arguments for this slideshow type.
        $defaults = array(
                        'display_as_titles' => 'false'
                        );

        $args = wp_parse_args( $args, $defaults );

        $slides[] = array( 'content' => 'This is slide 01.' );
        $slides[] = array( 'content' => 'This is slide 02.' );
        $slides[] = array( 'content' => 'This is slide 03.' );
        $slides[] = array( 'content' => 'This is slide 04.' );

        // A bit of custom code to convert our text to headings, based on the arguments.
        if ( 'true' == $args['display_titles'] ) {
            foreach ( $slides as $k => $v ) {
                $slides[$k]['content'] = '<h2>' . $v . '</h2>';
            }
        }

        return $slides;
    } // End get_slides()
} // End Class
?>

 

Having trouble viewing this code? View the same code in a GitHub Gist here.

 

Place the above code in a new file in your “wp-content/plugins” folder called “my-custom-slideshow.php” (the name isn’t important, but it’s a good idea to keep it easy to remember). You should now see your new plugin listed on the “Plugins” screen within your WordPress admin. We hope you’ve enjoyed working through this tutorial. We look forward to seeing the slideshows you can produce with WooSlider.

WooCommerce - the most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment