showplus Frequently asked questions

Frequently asked questions

Below you find answers to questions that frequently arise as regards using showplus (mostly the earlier 1.x series, we have not yet had time to update it for the new 2.x series). If you need support to find a solution to a problem you have encountered or have further questions, please feel free to contact us. Our small projects team is glad to give assistance as needed. We typically reply to e-mails between 9:00 and 21:00 UTC both weekdays and weekends.

How to contact the support

If you decide to contact the support team directly, please

  • buy a support license;
  • include in your e-mail as many specifics as possible (in particular, a URL to the page that has showplus on it, and access to the Joomla administration area and/or FTP as necessary) to help get an immediate answer to the question;
  • include the word showplus in the e-mail subject and body;

Customization (showplus 1.x only)

How to customize the appearance of the slideshow?

The way the slideshow looks is completely determined by the CSS file slideshow.css in the directory /modules/mod_showplus/css/. Should you wish to change the appearance of certain elements (e.g. thumbnails, the main image, etc.), this is the file you should edit. Do not forget to overwrite the minified CSS file slideshow.min.css or your changes will only be visible in debug mode. For specific instructions on what parts of the CSS file(s) to edit to achieve particular changes in appearance, see Q&A sections below.

The way I suggest working is as follows. First, open Module Manager in the back-end, click the showplus module you would like to configure in the list, and switch showplus into debug mode. Debug mode is one of the very last settings on the Advanced parameters tab. Normally, showplus uses the compressed and obfuscated (minified) version of CSS files, which end in  .min.css, and ignores files of the same name that end in  .css only. The files *.min.css save network transmission bandwidth by consisting of a fewer number of bytes than their *.css counterparts, and help your site load faster. However, minified files are inconvenient to edit directly. Switching to debug mode ensures showplus uses *.css and not *.min.css.

Next, make changes to the CSS file slideshow.css in the directory /modules/mod_showplus/css/ as necessary, which will be reflected in the appearance of the slideshow after a complete page refresh in the browser. When you are satisfied with the results, simply overwrite slideshow.min.css with slideshow.css or use an on-line compression/minification service to generate slideshow.min.css from slideshow.css. Finally, switch debug mode to off in the back-end.

How do I run multiple instances of showplus in a Joomla website?

Use the button Duplicate in the Module manager in the administration back-end to make copies of modules (see Extensions » Module manager). The copies can then be configured independently of each other, in particular, they can draw images from different folders. This works for any kind of Joomla module, including showplus. For details, refer to the Joomla documentation.

How do I assign different showplus instances to different pages?

Use the panel Menu assignment in the bottom part of the showplus module configuration page. Suppose you have two copies of showplus listed in the Module manager. Specify the same template position for both showplus module instances but assign one set of menu items to one instance and another set of items to the other instance. For details on how menu assignment works, check out the Joomla documentation.

How do I slow down the Ken Burns effect?

The Ken Burns effect duration is computed with the formula (Slideshow delay + 2 * Transition duration), which means both Slideshow delay and Transition duration contribute to the final animation speed. I would suggest using a very high Slideshow delay value such as 20000 and a low Transition duration value, such as 800 (both are in milliseconds), which significantly slows down the Ken Burns effect, especially for a slideshow that has relatively large width (e.g. 800px) compared to a small height (e.g. 300px).

How do I have main images automatically resized by showplus?

This is not supported at the moment. For some transition effects (e.g. fading) where the entire image is expected to fit the slideshow window, this could be a useful addition, but for other transition effects (e.g. Ken Burns) where the images are expected to exceed the window dimensions, resizing would prevent the transition from working properly. Also, you might have fine-tuned the appearance of your images, which showplus does not intend to destroy by applying any post-processing to them using a generic image processing library. You are advised to resize your images to the desired width and height before you upload them.

How to increase the size of the area that displays image captions?

Please read the topic How to customize the appearance of the slideshow? first.

Open the file slideshow.css and look for the following section:

.showplus-captions-visible {
height: 22px;
opacity: .7;
}

In order to increase the size of the area that shows image captions, replace 22px with a larger value, e.g. 44px. Do not forget to overwrite slideshow.min.css with the new version of slideshow.css.

How to change the color of the blue and yellow border around the thumbnails? Blue and yellow just don’t match with the colors on my website.

Please read the topic How to customize the appearance of the slideshow? first.

In order to change the background color for the thumbnail the mouse pointer is over or the thumbnail currently shown in the slideshow, edit the following sections in the CSS file slideshow.css (and slideshow.min.css) as you please:

CSS rules to modify to customize the border width around the thumbnails and the spacing in between them

