FrontPage Slideshow Plug-In For WordPress

JoomlaWorks’ Frontpage Slideshow is one of the best commercial “featured post” slideshows currently available. Its designed to show your featured posts in an eye-catching and professional manner and is used by many high-profile websites.

Not unexpectedly, it’s been designed to work with Joomla!, which claims to be one of the most popular open-source CMSs on the planet (along with Drupal). Strictly speaking, WordPress is a blogging platform, not a Content Management System. In fact, JoomlaWorks cheerfully lumps WP under “any PHP based site”.

If you buy Frontpage Slideshow (FPSS) believing in JoomlaWorks’ support for “any PHP based site”, you’ll find that it involves running FPSS in “static” mode. This means that all the data to be displayed resides in a fixed file which you have to manually create; it doesn’t pull any posts from WordPress, hence making it useless for us WordPress users (who number in the tens of millions).

Rather than accept I wasted €22, I built a plug-in so that FPSS would work with WordPress. It exposes all the FPSS properties along with a few WordPress-specific options, and generates the list of featured articles based on settings, or runtime parameters.

NOTE:
1.The following information assumes you’ve purchased Frontpage Slideshow and have read the documentation that comes with it.
2. The plug-in has been designed for theme integration, not end-user integration into posts or pages.

Installation

1. After purchasing, downloading and unzipping the FPSS package, locate the “fpss” directory under the “Static PHP Version folder”. fpss is inside a file currently called “frontpageslideshow-v1.7.2_static.zip” which you’ll need to unzip.
2. Ignoring the instructions, upload “fpss” and all its contents to your WordPress plug-ins directory. Strictly speaking, you don’t need to upload the “slideshows” directory, but it won’t hurt anything.
3. Download wp_fpslideshow.zip (link below), unzip it, then upload the single wp_fpslideshow.php file to the fpss directory created above.
4. Log into WordPress as Admin, go to the Plugins menu and activate “Front Page Slideshow”.

The plug-in will create an additional table in your WordPress database called “fpss_slideshows” and create some default settings in the options table in a field called “fpss_settings”.

Configuration

There are two lots of configuration settings – Global settings which affects the operation of the slideshow on your site, and individual Slideshow settings.

All configuration is done on the “FPSS Slideshows” page which is listed under the Settings admin menu.

Global Settings

Library
FPSS can use either the ubiquitous jquery java library, or the mootools library for rendering. Mootools provides for a nice text transition affect but has known interactions with other libraries which will prevent it from working (most notably with jquery itself).

NB: If you select jquery, the in-built WordPress version will be used, not the one that comes with FPSS.

JS Insertion on..
You can limit which pages the library will be included with to suit your usage of FPSS. If it will only be used on the front page, that’s the only page you need to load the library on.

Slideshows

A “slideshow” defines the look of a single slideshow as it appears on screen and reflects the content of the fpss configuration.php file. Read that file (eg the one in demoslideshow) for a full explanation of all the options. Only the WordPress-specific options are explained below. There is no limit to the number of slideshows that can be created.

Create a Slideshow

Enter a name for the slideshow, eg “Frontpage”, in the Create Slideshow area at the bottom of the page and click Create Template. The slideshow will be created and displayed for editing with some default values. The WordPress-specific options are shown in the top portion of the page.

WordPress Options

Output Template
Select the template to be used. You can see them all in action on the Frontpage Slideshow site.

Slideshow Post Category
The default category used to retrieve posts from. This can be over-ridden at runtime (depending on the next option) and is therefore optional.

Enforce Post Category
If set, this will force an AND query to include posts that are in the category set above as well as the category passed at runtime. If not set, a category passed at runtime will over-ride Slideshow Post Category. See below for an example of usage.

Number of Posts in Slideshow
Self explanatory, and can also be over-ridden at runtime. By default it returns the most recent posts, from newest to oldest.

Image Custom Field Name
The name of the custom field within each post which holds the URL of the image to be used in the slideshow.
NB: The plug-in processes shortcodes within the image custom field to allow for shortcodes that modify or set the URL at runtime.

Tagline Custom Field Name
The name of the custom field within each post which holds the tagline. Taglines are similar to excerpts, but don’t generally allow as much text. Not all templates use taglines in the same way.

Tagline is post meta
The plug-in can generate post meta which includes the date/time of the post and the number of comments. The meta can be changed to suit your requirements. If this option is set, the meta will be used as the Tagline.

Category is post meta
Similar to above; for templates that display a “category”, when this option is set, the post meta will be used.

Category Parent for Display
If you wish to use the post categories as the “Category” (ie, the option above is OFF), this option allows you to limit which categories will be listed. Only the post categories that are sub-children of this one will be displayed. Leave blank to display ALL the post categories.

Because of the way different templates use and display text, you may need to experiment with these settings to get the desired result.

The next group of options are the fpss settings found in configuration.php. Pay particular note of the Width and Sidebar Width options. For templates with sidebars, the total width of the slideshow is Width + Sidebar Width. For templates without sidebars, the total width of the slideshow is Width.

Some options specific to the Mootools library are only shown when the Mootools library is in use.

Integrating Frontpage Slideshow

As mentioned above, the plug-in is designed to be used within a theme. It exports a single function:
fpss_slideshow($templatename, $catid, $catname, $numposts, $postquery, $echo)
Only the templatename parameter is required, all the rest are optional.

templatename
The name of the slideshow template created as described above. Required.

