sigplus Frequently asked questions

Looking for responsive layout? Searching for a way to insert the activation tag using a dialog box? Want more control over captions? Help us release the next major version of sigplus by evaluating sigplus 1.5.x beta and sending feedback (including bugs you find) to our This email address is being protected from spambots. You need JavaScript enabled to view it..

Below you find common problems users run into when trying to set up sigplus on their site and possible solutions to each. The list targets typical problems but unfortunately can never be complete. Should you run into a problem that needs professional help by the support team, please read our support conditions before you contact us. Even though you are welcome to post a review on sigplus in the Joomla Extensions Directory (JED), please do not use the JED review system for asking questions, such violate JED terms of use and will be ignored as the JED does not expose contact information of reviewers and thus we cannot get in touch with you. If you feel this FAQ is incomplete and have suggestions on how to improve it, we would appreciate your comments.

Selected common problems

General troubleshooting

I am using {gallery}folder{/gallery} in an article but nothing happens when I visit the page and the activation tag is displayed as typed.

First of all, make sure that you have enabled the plug-in and the inner part of the activation tag contains no HTML formatting. Either type the activation tag using the keyboard, or if you decide to copy and paste an example, make sure that it is pasted as plain text. (Not as formatted text. You can use Remove Formatting from the toolbar in the article editor to make the text plain.) If your editor supports HTML source mode, the activation tag should look as {gallery}food{/gallery} in regular as well as in source mode, and not, for example {gallery}<i>food</i>{/gallery}.

Once you have made sure that none of the above apply, please check that folder is a simple name that consists of English letters, numbers, underscores and hyphens only, or a path whose components are simple names separated with /. You are not permitted to use spaces or special characters (especially outside the range of ASCII printable characters) in folder names. Some operating systems (including Windows) do not distinguish between lowercase and uppercase letters, most operating systems do. If the name of the folder contains an uppercase letter, it should be typed with the exact same character case when referenced in an article. Examples for proper usage:

  • {gallery}myfolder/myseason/myevent{/gallery}
  • {gallery}my_images{/gallery}
  • {gallery}2010-02{/gallery}
  • {gallery}Myfolder{/gallery}

Examples for improper usage:

  • {gallery}myfolder\myseason\myevent{/gallery} (uses backslash instead of slash)
  • {gallery}My Folder{/gallery} (contains a space)
  • {gallery}2010.02{/gallery} (contains a dot)

Please note that not all contexts that accept freely-styled text are suitable for using the sigplus activation tag. Regular articles are suitable but some components may have editable rich text where the activation tag will not trigger sigplus and the tag will be displayed as-is. sigplus is a plug-in: there is a so-called dispatcher mechanism built into Joomla whereby the plug-in is fed the text of an article, makes changes and replacements, and returns the updated text. If the dispatcher mechanism is not initiated by the component, no plug-ins (including sigplus) will work. For example, to use sigplus in the description text field of a VirtueMart component:

  1. Log in to the component.
  2. Select Admin/Configuration and choose the Global tab.
  3. Under Frontend Features, check the box next to Enable content mambots / plugins in descriptions?
  4. Click Apply.

The steps to follow with VirtueMart 3.x are:

  1. Log in to the component VirtueMart.
  2. Select Configuration > Configuration and choose the tab Shop.
  3. Check the box next to Enable content plugins in descriptions.
  4. Click Save.

This will enable the dispatcher mechanism to operate on description text in VirtueMart.

An error message about folders is printed at the top of the page where I have placed the {gallery}folder{/gallery} tag.

Please check that the base folder, the preview image folder and the thumbnail folder are relative paths whose components are all simple names (i.e. consist of English letters, numbers, underscores and hyphens). The base folder is interpreted w.r.t. the Joomla root, while the preview image folder and the thumbnail folder are resolved w.r.t. the image gallery folder. The terminology for folders is clarified in the documentation.

If you do not use the Joomla cache for storing thumbnails, make sure that sigplus has sufficient permissions to create the preview image folder and the thumbnail folder within the image gallery folder.

I have purchased a template that sigplus is part of but I have a problem.

sigplus is licensed under GPL, which permits anyone to make derivatives of the extension (provided that other conditions set forth in the license are met). Nonetheless, the creator of the derivative must, in compliance with the license, make it explicit that it is a derived version and not the original. A derived version is in fact a different piece of software that may be (but not necessarily is) substantially different from the original. Besides the legal aspects (please encourage the creators to re-brand their derivative version), it is clear that the person to ask for technical support are those who created the derivative: only they can know what custom changes they have made to the extension to attain what effect. Especially if you paid for a template sigplus was part of, you are strongly encouraged to contact the developers of the template.

Solving client-side issues

No gallery is displayed at all.

Please verify that your page does not produce any JavaScript errors. In Firefox, choose Tools/Error console from the menu and check if there are any errors, in Internet Explorer, you are usually prompted an error message when you load the page. To avoid erratic page rendering, sigplus initially hides galleries and shows them only when all initialization scripts have been executed. However, if a JavaScript error is triggered, the sigplus initialization script cannot terminate successfully and the gallery will never be shown.

If there is a JavaScript error, it is usually a result of a conflict between sigplus code and another extension or the template script. sigplus tries to be as error-tolerant as possible, however, if other extensions trigger errors, it might affect sigplus and there is nothing sigplus can do. We test sigplus with a clean installation and (as seen on the demo page) it works. We do our best so that it seamlessly cooperates with third-party code but do not expect that we resolve all script conflicts you might encounter. Remember: sigplus is licensed under GPL and comes with absolutely no warranty. (The likelihood of script conflicts has been further reduced in sigplus version 1.3.0.)

Some templates are known to be very aggressively removing any script references added by extensions. Please make sure you check out Server-side problems for a solution to such problems. If there is no JavaScript error, please check out Problems with image generation.