Technically speaking, the border around the thumbnails is realized using CSS padding and setting a CSS background color (see sections below). Reducing the padding width will reduce the width of the border.

.showplus-thumbnails > ul > li > a {
padding: 5px !important;
}

The spacing around thumbnails is controlled by the CSS margin of the list items in the list where each thumbnail is an item.

.showplus-thumbnails > ul > li > a {
margin: 5px !important;
}
CSS rule to alter to customize the appearance of the thumbnail the mouse pointer is over
.showplus-thumbnails > ul > li > a:hover {
background-color: #FF9 !important;
}
CSS rule to modify to customize the appearance of the active thumbnail whose corresponding image is shown in the slideshow
.showplus-thumbnails-active {
background-color: #9FF !important;
}
CSS rule to alter to customize the appearance of thumbnails that are neither active nor hovered
.showplus-thumbnails-inactive {
background-color: #000 !important;
}

How to change the fill color of space around images?

Please read the topic How to customize the appearance of the slideshow? first.

When an image is displayed whose width or height is smaller than the corresponding dimension of the slideshow, a background color is used to fill the empty space around the image, which defaults to black. Update the following rule in the CSS file slideshow.css (and slideshow.min.css) to customize the color:

.showplus-images span {
height:100%;
width:100%;
background:black none no-repeat center center;
}

The following example defines a shade of gray:

.showplus-images span {
height:100%;
width:100%;
background:rgb(190,190,190) none no-repeat center center;
}

How to reset the mouse pointer over the slideshow images (the “hand” cursor) to the default cursor?

Please read the topic How to customize the appearance of the slideshow? first.

Paste the following into the CSS file slideshow.css (and slideshow.min.css):

.showplus a {
cursor:default;
}

How to change the position of the controller?

Please read the topic How to customize the appearance of the slideshow? first.

In order to change where the navigation controller is displayed, open slideshow.css and find a section that looks as follows:

.showplus-controller {
background: url("[...]") no-repeat;
height: 42px;
left: 50%;
margin: -21px 0 0 -119px;
overflow: hidden;
position: absolute;
top: 50%;
width: 238px;
z-index: 10000;
}

Dots [...] indicate omission. The part you are interested in is top: 50%, choose any percentage value you like. You might also wish to change margin: -21px 0 0 -119px if you decide to position the controller to the top (margin: 0 0 0 -119px) or bottom (margin: -42px 0 0 -119px) because the percentage value for top is expressed in terms of the container height and the top of the controller, which means that without a proper negative margin, top: 100% aligns the controller below the main image. Alternatively, you might use a zero top margin (margin: 0 0 0 -119px) and top:0 or bottom:0 (without percentage sign) to align to the exact top or bottom.

How to make the controller remain visible when the mouse cursor moves away?

Please read the topic How to customize the appearance of the slideshow? first.

Normally, the controller is automatically hidden when the mouse cursor leaves its bounds. You can change this behavior by setting the same opacity (fully opaque) for both the "visible" and the "hidden" state of the controller:

.showplus-controller-hidden {
opacity: 1;
}
.showplus-controller-visible {
opacity: 1;
}

When you are done, do not forget to overwrite the file slideshow.min.css with slideshow.css or your changes will take effect in debug mode only.

General questions (showplus 1.x only)

Is showplus responsive?

Unfortunately, showplus 1.x is not responsive. (However, showplus 2.0 and later is fully responsive.) For animation effects, showplus 1.x internally uses a third-party slideshow extension called Slideshow2. This slideshow engine does not support responsive layout, and does most of the layout calculation in JavaScript, and does not re-calculate the layout when the container window size changes. The engine seems to have been abandoned by its author, and in order to make it responsive, it would need substantial changes. One the other hand, much as I have contributed to Slideshow2 to improve its robustness and visual effects, and much as I would like to make Slideshow2 responsive, it is still code I am not fully familiar with and have some difficulty updating. When showplus 1.x was born, responsive design was not yet ubiquitous. As a workaround, one could have multiple slideshows on the page and hide all but the slideshow specific to the current screen width with CSS or JavaScript, i.e. one could dynamically select between any of the fixed-size slideshows based on the device screen width.

I am looking for a way to automatically resize images so that they fit into the main window.

Since resizing could be meaningful for some transition effects (e.g. fading) where the image might be expected to fit into the main window but would go against others (e.g. Ken Burns) where images are expected to extend beyond main image dimensions so that they can be scrolled and zoomed, showplus 1.x does not do any automatic resizing of uploaded images. One particular scenario you would like to avoid is that you upload some images while the fading transition is selected, which would be promptly resized by the module but then you decide for the Ken Burns effect, which would then not function properly because it needs the image to exceed the bounds of the main window to have any discernible effect. However, resizing images can be very easily (and more efficiently) done on your own computer rather than on the server using one of the several free tools.

