Add custom slider

Function Reference: themeblvd_add_slider

Create a custom slider type to be used within the framework when a WordPress user creates a new slider.

Usage
themeblvd_add_slider( $slider_id, $slider_name, $slide_types, $media_positions, $slide_elements, $options, $function_to_display );
Parameters

[param id="slider_id" type="string" required="true" description="ID for the new slider type." default=""]

[param id="slider_name" type="string" required="true" description="Name for the new slider type." default=""]

[param id=”slide_types” type=”array” required=”true” description=”Types of slides the user can choose from when using this slider – image, video, and custom. Ex: array( 'image', 'video', 'custom' )” default=””]

[param id=”media_positions” type=”array” required=”true” description=”Ways user can align the image or video within the slides – full, align-left, and align-right – and their corresponding crop sizes. The crop sizes are only for reference in the Slider Manager so the end-user knows what size their images need to be. The actual crop sizes used will ultimately be determined by what you do in your callback function. Ex: array( 'full' => 'crop_size', 'align-left' => 'crop_size', 'align-right' => 'crop_size' ) — crop sizes could also be left as blank values in the array for them to not show to the end-user.” default=””]

[param id=”slide_elements” type=”string” required=”true” description=”The elements that can be selected when editing a slide – image-link, headline, description, and button. Ex: array( 'image_link', 'headline', 'description', 'button' )” default=””]

[param id="options" type="array" required="true" description="Array of options to include for the entire slider." default=""]

[param id=”function_to_display” type=”callback” required=”true” description=”The name of the function to actually display the slider on the frontend of the website. Usage Ex: function my_callback( $slider, $settings, $slides ) { ... }” default=””]

Examples

This all could get much more complicated if we were actually creating a new slider type that requires us to incorporate a new jQuery plugin or something similar to that. However, let’s just keep this example simple to demonstrate how this function works.

Let’s say our client requires making sliders that just contains videos. In this case, maybe it’ll be a little confusing to try and explain to them how sliders work with image slides vs videos slides, how they can stage the video left/right/full width, etc. So, we’ll just create a simple slider that just asks them to input a video URL into each one of their slides.

First, we need to create the slider type that the user will be able to select from. We’ll call it “Simple Video Slider”.

We’ll give it a few basic options like one to choose the slide transition and another two to input the text for some “Next Video” and “Previous Video” buttons. Finally, we’ll display on the frontend with the callback function, display_simple_video_slider that we’ll also need to setup our HTML markup and javascript, which we’ll just place inline with the HTML markup.

// Slide types - Video only
$slide_types = array( 'video' );

// Media positions - Full Width only, and because we're not using images, we'll leave crop size blank.
$media_positions = array( 'full' => '' );

// Slide elements - none
$slide_elements = array();

// Options
$options = array(
	array(
		'id'		=> 'fx',
		'name'		=> 'How to transition between slides?',
		'std'		=> 'fade',
		'type'		=> 'select',
		'options'	=> array(
			'fade' 	=> 'Fade',
			'slide'	=> 'Slide'
		)
	),
	array(
		'id'		=> 'prev',
		'name' 		=> 'Text for "Previous" Button',
		'std'		=> 'Previous Video',
		'type'		=> 'text'
	),
	array(
		'id'		=> 'next',
		'name' 		=> 'Text for "Next" Button',
		'std'		=> 'Next Video',
		'type'		=> 'text'
	)
);

// Add Slider type
themeblvd_add_slider( 'simple_video_slider', 'Simple Video Slider', $slide_types, $media_positions, $slide_elements, $options, 'display_simple_video_slider' );

After using the above code, we’ll have something like this for the user in the slider manager.

Now that we’ve setup the slider manager for the user and they can create a slider, we need to create an actual function to display the slider on the frontend of the website. In our code above we used “display_simple_video_slider” as the $callback parameter and so that’s what we’ll need to name our function.

In our function, we’re going to use the items saved from the slider manager to setup a slider with the FlexSlider plugin, which is already included in the theme; so we don’t need to incorporate any other javascript files for this slider to work.

In this function, we’re going to pass in the three required parameters we have to work with.

  • $slider – Unique ID that the user has assigned to the slider.
  • $settings – Array of the settings the user has saved based on the options we’ve added to the slider.
  • $slides – Array of all the slides of the slider.

To understand how $settings and $slides are setup, you should print out their values while developing your function so you can see how they’re setup with print_r(). In this case if we start out our function like this:


// Display slider
function display_simple_video_slider( $slider, $settings, $slides  ) {
	
	// For development
	echo '<pre>'; print_r($settings); echo '</pre>';
	echo '<pre>'; print_r($slides); echo '</pre>';
	
}

And now when we insert an example of this new slider type into our website, we can see something like this:

So, let’s get to it. In our function, we’re just going to basically use WordPress’s oembed system to embed the videos based on the video URL’s the user has put in. The structure of the slider and the basic javascript will just be setup how the FlexSlider documentation shows.


// Display slider
function display_simple_video_slider( $slider, $settings, $slides  ) {

	// For development
	// echo '<pre>'; print_r($settings); echo '</pre>';
	// echo '<pre>'; print_r($slides); echo '</pre>';
	
	// Enqueue Flexslider script
	wp_enqueue_script( 'flexslider' ); // will be added to wp_footer()
	?>
	<script>
	jQuery(document).ready(function($){
		$(window).load(function() {
			$("#<?php echo $slider; ?>").flexslider({
				controlNav: false,
				slideshow: false,
				animation: "<?php echo $settings['fx']; ?>",
				prevText: "<?php echo $settings['prev']; ?>",
				nextText: "<?php echo $settings['next']; ?>"
			});
		});
	});
	</script>

	<div id="<?php echo $slider; ?>" class="flexslider">
		<ul class="slides">
			<?php foreach( $slides as $slide ) : ?>
				<li><?php echo wp_oembed_get( $slide['video'] ); ?></li>
			<?php endforeach; ?>
		</ul>
	</div>
	<?php
}

When viewing the slider on the frontend of our website, we see something like this.

Here are some things to note about what we’ve done here in this function.

  • In this example, we’re just using some of the basic CSS classes already present in the theme with the FlexSlider plugin. So, that’s how we’re able to get the basic setup of a slider without putting in any custom CSS. However, most likely your slider is going to require you to also add your own custom styles to your child theme.
  • For the videos, we’ve used WordPress’s wp_oembed_get function, which automatically incorporates the framework’s responsive video features. So, in this case, our simple video slider will also be responsive.