Advanced users' notes

In terms of framework compatibility, sigplus tries to act conservatively: when using the JavaScript framework jQuery for animation and other graphical effects, it enters the so-called no conflict mode and avoids the use of the special variable name $ that jQuery shares with MooTools.

[≥ 1.3] sigplus accesses the jQuery library via the variable __jQuery__. This prevents methods added by extending jQuery from being cleared when another extension links their own version of jQuery. After another extension has loaded their own version, the variable jQuery will refer to that version but the one used by sigplus will still be accessible via __jQuery__. For this approach to work, it is important that sigplus should be the very first plug-in loaded by Joomla: you can adjust the inclusion order in the administration back-end (open Extensions/Plugins). However, if possible, avoid using multiple jQuery versions alongside one another.

[≥ 1.3] sigplus uses a lazy inclusion of jQuery: if it detects that jQuery has already been included, it checks its version number and loads its own version of jQuery only if the version number of the loaded instance is lower than the one expected by sigplus. For the lazy inclusion to work, sigplus has to included after any other plug-ins that would load jQuery, you can adjust the inclusion order in the administration back-end (open Extensions/Plugins).

[≥ 1.3] The above two points are summarized in the following table:

Recommended plug-in activation order
jQuery loaded by another plug-in Recommended position for sigplus
1.3.2 first (prevents other extension from clearing sigplus jQuery extensions)
1.4.2 last (prevents double-inclusion of jQuery)

When I click an image preview, there is no lightbox effect, the original image is shown in a new tab.

The likely cause is that there is a JavaScript error, which is usually a result of a conflict between sigplus code and another extension or the template script. The JavaScript error halts script execution and the lightbox initialization code is not run, which is the reason why there is no lightbox effect.

If there is no script error, make sure the browser is able to access style sheet files and script files it needs to display images correctly. In fact, the contents of the folders plugins/content/sigplus/css and plugins/content/sigplus/js has to be accessible from an external location, as well as all subfolders in plugins/content/sigplus/engines. Please enter source mode in your browser and check that if you click on links that relate to sigplus, you do not get HTTP status code 403 Forbidden or a similar error.

Advanced users' notes

The initialization code is responsible for binding the mouse click event to the lightbox pop-up effect. In fact, sigplus preview images are wrapped in anchor elements (HTML tag a), for which the normal behavior is to navigate to the linked page (i.e. the original image). If the binding does not succeed, this normal behavior takes effect.

I am using the lightbox engine Slimbox (or prettyPhoto, etc.) but it does not work as expected.

Lightbox engines (with the exception of boxplus) are not strictly part of sigplus in the sense that these are great external tools we have integrated into sigplus and not tools we have developed. Consequently, we do not provide support for lightbox engines (except boxplus). Experiment with the engines: we offer multiple lightbox engines to increase the likelihood that one of them will run without problems on your site. Please do not contact us to report that a given lightbox engine displays poorly with a given template or in a given browser.

The only exception to the aforementioned rule is the boxplus engine family, which has been developed specifically for use in sigplus. If you encounter browser incompatibilities with boxplus, please feel free to report them.

When the pop-up window opens, it does not cover a video (or other Flash content).

Elements on the page that contain Flash (.swf) or Java applets are always rendered on top of all other elements in the document irrespective of their stacking order (z-index). However, adding an additional wmode (window mode) parameter to the object tag that comprises the Flash solves the issue by enforcing usual rendering. (The default value for wmode is window, which is set to transparent in the code below.)

<object height="225" width="800" data="/flash/header.swf" type="application/x-shockwave-flash">
<param name="src" value="/flash/header.swf" />
<param name="wmode" value="transparent" />
</object>

After this change is made, the pop-up window will display as expected, properly overlaying the pop-up dialog over the Flash content.

The above solution is applicable when you have full control of the HTML source. If the Flash content is generated by a third-party extension (e.g. a YouTube video extension), you will most likely be able to change the window mode from window to opaque or transparent on the extension configuration page in the administration back-end. Look for a configuration parameter Window mode and if necessary, contact the developer of the third-party extension for assistance.

The lightbox or slider engine behaves in a strange way.

Please ensure that your page does not load multiple instances of the JavaScript library jQuery. jQuery is not designed to seamlessly cooperate with other instances of itself and may cause sigplus or other extensions to behave in peculiar ways. When triggered, sigplus inspects if a jQuery version of a least 1.4 is loaded and does not load its own version unless necessary. However, some extensions are known to unconditionally load jQuery even if a previous instance has been loaded, and if they are triggered after sigplus, you end up with two instances of jQuery: one included by sigplus and one by the other extension. This can be especially troublesome if multiple different versions are loaded (e.g. 1.3 and 1.4). jQuery is (mostly) backwards-compatible: it is sufficient to load the latest of the versions the extensions need.

If you use a system plug-in that loads jQuery by default, you can turn off sigplus jQuery auto-detection and automatic inclusion: on the sigplus configuration page in the administration back-end, open the Advanced parameters panel and set AJAX library source to none. From then on, sigplus will depend on the system plug-in providing the necessary jQuery version: make sure the system plug-in is enabled and uses jQuery version at least 1.4 or sigplus might break.

Images are turned to their side when displayed in the lightbox but they are shown correctly in my image viewer program.

Photos taken with a digital camera usually have two “types” of orientation. One is their storage orientation, which corresponds to how image pixels are arranged in the 2D grid, this is the same regardless of how you rotate your camera (i.e. for both portrait and landscape pictures). The other is a special metadata field (part of EXIF metadata) that tells how the direction “up” is to be understood for the image, which is of particular interest when you take a portrait picture with the camera turned sideways. Unfortunately, many browsers do not read the metadata orientation and rely only on the storage orientation. While sigplus cannot do anything about this, you can use an image processing program to align the storage orientation with whatever is set in the orientation metadata field, effectively rearranging the pixels in the 2D grid (i.e. the original image will be modified but no information will be lost). The Windows program IrfanView is great for this purpose.