I want to make a feature request as to how the slideshow works.

Let me confess, I did not write 100% of showplus 1.x from scratch. showplus 1.x (mainly) comprises of stylesheets (.css files), client-side scripts (.js files) and server-side code (.php files). I compiled a major part of the stylesheets, wrote the server-side code (entirely) and made slight changes to the client-side scripts (but I definitely did not write this latter part from scratch). As such, any feature requests concerning the client-side part (what you see and interact with) should be submitted directly on the Slideshow2 project page. Even if I made any customization to the client-side scripts, they would be overwritten with future releases of Slideshow2, and each new release would involve my merging of the new code with my custom version of the code. Needless to say, this involves much work, while the developer of Slideshow2 gets all the credit (i.e. unless I get paid for this, I am not motivated). In contrast, if you can get a nice feature directly into Slideshow2, they will automatically be available to all users of showplus with an upgrade.

Troubleshooting (showplus 1.x only)

I miss some images. Is there a limit to the number of images the extension can display?

There is no prescribed limit to the number of images showplus can display. It might be worthwhile to inspect whether those missing images show up in the main image view if you let the animation go. If they do show up, the image processing libraries ImageMagick or GD might have difficulty rescaling the image, and the thumbnail image may never be generated. Try switching Image library in the back-end to some values other than the default.

Even while there is no theoretical limit, you might run into performance issues with a large number of images in a single slideshow gallery, which might impose a practical limit. For animation effects, showplus 1.x uses code from the Slideshow2 project, and Slideshow2 has no progressive load mechanism, i.e. all images must load when the page loads before the animation could start. This might come down to long delays on startup.

The slideshow does not show or it shows but does not animate.

This is a common problem and is usually caused by an aggressive template or an extension conflict. showplus 1.x references two types of files: stylesheets (.css files), which define how the slideshow is formatted (layout), and scripts (.js files), which are responsible for dynamic behavior (animation). Scripts have an initialization phase, which is triggered when the page loads. If scripts are stripped away by the template or some other extension interferes with the initialization procedure, the slideshow never gets a chance to start. Problems like these are scarcely attributable to showplus, one must look for an external cause to solve the problem. (In addition, they are not specific to showplus in any way: if you ignore them, they are likely to crop up again in another context.) This needs at least a URL to the page with the issue, and possibly administrator access (or FTP access) to the site to solve it. Telltale symptoms include:

  • errors in the browser's Error console, in particular, the message Slideshow is undefined (in Firefox, press ALT, then click Tools in the menu and select Error console; in Chrome, click the wrench icon, select Tools and JavaScript console)
  • slideshow.min.js missing from HTML source (in Firefox and Chrome, right click anywhere on the page and select View page source and look for slideshow.min.js near the top of the document)
  • slideshow.min.js is in the HTML source but when you try to visit the link you get an HTTP 404 Not found or HTTP 403 Forbidden error message

The slideshow works with the pre-installed templates but not my template.

Most likely, there is a programming error in the template. (One such example we know of are templates by Rocket Theme running the Gantry Framework.)

showplus 1.x uses a technology called conditional comments that is meant to give special instructions to legacy browsers IE 7 and IE 8 so that they can properly display a showplus slideshow. Conditional comments are a special kind of HTML comment, they are understood only by IE and ignored by all other browsers.

Some templates use a merger to concatenate all stylesheet and script files they find being referenced on a web page into a single large file, which is meant to improve the responsiveness of the site. A stylesheet tells the browser how the site should look, and a script is what is responsible for dynamic behavior on a web page such as slideshow transitions.

Unfortunately, some mergers have difficulty understanding conditional comments as (regular) comments, and try to extract data from them, leading to an incorrect final output. Typically, your page where you have a showplus slideshow would output nothing but the background color. Other pages (where you have no conditional comments) would work fine.

The solution to the merger problem is simple: either contact the template developer to fix the problem or turn off the merger on your template configuration page.

Advanced users' note

First of all, if you are a template author or have made changes to the layout of a template, make sure you have not forgotten about the following instruction, which pulls in all stylesheets and scripts added to the page header (HTML <head>) by extensions via the standard Joomla mechanism:

<jdoc:include type="head" />