catid
The ID of the category from which to pull posts. If not passed, it will use the category set in the slideshow editor. If no category is set in the template or at runtime, ALL posts will be used.

catname
Allows a category to be specified by name. If not passed, it will use the category set in the slideshow editor. If no category is set in the template or at runtime, ALL posts will be used.

NB: if you pass both a category ID and a category name, BOTH will be used and only posts that appear in both will be displayed. If a category is set in the template and Enforced, posts must also be in that category.

numposts
The number of posts to be used in the slideshow. Defaults to the number specified in the slideshow editor.

postquery
Allows a custom query to be passed directly to the slideshow for use with WP_Query to return the required posts. This over-rides ALL other options.

echo
Set to false to return the slideshow code as a string and not display it on the screen. When true (the default), fpss_slideshow() returns an array holding the IDs of all the posts displayed in the slideshow.

PHP Usage

To insert the slideshow at the required place in your theme, simply call a statement such as the following (using the required slideshow name): <?php fpss_slideshow('Frontpage'); ?>. The plug-in will output all the code to display the slideshow. If there are no posts in the slideshow, nothing is output.

In normal echoing mode, fpss_slideshow() returns an array holding the IDs of all the posts displayed in the slideshow. This can be used to determine if no posts were displayed so that alternate content can be shown or to prevent the same posts from being displayed on the same page. Here’s a standard way of displaying the slideshow and then modifying the loop to prevent the same posts from being listed:

global $wp_query;

//output the slideshow
$ids = fpss_slideshow('Homepage'); 

//don't show slideshow posts again
query_posts(array_merge(array('post__not_in' => $ids), $wp_query->query));

if (have_posts()) : while (have_posts()) : the_post();
..etc..

This technique is far more efficient than modifying the loop to not show posts in your “featured” category (or whatever you’re using). The plug-in also records the ID of all the displayed posts in the commonly used global $do_not_duplicate array for the same purpose.

Styling the Slideshow

Frontpage Slideshow uses a non-standard technique to dynamically load a stylesheet at runtime. The stylesheet is located in the same directory as the relevant template (eg, Default, FSD, JJ-Orbs, etc) and called template_css.php. Customisations to suit the site theme should be made to this file.

Integrating the FPSS Stylesheet (V1.1)

For improved site performance, the frontpage CSS can be incorporated into your main style sheet (ie style.css). To do this, style the appropriate stylesheet as described above, then copy its entire contents (excluding PHP commands) into style.css.

In the copied CSS code, replace all occurrences of $width, $sidebar_width and $height with the values you’re using. All PHP statements must be replaced with text, so you’ll need to replace statements such as width:<?php echo $width+$sidebar_width; ?>px; with their direct values, eg “width:500px;”.

An even easier way to achieve this is to find the line in the source code of a working FPSS page that starts with “var embedFPSSCSS =” and open the url after “@import” in the browser. Copy the entire contents into style.css, no modification required.

Under the FPSS Global settings check “Don’t Include CSS” to prevent the frontpage CSS from being linked in and then check the slideshow displays correctly (you’ll need to Ctrl-F5 or similar).

While the additional styling may significantly increase the size of the plain text style.css file, in a normal server environment with compression, the time difference to download it is insignificant. The real improvement to response times across your site comes with eliminating the additional request to the server.

Caching (V1.2)

To dramatically improve performance, the plug-in supports caching of individual slideshows by storing the entire FPSS output code in a file, thus eliminating expensive database queries each time the slideshow is displayed.

To enable caching, check “Cache if possible” under the FPSS Global settings and save. The plug-in will attempt to create a “cache” directory in the FPSS folder and give you a message if successful (or not). In many server environments it will fail and you’ll need to create this directory manually via FTP and set its permissions to allow read/write access to everyone (ie 0777).

When the directory exists, setup will report that the cache is available, display the full file system path to it and automatically cache all the current slideshows. At this point, calls to fpss_slideshow('templatename') will be served near instantaneously from the cache without running any post queries.

NB: slideshows that are customized at runtime by passing additional parameters to fpss_slideshow() are not cached.

The plug-in will automatically re-build a slideshow cache if a new post is published that is to appear in that slideshow, a post within the slideshow is edited or deleted, or if comments are made on a post in the slideshow.

Non-Standard Uses for Frontpage Slideshow Within WordPress

It’s not necessary to create a slideshow for each slideshow required. For instance, if a custom category archive page template is to display a slideshow for featured posts within the category, followed by all the posts within that category, create a “Category” slideshow to define the look, set the Slideshow post category to “Featured”, Enforce the category, and then pass the required category ID within the template. Eg:

<?php fpss_slideshow('Category', $cat); ?>
This relies on the global variable $cat that WordPress sets to the ID of the category being displayed.

This will display the slideshow with posts that are within both the Featured category and the category being listed. You can combine this with the code shown above to subsequently prevent the same posts from being displayed on the page.

NB: when echoing, the plug-in outputs nothing if there are no posts to display. Therefore, you can safely use the example above and not risk an empty slideshow box on the screen. Testing the output of fpss_slideshow() for an empty array allows you to display alternate content instead, if necessary.

Download wp_fpslideshow.zip V1.2

Update Jun 2010: V1.2 – Caching; Enforce category; option info
Update Dec 2009: V1.1 – Option to not include CSS

This plug-in has been tested on WordPress version 2.8 and up.

Page updated 18 June 2010