I think images are arranged in the wrong order when I set orientation to horizontal/vertical.

sigplus chooses relative image order based on slider orientation. For horizontally oriented sliders (which move from left to right or vice versa), sigplus aligns images column-wise, and for vertically oriented sliders (which move from top to bottom or vice versa), sigplus aligns images row-wise. As pointed out in the documentation, the slider can not only advance by a page (i.e. replace the entire set of images seen on the page with a completely new set) but also by row/column (which of the two again depends on orientation).

When the image slider orientation is set to horizontal, which is the default for a vanilla sigplus installation, preview images are arranged on a slider page vertically (column-wise), so that when you click the button Next and the slider moves by a single column, the arrangement remains logical (the vertical bar denotes page boundary). The initial arrangement of images could be as follows:

01.jpg  04.jpg  07.jpg | 10.jpg
02.jpg  05.jpg  08.jpg | 11.jpg
03.jpg  06.jpg  09.jpg | 12.jpg

The above may move as follows when you click the button Next:

01.jpg | 04.jpg  07.jpg  10.jpg
02.jpg | 05.jpg  08.jpg  11.jpg
03.jpg | 06.jpg  09.jpg  12.jpg

In contrast, when the slider orientation is vertical, preview images are arranged horizontally (row-wise), so that when you advance within the gallery from

01.jpg  02.jpg  03.jpg
04.jpg  05.jpg  06.jpg
07.jpg  08.jpg  09.jpg
----------------------------------------
10.jpg  11.jpg  12.jpg

you get

01.jpg  02.jpg  03.jpg
----------------------------------------
04.jpg  05.jpg  06.jpg
07.jpg  08.jpg  09.jpg
10.jpg  11.jpg  12.jpg

Only part of the images in the slider is displayed, the rest is covered.

Especially if this problem manifests itself in some browsers but not in others or with one template but not others or on page load but not on page refresh, then it is likely an interoperability problem between sigplus and your template client-side scripts or styles.

This symptom typically manifests itself when a sigplus stylesheet formatting rule and a formatting rule from your template get into a conflict. Usually, the template has the CSS property height forced to the value auto on all images, which does not always work well with how the sigplus gallery layout is initialized. This is demonstrated by the following snippet from bootstrap.css:

img {
max-width:100%;
width:auto \9;
height:auto;
vertical-align:middle;
border:0;
-ms-interpolation-mode:bicubic;
}

The solution is to change the CSS rule or override it for sigplus galleries. If you have the above snippet, you could write the following instead. omitting the property height:

img {
max-width:100%;
width:auto \9;
vertical-align:middle;
border:0;
-ms-interpolation-mode:bicubic;
}

The explanation for image height being reduced lies in how the browser reports image height to sigplus. sigplus computes the width and height of the image slider when the page loads (more specifically, in a domready event handler). This is when the structure of the page as well as style information such as margin, border and padding around images becomes available to scripts. As the slider width and height depends on the width and height of images (including margin, border and padding), the slider cannot be initialized sooner than the page loads. However, under some circumstances (e.g. the images have not yet loaded), some browsers report an image with height auto to be 18px (or some small number of pixels) tall when sigplus queries the image height on initialization. If sigplus happens to be executed by the browser before the image dimensions have been calculated (something occasionally called a race condition), sigplus has no choice but to make a wrong conclusion about the image size.

Image size reported by the browser can also be incorrect if some script is executed before the sigplus initialization script and sets different values to image width and height or any of the containers that are part of the gallery. In such a case, sigplus will use these newly assigned values. This can have undesired effects. The solution is to postpone the execution of these other scripts, which are usually injected by the template, until the sigplus slider initializes. This can be accomplished by rearranging the template scripts or wrapping some template scripts in a domready event handler; the exact solution depends on the particular template.

A black rectangle covers part of the image in the lightbox.

The issue is not related to sigplus. The black box in the top left corner (or upper part of) the boxplus lightbox pop-up window, and the text Download file that may be written in it, are not generated by sigplus but a third-party component called MediaElement.js (mejs) which ships with some (popular free) templates, e.g. by Gavick or YooTheme. Unfortunately, mejs injects itself into the HTML code generated by sigplus, quite unknown to sigplus, and therefore sigplus is powerless to prevent the intrusive behavior. However, disabling mejs in the administration back-end solves the issue and causes the black box to immediately disappear.

Advanced users whose template uses Widgetkit by YooTheme might disable the Media Player part in the Widgetkit component instead of disabling the Widgetkit system plug-in.

Gallery images shown on the page are collapsed into thin lines only a few pixels wide.

Our experience is that the following CSS rule leads to the symptom of thin lines in some browsers under some circumstances:

img {
max-width: 100% !important;
}

Not all browsers or Joomla templates exhibit the issue, and particular combinations may work while others not. Removing the CSS rule above (usually from template CSS files) or overriding it for sigplus galleries solves the problem.

Layout is not responsive for the slider.

When sigplus was originally written, responsive design was not yet ubiquitous. Even while flow layout works with responsive templates, fixed layout initializes based on parameters set on the server side and does not automatically scale down images if insufficient screen space is available. If you have a responsive template, one option is to use flow layout whereas the other is to use the special prefix mobile: to provide parameter value overrides specifically for handheld devices:

{gallery cols=4 mobile:cols=2}myfolder{/gallery}

Such an activation tag using the mobile: prefix produces 4 columns on desktops and 2 columns on handheld devices. Whether the browser runs on a desktop or a handheld device is determined from the user agent string.