Some templates use an aggregation mechanism to merge all CSS and JavaScript files into a single large .css and .js file. This means that stylesheet and script references added by various extensions (showplus inclusive) to the page header (HTML <head>) are removed by the merger on the server side, and a reference to a large generated stylesheet and script file is added to the page head section instead. The upside is that only a single stylesheet and script file is transferred over the network as opposed to a multitude of files, resulting in improved page load times. The downside is that should there be errors in how the merger code is written, they will break otherwise perfectly written extension code (e.g. showplus code). In particular, data URIs and conditional comments are two standard and 100% valid constructs showplus uses but mergers have been observed to have difficulty with. Please contact the person/company you acquired the template (or merger) from, and contact the developer of showplus only as a last resort to help you find a workaround. If you are a developer yourself, remove data URIs and conditional comments from showplus source code, the files you need to edit are as follows:

  • modules/mod_showplus/helper.php (method addHeadDeclarations)
  • modules/mod_showplus/css/slideshow.css (and slideshow.min.css, which is its equivalent, minified version)

I get the error message Insufficient file system permissions to create the folder root/cache/thumbs.

This is a Joomla misconfiguration issue and means that the operating system user account that is running Joomla/PHP does not have the necessary permissions to create the folder thumbs inside your Joomla cache folder. If the Joomla system is configured properly, extensions should be able to create subdirectories in the cache folder. The opposite may happen, for instance, if UNIX permissions on the Joomla cache folder are not set to 755 (i.e. read, write and execute access (4 + 2 + 1 = 7) for the owner; read and execute access (4 + 1 = 5) for the group; read and execute access (4 + 1 = 5) for everybody), or the permissions are set this way but the owner of the folder differs from the user account that is executing the Joomla engine (possibly a special user with very restrictive permissions). Usually, creating (or deleting and re-creating) the folder cache/thumbs manually via FTP solves the problem. In general, setplus has to be able to create the folder thumbs inside your Joomla cache folder, and files within, in order to support automatic thumbnail generation for a horizontal or vertical thumbnail navigation bar. Needless to say, if thumbnail navigation is disabled, setplus does not need write access to any folders on your server.

I get the error message The Graphics Draw (gd) or ImageMagick (imagick) image processing library has to be enabled in the PHP configuration to generate thumbnails.

By default, showplus displays a set of thumbnail images below the main image to facilitate fast navigation between non-consecutive slideshow images. Whenever you click a thumbnail image, you are immediately taken to the corresponding main image. Since these thumbnail images are generated automatically from the main images and saved in the Joomla cache folder, your server should have appropriate PHP extensions installed. GD and ImageMagick are image processing extensions designed to accomplish this task.

Consequently, the easiest way to get rid of the error message is to disable navigating with thumbnails so that these small-scale images do not need to be generated. Open the showplus module configuration panel in the Module Manager in the administration back-end, and choose disabled for the option Thumbs bar orientation.

Should you wish to use thumbnails with showplus in the future, you should act upon what the error message suggests, and enable one of these libraries in the PHP configuration (php.ini). If you have your site hosted on a remote server, you should contact the server administrator to have the GD or ImageMagick PHP extension enabled for you. This will unlock the two other options for Thumbs bar orientation. If you are managing your own server, consult the PHP manual on how to install and enable PHP extensions. If you have a simple local server like WAMP, this is usually a matter of a few clicks on the user interface.

I get an error message NoDecodeDelegateForThisImageFormat or another cryptic message that has the word magick in it.

This is not specifically a showplus error but rather an error related to ImageMagick. showplus uses one of the image processing libraries GD or ImageMagick for generating the small thumbnails displayed below or next to the main image. By default, showplus uses ImageMagick if available, with a fallback to GD if not. If you see such an error message, it is most likely that ImageMagick is not properly configured for your server. You can take any of the following options:

  1. Choose another image processing library for showplus. On the showplus module configuration page in the administration back-end, find the setting Image library among the advanced settings, and choose GD (Graphics Draw) from the drop-down list instead of default or ImageMagick.
  2. Disable thumbnails. For the configuration setting Thumbs bar orientation, choose disabled instead of horizontal or vertical. You will lose the scrollable thumbnails below or next to the main image but you will not see the error message either. If showplus does not need to generate thumbnails, it will not call either of the image processing libraries.
  3. Contact your server administrator to have ImageMagick properly configured for your website.

I get an error message that reads Safe mode restricts user to read image.

The problem is that your server is configured to run in PHP safe mode. Quoting from the PHP manual: When safe_mode is on, PHP checks to see if the owner of the current script matches the owner of the file to be operated on by a file function or its directory. In particular, this means that if the file system owner of an image (usually uploaded via FTP) in a gallery (e.g. your user account) differs from the owner of the script that constitutes the Joomla system (e.g. a special user nobody), showplus will not be granted permission to access the image, and an error message will be issued. showplus needs read permission in order to generate thumbnail images; showplus loads the image file on your server into memory, resizes it to or thumbnail size and saves it to the specified generated image folder.

