» bSuite Slideshow

Register the Token

A token is a string inside square brackets. It looks like this: [[token_name]] or [[token_name|options]] (options, if listed, are separated from the token by the pipe character). When bSuite encounters a registered token it replaces the content with that from a function specified when the token was registered.

Register the token by hooking the bsuite_tokens filter. Your registration function must accept the associative array of tokens ($tokens['token_name'] = ‘token_function’), add your tokens (and, perhaps remove tokens you want to unregister), then return the entire array.

add_filter('bsuite_tokens', 'bsuite_slideshow_token_register');
 
function bsuite_slideshow_token_register($tokens){
	$tokens['slideshow'] = 'bsuite_slideshow_token_replace';
	return($tokens);
}

Work the Token

We’ve registered the token, and we’ve got a post that includes the token and all its options. This token expects the following:

[[slideshow|width=500px&height=375px|http://path/to/photo/1.jpg http://path/to/photo/2.jpg]]

The following code will parse it and return the result.

function bsuite_slideshow_token_replace($args){
	list($args, $images) = explode('|', $args, 2);
	$defaults = array(
		'height' => '357px', 'width' => '100%'
	);
	$args = wp_parse_args( $args, $defaults );
 
	$images = array_filter(preg_split('/[\s|\n|\r|\t]/', trim($images)));
	if(!is_array($images)) 
		return NULL;
 
	add_action('wp_footer', 'bsuite_slideshow_footer');
	$return = $script . '<div id="slideshow" style="width: '. $args['width'] .'; height: '. $args['height'] .'; overflow: hidden;">';	
	foreach($images as $image)
		$return .= '<img src="'. $image .'" alt="slideshow image" />';
	$return .= '</div>';
	return $return;
}

Lines 19 through 23 parse the arguments passed to the function, first separating the images from the options (separated from the options by a pipe), then using wp_parse_args to parse the arguments (width=500px&height=375px).

Lines 25 through 27 split the images into an array, then exit if there are no images.

Line 29 adds an action that will include some necessary javascript code in the footer (the header action has already executed, soo…).

Lines 30 through 34 generate the content, creating the div, filling it with the imgs, and return it. The return value is inserted into the post where the token was found. The result looks like this: chasing seagulls.

The Whole Plugin

The whole plugin looks like this. If you’re actually planning to use it, be sure to replace line 39 with the location of your jQuery). Note: the JavaScript code is not mine. I believe it was offered as an example on a jQuery site, but I can no longer find the code. If it is yours, or you know whose it is, please contact me via the comments so I can properly credit you (or, I suppose, if it’s not GPL-compatible, remove it).

< ?php
/*
Plugin Name: bSuite Slideshow
Plugin URI: http://maisonbisson.com/blog/bsuite/slideshow
Description: Animates a series of photos as a slideshow (requires <a href="http://maisonbisson.com/blog/bsuite/">bSuite v.3 or greater).
Version: .01
Author: Casey Bisson
Author URI: http://maisonbisson.com/blog/
*/
 
add_filter('bsuite_tokens', 'bsuite_slideshow_token_register');
 
function bsuite_slideshow_token_register($tokens){
	$tokens['slideshow'] = 'bsuite_slideshow_token_replace';
	return($tokens);
}
 
function bsuite_slideshow_token_replace($args){
	list($args, $images) = explode('|', $args, 2);
	$defaults = array(
		'height' => '357px', 'width' => '100%'
	);
	$args = wp_parse_args( $args, $defaults );
 
	$images = array_filter(preg_split('/[\s|\n|\r|\t]/', trim($images)));
	if(!is_array($images)) 
		return NULL;
 
	add_action('wp_footer', 'bsuite_slideshow_footer');
	$return = $script . '<div id="slideshow" style="width: '. $args['width'] .'; height: '. $args['height'] .'; overflow: hidden;">';	
	foreach($images as $image)
		$return .= '<img src="'. $image .'" alt="slideshow image" />';
	$return .= '</div>';
	return $return;
}
 
function bsuite_slideshow_footer(){
?>
<script src="/blog/javascript/jquery-1.2.1.min.js" type="text/javascript"></script>
<script type="text/javascript">
$.fn.slideshow = function(options) {
	var settings = {
		timeout: '2000',
		type: 'sequence'
	}
	if(options)
		$.extend(settings, options);
 
	this.css('position', 'relative');
	var slides = this.find('img').get();
	for ( var i = 0; i < slides.length; i++ ) {
		$(slides[i]).css('zIndex', slides.length - i).css('position', 'absolute').css('top', '0').css('left', '0');
	}
	if ( settings.type == 'sequence' ) {
		setTimeout(function(){
			$.slideshow.next(slides, settings, 1, 0);
		}, settings.timeout);
	}
	else if ( settings.type == 'random' ) {
		setTimeout(function(){
			do { current = Math.floor ( Math.random ( ) * ( slides.length ) ); } while ( current == 0 )
			$.slideshow.next(slides, settings, current, 0);
		}, settings.timeout);
	}
	else {
		alert('type must either be \'sequence\' or \'random\'');
	}
};
$.slideshow = function() {}
$.slideshow.next = function (slides, settings, current, last) {
	for (var i = 0; i < slides.length; i++) {
		$(slides[i]).css('display', 'none');
	}
	$(slides[last]).css('display', 'block').css('zIndex', '0');
	$(slides[current]).css('zIndex', '1').fadeIn('slow');
 
	if ( settings.type == 'sequence' ) {
		if ( ( current + 1 ) < slides.length ) {
			current = current + 1;
			last = current - 1;
		}
		else {
			current = 0;
			last = slides.length - 1;
		}
	}
	else if ( settings.type == 'random' ) {
		last = current;
		while (	current == last ) {
			current = Math.floor ( Math.random ( ) * ( slides.length ) );
		}
	}
	else {
		alert('type must either be \'sequence\' or \'random\'');
	}
	setTimeout((function(){$.slideshow.next(slides, settings, current, last);}), settings.timeout);
}</script>
 
</script><script type="text/javascript">
	$(document).ready(function() {
		$('#slideshow').slideshow({
			timeout: 1000,
			type: 'sequence'
		});
		});
</script>
< ?php
}

Installation and Usage

This plugin is offered mostly as a proof of concept. A real slideshow plugin should offer more options and allow the user to click forward/backward and stop the show. Still, I use it in my blog. The plugin is included as part of bSuite and requires WordPress 2.3, so get those installed first.

Install and activate bSuite version 3.0 or greater
Activate bSuite Slideshow
Add the token to one (or more) of your posts like this:
[[slideshow|height=375px|http://path/to/photo/1.jpg http://path/to/photo/2.jpg]]
Use any number of images, separate their URLs with spaces or newlines
Enjoy the show

One Comment

Sinister

Posted April 4, 2008 at 2:37 am | Permalink

Hello,
can I use a plugin like this, to allow my visitors to create their own slideshow on my website. Or do you know, where I can find a script like this?

2 Trackbacks/Pingbacks

By WordPress Plugins Database » Plugin Details » bSuite Slideshow on 30 Oct 2007 at 5:24 am

[...] Visit [...]
By » bSuite 3 Released on 26 Nov 2007 at 2:54 pm

[...] with the results of a PHP function. A number of tokens are built in, but they’re extendable; bSuite Slideshow offers one example of how another plugin could leverage [...]

MaisonBisson.com