The image gallery displays correctly in all browsers but Internet Explorer.

Make sure your web page HTML code starts with a Document Type Definition (DTD). If an HTML document is lacking a DTD, Internet Explorer is known to render the page in quirks mode, which will cause sigplus galleries to display in unexpected ways.

Some JPEG images fail to display in Internet Explorer but they show up fine in other browsers.

JPEG files (images with extension jpg or jpeg) can be saved in a number of color space modes:

  • RGB (separate Red Green Blue channels)
  • CMYK (Cyan Magenta Yellow Black)
  • YCbCr (three channel component)
  • YCbCrK (four channel component)

Unfortunately, Internet Explorer can display images only in the RGB color space mode. Try opening the image in an image manipulation program and save it in the RGB color scheme so that it is accessible to Internet Explorer users.

The image gallery does not display correctly in IE6.

Like major websites including Google, Facebook or YouTube that have discontinued support for IE6, sigplus does not support IE6 either. IE6 is not standards-compliant, and supporting this outdated browser would require introducing a lot of legacy code into sigplus. As suggested by Microsoft, you are strongly encouraged to upgrade to a later version, sigplus fully supports the latest version, IE8.

My page with sigplus on it is failing W3C Markup Validation.

This is not a sigplus error per se, you can test demo pages on this website to verify that they pass the W3C validation service. On the other hand, the sigplus activation tag itself expands into a <div> element that is not legal inside a <p> (paragraph) element. When you type text, most Joomla editors wrap such text automatically inside a <p> element. Usually, you can choose between paragraph formats or styles Normal (which wraps text in a <p> element) and Normal [DIV] (which wraps text in a <div> element), make sure you use the latter. If these formats or styles are not available, switch into editor source mode and ensure that the activation tag is located in a context similar to what follows:

<div>{gallery}myfolder{/gallery}</div>

The following nesting, however, will produce invalid (X)HTML:

<p>{gallery}myfolder{/gallery}</p>

Problems with image generation

An error message is printed that says there are insufficient file system permissions to create a directory.

A likely cause is that the Joomla cache folder used for saving the preview images and thumbnails is not writable. If you open the tab Directory permissions in Help/System info, you should see Writable in green text next to the label Cache directory. If not, you should make the folder writable by setting permissions to 755 (or 777) on UNIX-like systems (common for hosting services) or equivalent on Windows with your File system manager or FTP client. Joomla assumes that it is able to save temporary files in this folder, it is therefore advisable to make it writable, or you might encounter problems with other extensions as well.

If you have explicitly configured sigplus not to use the Joomla cache for storing preview images and thumbnails, sigplus has to have permission to create and populate the appropriate folder inside the image gallery folder.

Instead of images, a broken link image is shown, or no gallery images are shown at all.

First of all, make sure that the activation tag is pointed to the appropriate image gallery folder (i.e. a relative path w.r.t. the image base folder). For the definition of image gallery folder and base folder, see the terminology for folders in the documentation. If a lightbox pop-up window engine is selected and the original images do show up in the pop-up window when you click the preview image placeholders, the folders are probably set in a proper manner.

Next, you might wish to check if thumbnail and preview images are generated at all. Using your File manager or FTP client, browse the contents of the folders cache/thumbs and cache/preview to see if there are any images inside. If not, sigplus image processing libraries might not have sufficient permissions to create files in these folders and you might use more lenient permissions (e.g. 777) on these two folders. Keep in mind that depending on your system configuration (e.g. on a shared server), lenient permissions might pose a security risk and are recommended only as a last resort.

If appropriate folders are used and folder permissions are set but images still do not appear, it is possible that the GD library sigplus uses to generate preview images and thumbnails does not support the image format you use. Try whether the gallery works with some standard images (such as those copied with a Joomla installation) and if it does, convert your images to a standards-compliant format with an image processing program like GIMP.

Otherwise, you might have server restrictions that prevent URLs pointed at the folders cache/thumbs and cache/preview from being accessed by the browser. In particular, some servers are configured in such a way as to return a 403 Forbidden HTTP error message when your browser attempts to access these folders or any files within. You can easily test whether this is the case by copying the link of the broken preview image directly into the browser navigation bar. If you are not displayed the preview image but taken to an error page instead, then you either have to make changes to the server configuration or disable Use cache for generated images in the sigplus configuration settings in the administrator back-end.

sigplus is called in category list view as many times as there are articles in the category, even though no gallery is actually seen

Do you use the Read more... separator in your Joomla articles? The Read more... separator lets articles be split into an introductory part and a main body part. When the Joomla dispatcher invokes content plug-ins in succession, including sigplus, it forwards the entire article content (introductory and main body part) to plug-ins in article view but only the introductory part in category list or blog view. If no sigplus activation tag is found in the introductory part when an article is shown in category view, sigplus short-circuits, and never embeds a gallery (neither HTML nor JavaScript). If you do not use Read more..., all article text becomes the introductory part. This in fact means that your page invokes sigplus as many times as there are articles in the category, only to throw away the galleries sigplus has generated. A content plug-in like sigplus cannot distinguish between whether it is shown in category list layout (only article title is shown as a link) or category blog layout (article title is shown with introductory text). Especially not using Read more... in category list layout is therefore a huge waste of processing time.

Recommended usage

When the article is shown in category blog view, use

Some introductory text

--- Read more ---

Main text

{gallery}folder{/gallery}

Here, the activation tag is not part of the introductory text, and thus sigplus will not activate when the article appears in category blog or list view but will properly activate when the article is shown in details view (with full article text).

When the article is shown in category list view only (but not category blog view), use

--- Read more ---

Main text

{gallery}folder{/gallery}