Some possible solutions:

  1. Try uploading images using Joomla's own Media manager instead of FTP. Files uploaded with Media manager should have the same owner as the Joomla system as they are saved by Joomla itself.
  2. Switch to the GD image processing library (see Image library among advanced settings on the showplus configuration page in the administration back-end). The ImageMagick library (which constitutes a different executable) may not be configured to access the images in your image folder.
  3. Avoid automatic thumbnail generation (on the showplus configuration page in the administration back-end, set Thumbs bar orientation to disabled).

I use Joomla 1.5 and I see all the images for a split second when the page loads, making it look confusing. Is there a way to remove this?

Due to compatibility issues in Joomla 1.5, showplus either looks confusing or it runs into critical problems in some browsers. The main problem is that Joomla 1.5 comes with an age-old version of MooTools (even after having enabled the MooTools Upgrade as the instructions say), and this age-old version does not run seamlessly on some modern browsers, including IE 9. If you could upgrade MooTools in Joomla 1.5 manually to a more recent version, the fuzzy initialization in showplus for Joomla 1.5 could be eliminated. My choice has been to make the slideshow more robust (i.e. make it work in all major browsers) rather than pretty (i.e. make it look more attractive in those browsers where it would work fine), which is a trade-off where I as a developer had to make a choice for either.

Note that this problem is specific to Joomla 1.5. Joomla 1.7 and later do not exhibit this issue.

I use Joomla 1.5 and the slideshow does not seem to work at all even though I have just enabled the MooTools Upgrade system plug-in.

A common cause of this problem is that after you have enabled the MooTools Upgrade system plug-in, both MooTools 1.1 and MooTools 1.2 are referenced. If the MooTools Upgrade plug-in is enabled, whenever an extension requests MooTools to be included via Joomla's standard script inclusion mechanism, the plug-in includes the version 1.2 script library instead of the version 1.1 library. However, some templates ignore the standard mechanism and import their own copy of MooTools 1.1 if they do not find it in the page headers. Unfortunately, MooTools 1.1 and MooTools 1.2 cannot coexist on the same page. The following example illustrates the problem:

<script type="text/javascript" src="/plugins/system/mtupgrade/mootools.js"></script>
[...]
<script type="text/javascript" src="/modules/mod_showplus/js/slideshow.min.js"></script>
[...]
<script type="text/javascript" src="/templates/mytemplate/js/mootools.js"></script>

The first <script> tag imports MooTools 1.2 and is included using the Joomla mechanism. The second <script> tag imports the necessary javascript code required by showplus. The third tag includes another MooTools instance, this time version 1.1, and is added by the template mytemplate.

In order to solve the problem, either contact the developers of the template if they have a version compatible with MooTools 1.2 available, or manually upgrade the template to use MooTools 1.2 instead of MooTools 1.1. Either way, the second inclusion of MooTools should be removed or several extensions including showplus will break.

I use Joomla 1.5 and the slideshow does not display in IE9 even though it works perfectly in other browsers.

This is due to an incompatibility issue between the MooTools framework verison 1.2.4 integrated into Joomla (as part of the MooTools Upgrade system plug-in) and Internet Explorer 9. The MooTools team has already released a fix to address this issue but the Joomla team is yet to include MooTools 1.2.5 as part of Joomla with a patch. Until the Joomla team catches up with the most recent version of MooTools in the series 1.2.x, you can use IE8 compatibility mode in IE9 by adding the following to the <head> section of your page:

<meta http-equiv="X-UA-Compatible" content="IE=8" />

This will force IE9 to display the page as if it were an IE8 browser. Since MooTools 1.2.4 bundled with Joomla is compatible with IE8, the slideshow will display as expected.

The slideshow works in all browsers (including IE, Chrome and Safari) but not in Firefox 4.

Another symptom of this error is a message that appears in the Firebug console:

A parameter or an operation is not supported by the underlying object

The message is triggered in mootools.js line 1. This is not a showplus error per se but seems to be a timing issue as regards the domready event in the MooTools framework. The solution is simple: delay the initialization of the slideshow script until the page has entirely loaded. Change domready to load in the following line in modules/mod_showplus/helper.php (dots indicate omission):

$document->addScriptDeclaration('window.addEvent("domready", function () { ... });');

so that it reads (dots indicate omission):

$document->addScriptDeclaration('window.addEvent("load", function () { ... });');

If you are having difficulty making the replacement, feel free to contact the developer.