Here, there is no introductory part, and thus sigplus will not activate when the article appears in category view but will properly activate when the article is shown in details view.

An error message that reads Safe mode restricts user to read image is displayed.

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), sigplus will not be granted permission to access the image, and an error message will be issued. sigplus needs read permission in order to generate preview images; sigplus loads the image file on your server into memory, resizes it to preview image or thumbnail size and saves it to the specified generated image folder. Some possible solutions:

  1. Try uploading images using Media manager instead of FTP. Files uploaded with Media manager should have the same owner as the Joomla system as they are saved by the Joomla system itself.
  2. Switch to the GD image processing library. 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 by using your own thumbnails. Set Use cache for generated images in the back-end to No and copy your own preview images to the subfolders as specified in the back-end.

A cryptic error message is displayed about imagick, ImageMagick or MagickWand.

MagickWand might be instantiated in connection with using the ImageMagick image processing library. By default, sigplus uses the ImageMagick library if available on the system and reverts to GD otherwise. ImageMagick achieves higher performance resizing larger images than GD does, which is why sigplus favors it against GD. However, GD is more widely available, and as such, you can switch to GD if you encounter problems with ImageMagick: on the sigplus configuration page in the administration back-end, open the Advanced parameters panel and set Image library to GD (Graphics Draw).

An error message is printed that reads Insufficient memory to carry out the requested operation but the memory available is negative.

By default, sigplus performs a memory check when generating images to prevent running out of memory when resizing excessively large images that would not fit into the available memory allocated to PHP. Should a memory overrun occur, a completely blank screen would be returned, which is not informative as to the nature of the error. Instead, sigplus inspects image dimensions before loading the original image and compares it to available memory, prompting an error message if the required memory is more than available. On some systems, however, sigplus is unable to retrieve the amount of memory available. The solution is to replace the body of the function SIGPlusImageLibrary::checkMemory in plugins/content/sigplus/thumbs.php with an empty function body essentially disabling the memory check:

protected function checkMemory($imagepath) { }

Solving other server-side issues

No gallery is displayed at all and I get a message on the error console that reads __jQuery__(xxx).yyy(...) is undefined.

Aggressive templates

Some templates are known to be very aggressively removing script references added by sigplus or other extensions. For instance, when using the boxplus pop-up window and the boxplus slider engine, sigplus adds references to the files boxplus.min.js and boxplus.slider.min.js, which may be removed by an aggressive template. If you do not see these two files occurring in HTML source, they have most likely been removed by the template.

sigplus uses the standard Joomla mechanism for adding references to JavaScript files it relies on but as templates get priority over plug-ins and modules, sigplus is powerless to combat these “script-killer” templates. The solution is to make chages to the template itself. Open Extensions/Template manager in the administration back-end, choose your template from the list, and click the button Edit HTML. The following is one example (but definitely not the only way) of an aggressive removal of scripts added by extensions:

$header = $this->getHeadData();
$header['scripts'] = array();
$this->setHeadData($header);

As templates are run after all modules and content plug-ins have been activated (including sigplus), the line $header['scripts'] = array(); is essentially removing any script references that have been added to the HTML header. Commenting this code snippet should remedy the problem:

$header = $this->getHeadData();
// $header['scripts'] = array();
// $this->setHeadData($header);
Script mergers

Some templates use an aggregation mechanism to merge all JavaScript files into a single large js file. This means that script references added by various extensions (sigplus inclusive) to the page header are removed by the script merger on the server side, and a reference to a large generated file is added to the page head section instead. The upside is that only a single file is transferred over the network as opposed to a multitude of files, resulting in improved page load times. The downside is that since all scripts are put into the same execution context, a script error in a file originally added by another extension could affect sigplus even if sigplus would otherwise function perfectly. It is a good idea to try to isolate the problem and set up a test page with as few extensions as possible to see which is the culprit.

By default, sigplus uses Google's Content Delivery Network (CDN) to speed up loading the page. This means that the jQuery library various sigplus engines are built upon are fetched from Google's high-speed servers rather than your own, thereby improving the responsiveness of your site. Unfortunately, script mergers cannot recognize the approach sigplus uses to fetch jQuery and create a combined file that leads to JavaScript errors. You must select local copy for AJAX library source in the Advanced parameters section of the sigplus configuration page to avoid such errors. (If you only use engines that are built on the MooTools framework, you are unaffected by the setting of AJAX library source.)

My site outputs nothing except for an error message sigplus requires PHP version 5.1 or later.

sigplus expects PHP version 5.1 or later and will not work with PHP 4. Please check in Help/System info in the administration back-end if you have the proper PHP version. Usually, you can instruct your hosting service to use PHP 5 instead of the now outdated PHP 4 engine. Joomla is fully compatible with PHP 5 and exhibits better performance with this version. If you cannot instruct your hosting service to use PHP 5, you can download an unsupported “downgrade” version from JoomlaCode.

My images have metadata (e.g. Headline or Caption-Abstract) but sigplus fails to recognize it.

Some image manipulation programs add proprietary IPTC metadata (e.g. PhotoshopThumbnail). sigplus uses the function iptcparse to extract metadata from images. This function does not understand non-standard IPTC metadata and if it encounteres such, it cannot extract any metadata from the image file, not even those it would recognize otherwise. Image manipulation software can usually be configured in such a way as to leave out proprietary IPTC metadata extensions.

I am sure that I have GD installed, yet sigplus reports that an image processing library is not available.

First, make sure that PNG, GIF as well as JPG support is enabled for GD. If your GD installation lacks support for either of the image formats, sigplus will report that GD is not available.

Use the following scripts to make sure that functions in the GD image processing library are available and fully functional. Create a PHP script with the name checkgd1.php and upload it to the web server document root:

<?php
$im = @imagecreate(200, 100) or die ("Cannot create a new GD image.");
$background_color = imagecolorallocate($im, 240, 240, 240);
$border_color = imagecolorallocate($im, 50, 50, 50);
$text_color = imagecolorallocate($im, 233, 14, 91);
 
imagerectangle($im, 0, 0, 199, 99, $border_color);
imagestring($im, 5, 10, 40, "a simple text string", $text_color);
header("Content-type: image/png");
imagepng($im);

Next, proceed in the same manner with a file named checkgd2.php:

<?php
$im = imagecreatetruecolor(300, 200);
$black = imagecolorallocate($im, 0, 0, 0);
$lightgray = imagecolorallocate($im, 230, 230, 230);
$darkgreen = imagecolorallocate($im, 80, 140, 80);
$white = imagecolorallocate($im, 255, 255, 255);
 
imagefilledrectangle($im, 0, 0, 299, 199, $lightgray);
imagerectangle($im, 0, 0, 299, 199, $black);
imagefilledellipse($im, 150, 100, 210, 110, $white);
imagefilledellipse($im, 150, 100, 200, 100, $darkgreen);
header("Content-type: image/png");
imagepng($im);

If GD is installed properly, checkgd1.php should output the text a simple text string in front of a gray background, whereas checkgd2.php should produce an ellipse with a white outline and filled with solid green in front of a gray background.

I get the error message PHP regular expression limit reached.

Usually, this is associated with a sigplus gallery producing lengthy HTML code. A sizable article HTML code is likely with large galleries (100 or more images) because all information in labels.txt is emitted into the article text (with default configuration settings). Joomla has a built-in plug-in called System - SEF, which is enabled by default, and is responsible for URL rewriting. When the HTML code of an article gets fairly large, it causes System - SEF to fail, resulting in the server returning the above error message, or even a totally empty or corrupt page. A straightforward solution would be to turn off System - SEF, which you can do in case you are not using short and pretty-looking URLs. However, people usually make use of System - SEF such that turning it off is not an option. sigplus has multiple data population methods that determine where the information is stored that is used in constructing a gallery. The default is inline whereby all image data is stored in the document body as HTML elements a, img, div and others. Other methods, including script in HTML head or external script in cache folder, cause instructions on how to reproduce gallery content on the client computer to be put in the document head or an external JavaScript file, respectively, which are executed when the page loads. This gets around the URL rewriting scheme that operates on the page body. The downside is that galleries that use client-side programmatic gallery generation are invisible to search engines, i.e. they cannot pick up images or image caption text.

Advanced users' note: The PHP function preg_replace used extensively in System - SEF cannot handle large bodies of text.

A blank or corrupt screen is shown when I visit a page where I have placed a {gallery}folder{/gallery} tag.

This might have several causes:

  • The PHP memory limit is reached. A memory error occurs when the original images are too large to fit into the memory allocated to PHP. Either increase the memory limit in the PHP configuration or resize the images to smaller dimensions before you upload them. (Images with sizes around 600 to 800px should be sufficient for display on a website.) Alternatively, you might disable the cache folder, pregenerate the preview images and upload them yourself, in which case sigplus will use the pregenerated images from a subfolder of the image folder (preview by default).
  • The PHP regular expression limit is reached. See the FAQ entry above.

Solving issues with installation

The installer stops with an error message when I try to install sigplus the first time.

(Please do not forget that you have to use the package file of sigplus for installation. Do not unpack the .tgz or .zip file before you upload and install it.)

The most likely reason you get an error message is because the temporary folder is not writable. sigplus uses the built-in installer shipped with Joomla. When Joomla installs an extension, it extracts the contents of the plug-in package archive (file extension .tgz) into the temporary folder (usually tmp in the Joomla root) and tries to copy the files that belong to the extension to their final location based on the so-called XML manifest file that is originally in the root folder of the archive. If the decompression is unsuccessful because the temporary folder is write-protected, Joomla fails to create and subsequently locate the XML file. This error, however, is not specific to sigplus; you should get a similar error when trying to install other extensions. Please check whether folders are writable in Help/System info/Directory permissions and make changes in Site/Global configuration and/or the file system as necessary.

The Joomla installer fails when I try to install/uninstall sigplus.

If you have not configured your environment in such a way that Joomla has sufficient permissions to copy the files shipped in the sigplus distribution to their intended location, or delete them, you may be left with a partial installation. There are two cases:

  1. Joomla sees the plug-in as if it were installed even if some of its files have been removed. In this case, the plug-in is listed among the installed plug-ins but usually without version or developer information. To repair such a partial installation, you should either upgrade sigplus (i.e. install sigplus a second time using the Joomla installer) or manually copy sigplus files to their intended location. Once they are copied, sigplus will resume normal operation. Note: sigplus does not add any database tables. On installation, Joomla inserts a single database row for sigplus to store configuration settings, you find it in the table jos_plugins (the prefix may vary).
  2. The plug-in is invisible to Joomla but there are remnant files in the file system that prevent a subsequent sigplus installation. In such a case, you should manually clean any files from the system that belong to sigplus. Once all leftover files are deleted, the Joomla installer should be able to install sigplus normally.

Upon installation, the Joomla installer copies files in the plg_sigplus.tgz package to the following file system locations:

  • en-GB.plg_content_sigplus.ini is copied to administrator/language/en-GB/en-GB.plg_content_sigplus.ini
  • xx-XX.plg_content_sigplus.ini is copied to administrator/language/xx-XX/xx-XX.plg_content_sigplus.ini where xx-XX is the language identifier
  • sigplus.php is copied to plugins/content/sigplus.php
  • sigplus.xml is copied to plugins/content/sigplus.xml
  • the entire contents of the folder sigplus in plg_sigplus.tgz is copied to plugins/content/sigplus

No other files (including license.html) are copied from plg_sigplus.tgz.

Customization

I would like to use sigplus in different articles with different configurations. How?

There are multiple approaches to how this could be accomplished:

  1. Use the plug-in, change its configuration in the back-end using the Plug-in manager to have settings that are common to most articles, and use overrides in the article text to set parameters that are applicable in that particular context only. For example, if you set preview image width and height to 200 px in the back-end and then type {gallery width=100}myfolder{/gallery} in the article, width will be decreased to 100 px, while height will remain 200 px (as configured in the back-end). (This is the recommended approach.)
  2. Use the module, and set up as many modules as different configurations you need; use the Copy icon in the Module manager to replicate modules. If you would like to import a module into article text, you can use the loadposition built-in extension by typing where position is an arbitrary identifier specified for Details/Position in the module configuration page. (Note: you can type new identifiers into the drop-down list box as well as choose one from the existing ones.)

I would like to use sigplus outside of Joomla articles. Is this possible?

sigplus is a content plug-in, which are extensions automatically activated by Joomla in succession, the first enabled content plug-in being fed the raw article text as stored in the Joomla database and successive plug-ins handed the output of the previous one, and the output of the last is eventually displayed by Joomla.This should make a few points clear. Content plug-ins operate on data that originates from the database, i.e. they never act upon content outside the database, in particular, a content plug-in never processes PHP files that are part of a template, stored directly on the disk. In addition, since the content plug-ins are activated by Joomla, their activation code has an effect only when you place them in a context which Joomla recognizes as a valid plug-in context; regular Joomla articles (and text-like parts of some components) fall into this category.

Advanced users' note

If you would like to have sigplus operate on data that does not come from a database or you would like it to work in a context not recognized by Joomla as a content plug-in context, you must write your own PHP code to instantiate the sigplus plug-in class SIGPlusCore and call the method getGalleryHtml with the proper parameters. Invoking sigplus directly from PHP code is a non-standard way of accessing sigplus functionality, which does not receive the same amount of regular testing normally given to other sigplus features. As such, calling sigplus directly from PHP is not covered by regular support, and the sample code shown here is strictly meant for illustrating the concept, and may require small changes to work correctly.

Example for illustration purposes only (requires 1.3.4.10 or later in Joomla 1.5 and 1.4.2.7 or later in Joomla 1.6):

require_once JPATH_ROOT.DS.'plugins'.DS.'content'.DS.'sigplus'.DS.'core.php';
$sigplus = new SIGPlusCore();
$source = 'sigplus/birds';
$params = array(
	'layout'=>'fixed',
	'rows'=>1,
	'cols'=>3,
	'width'=>200,
	'height'=>200,
	'crop'=>true,
	'alignment'=>'center',
	'orientation'=>'horizontal',
	'navigation'=>'bottom',
	'buttons'=>true,
	'links'=>true,
	'counter'=>true,
	'overlay'=>true,
	'borderwidth'=>2,
	'borderstyle'=>'solid',
	'bordercolor'=>'000000',
	'sortcriterion'=>'filename',
	'sortorder'=>'desc',
	'slider'=>'boxplus.slider'
);
print $sigplus->getGalleryHtml($source, $params);

In the example above, sigplus looks for images in the folder /images/stories/sigplus/birds (with the default base folder for images being /images/stories in sigplus).

I do not like the overlay navigation buttons. How can I replace them?

sigplus will use the navigation arrows it finds in the folder plugins/content/sigplus/engines/boxplus/slider/css (or the folder plugins/content/sigplus/css for earlier releases < 1.3).

Overlay navigation buttons have the naming convention btnDirectionSize.png, e.g. btnRightLarge.png. If you change the height of “up” and “down” arrows or the width of “left” and “right” arrows, you might also have to update the style sheet file slider.css in the same directory.

Navigation buttons displayed above and/or below the image gallery are stored as a single sprite image pagingNav.png. Buttons first, previous, next and last are stacked one next to the other, and highlighted versions of buttons (shown when the mouse is over the button) are stacked below each regular button version. If you replace the buttons with your own versions, the style sheet file boxplus.slider.css (or slider.css for earlier releases < 1.3) has to be updated. In order to extract the appropriate image from the sprite, the style sheet file uses the background offset technique: the background of each navigation control is set to the sprite but with different position. The x-offset is a cumulative negative number reflecting the width of each button (and horizontal spacing in between) and the y-offset is zero for normal buttons, while highlighted buttons have the same x-offsets as normal buttons but with negative y-offset reflecting the button height (and vertical spacing). Enter the phrase CSS sprite generator into a search engine to get (usually free) tools to automatically generate stacked images and the corresponding style sheet entries.

The language of my site is not included in the installation package, captions display in English.

Several languages are included in the installation package of sigplus but they are installed by Joomla only if a corresponding Joomla language extension has already been installed when the sigplus installer is started. This means you must install a language extension for core Joomla before you install sigplus, or the language will not be set up for sigplus even if sigplus would support the language in question. (This works in the same way for every other Joomla extension.) In other words, you should follow the installation order:

1. Install the language extension for the desired language (e.g. de-DE). The new language will appear in the list of available languages.

2. Install (or update) sigplus. On updating, sigplus migrates existing settings but will add support for the new language.

Language-specific data are retrieved from a so-called language file whose file name looks like en-GB.plg_content_sigplus.ini and you find it in a folder whose name is like en-GB in the directory administrator/language. For instance, to make sigplus display in Dutch, create a file nl-NL.plg_content_sigplus.ini (the first two letters are the language ISO code, the next two are the country code), copy the contents of the English language file into this newly created file, translate language strings to Dutch while leaving language keys like SIGPLUS_FIRST as-is, save the file, and copy the result to administrator/language/nl-NL/nl-NL.plg_content_sigplus.ini. When you refresh the page with the image gallery, sigplus will display in Dutch. If you would like to translate front-end language strings only, you find them near the end of the language file.

All language files are assumed to be UTF-8 encoded without byte-order mark (BOM). For Windows, the editor Notepad++ has the option Convert to UTF-8 without BOM in the Format menu. Even though the default Windows Notepad also has the option to save as UTF-8 but it automatically adds the BOM, which is not desired.

[≥ 1.3] The boxplus family of products has its own localization mechanism. In order to translate language strings, you need to edit the file sigplus/engines/boxplus/lang/boxplus.lang.js and add your own language key and translations as appropriate. Usually, you will need to overwrite boxplus.lang.min.js with the boxplus.lang.js you have just edited. Changes affect the boxplus pop-up window, the boxplus slider, the boxplus overlay caption as well as the hover window. However, updating the language file for boxplus might not be your chief concern: if boxplus does not have a localization that matches your Joomla front-end language, the only difference you will see is that boxplus icons will not have tooltips.

If you would like your language file to be supported in future versions of sigplus, please consider volunteering as a language file maintainer.

Customizing appearance

I have made changes to a stylesheet file but the changes seem to have no effect.

In most cases, sigplus uses a pair of CSS stylesheet files. A stylesheet file such as boxplus.css has a pretty layout and is easy to edit but is rather verbose and contains a lot of whitespace. In contrast, a corresponding file such as boxplus.min.css is a minified file generated from boxplus.css automatically when the extension is installed (or the extension is packaged), and is a compact file with only the necessary information for visual rendering but is a nightmare to edit directly. Debug mode (i.e. Debug mode set to Yes on the sigplus configuration page in the administration back-end) uses the human-readable file such as boxplus.css, whereas normal (production) mode uses the minified file such as boxplus.min.css.

Therefore, you are advised to make changes to the original (non-minified) stylesheet file, and once you are done with changes, overwrite boxplus.min.css (or equivalent) with your updated version of boxplus.css (or equivalent). This will make changes take effect both in production and in debug mode.

How to hide the thumbnail navigation bar in the boxplus lightbox pop-up window?

Open the file

/plugins/content/sigplus/engines/boxplus/popup/css/boxplus.css

where the CSS rules of interest are

#boxplus .boxplus-viewer > .boxplus-thumbs > ul {
visibility:hidden;
}
#boxplus .boxplus-viewer > .boxplus-thumbs:hover > ul {
visibility:visible;
}

that make the thumbnail navigation bar appear when you move the mouse cursor over the thumbnail images area. Replacing both rules with the single rule

#boxplus .boxplus-viewer > .boxplus-thumbs {
display:none;
}

makes the thumbnail navigation bar (both the thumbnail images and the smaller arrows associated with them) be permanently hidden.

You might also want to read the entry I have made changes to a stylesheet file but the changes seem to have no effect.

Advanced users' note. If you want the changes to apply on mobile devices only, @media may come to your aid:

@media handheld, only screen and (max-width: 480px), only screen and (max-device-width: 480px) {
#boxplus .boxplus-thumbs { display:none; }
}

How to make the left and right navigation arrows remain permanently visible?

Normally, navigation arrows Previous and Next appear only when the mouse cursor approaches the edges of the gallery layout, they remain hidden otherwise. In order to give a more suggestive visual hint on how to navigate to the next set of images, open the stylesheet file

/plugins/content/sigplus/engines/boxplus/slider/css/boxplus.paging.css

where you find CSS rules that look as follows:

.boxplus-viewport > div.boxplus-prev.boxplus-horizontal.boxplus-large {
width:57px !important;
}
.boxplus-viewport > div.boxplus-prev.boxplus-horizontal.boxplus-large:hover {
background-image:url(btnLeftLarge.png) !important;
}

The CSS rule without :hover at the end is for the general case whereas the one with :hover is for the case when the mouse cursor is over the navigation arrow. To make that particular control permanently visible, remove the :hover pseudo-element indicator from the second rule (to make it apply generally as well). Repeat as necessary for other controls (e.g. Next or the small buttons).

You might also want to read the entry I have made changes to a stylesheet file but the changes seem to have no effect.

How to make the caption area on preview images larger or smaller?

The styling for preview image captions comes from the file

/plugins/content/sigplus/engines/boxplus/caption/css/boxplus.caption.css

where the part of interest reads as follows:

div.boxplus-imagecaption.boxplus-overlaycaption {
background-color:black !important;  /* fall-back setting, overridden for IE */
background-color:rgba(0,0,0,0.6) !important;  /* overridden for IE */
color:white !important;
height:30% !important;
bottom:0 !important;
padding:4px !important;
overflow:hidden !important;
}

To decrease the height of the caption area, for instance, update

height:30% !important;

to, say,

height:60px !important;

You might also want to read the entry I have made changes to a stylesheet file but the changes seem to have no effect.

How to make the caption area below the main image in the lightbox pop-up window larger or smaller?

The discussion below applies to the boxplus lightbox pop-up window only. Third-party lightbox pop-up window engines integrated into sigplus (e.g. Slimbox) have different CSS files and the changes to be made also differ.

The styling for the boxplus pop-up window comes from the file

/plugins/content/sigplus/engines/boxplus/popup/css/boxplus.css

where the part of interest reads as follows:

/* Image caption */
#boxplus .boxplus-bottom > .boxplus-caption {
position:relative;
margin:5px 0 0 0;
max-height:60px;
overflow:auto;
}

To increase or decrease the height of the caption area, update

max-height:60px;

to, say,

max-height:90px;

You might also want to read the entry I have made changes to a stylesheet file but the changes seem to have no effect.