sigplus Configuration

Looking for responsive layout? Searching for a way to insert the activation tag using a dialog box? Want more control over captions? Switch to the next major version of sigplus. (sigplus 1.4.x, which is discussed on this page, is no longer actively maintained or supported.)

[≥ 1.3] Configuration

This section summarizes possible global settings and local parameter overrides for the sigplus plug-in, and module-specific parameters for the sigplus module that can be set either in the administration back-end or (for the plug-in) with inline parameters.

As with other Joomla plug-ins, global settings can be changed in the administration back-end; from the menu, choose Extensions/Plugin manager and click Content – Image gallery – sigplus in the list. Local parameters are set using name-value pairs in the activation start tag:

{gallery id=birds rows=2 cols=3 width=100 height=100 crop=1 labels=captions
         alignment=center orientation=horizontal
         buttons=0 links=0 counter=0 overlay=1}sigplus/birds{/gallery}

Likewise, in order to change module-specific settings for a sigplus module, choose Extensions/Module manager from the menu and click the module whose settings to update (the name of the module is sigplus by default).

Parameters specific to particular engine, i.e. a given lightbox, slider or captions engine implementation, can be entered in the Custom settings field in the Advanced parameters section on the extension configuration page. This applies to both the plug-in and the module version of sigplus. A typical usage is as follows:

lightbox:contextmenu=0
captions:alwaysOnTop=1

See how each parameter setting occupies a single line. For a sigplus module, the custom settings apply to the module instance. For the sigplus plug-in, the custom settings apply to all galleries (but can be overridden separately in the activation tag).

The explanation for the way entries are organized is as follows:

Parameter name in back-end
Local parameter The parameter name to use when overriding the global setting specified in the back-end locally. Applicable to plug-in only. For instance, preview image width set to 200 in the back-end is overridden with the local parameter name-value pair width=100.
Parameter type/value The rangle of possible values the parameter can take. For instance, string is a series of characters, text is unstructured text possibly with newlines, and html is unstructured text interspersed with inline HTML tags (e.g. a, strong, em, span). Move the mouse over the type name to get more information. The bracket syntax [one|two|three] indicates that the parameter accepts any one of the listed values one, two or three.
Available The sigplus release version when the parameter was introduced.
Summary Gives a short summary on what the parameter does, and lists the possible values it can take and what their effect is. This text is also shown as a tooltip in the back-end when you move the mouse over a parameter.
Details Gives further explanation and technical details on the parameter. This text is not shown in the back-end.
Example Illustrates how the local override parameter can be used in the activation tag. Applicable to plug-in only.

Parameters available in back-end

Basic parameters

Base folder (plug-in only)
Local parameter n/a
Parameter type/value string
Available ≥ 1.0.1
Summary Base directory w.r.t. which relative image gallery paths in the activation tag are interpreted. Use a path relative to the Joomla root folder. Setting the base folder to images/stories (default) and writing {gallery}sigplus/birds{/gallery} in a content item maps to the file system path root/images/stories/sigplus/birds.
Details In technical terms, the folder should comprise of POSIX fully portable filename components, or in other words, validate against the regular expression ^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$.
Language key SIGPLUS_BASE_FOLDER
Images folder (module only)
Parameter type/value string
Available ≥ 1.2.8
Summary Directory where your images are. Use a path relative to Joomla root. Setting the images folder to images/stories/birds maps to the file system path root/images/stories/sigplus/birds.
Details In technical terms, the folder should comprise of POSIX fully portable filename components, or in other words, validate against the regular expression ^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$.
Language key SIGPLUS_IMAGES_FOLDER
Example Setting the images folder to images/stories/fruit would display images from the folder root/images/stories/fruit where root is your Joomla root directory. Compare this to base folder for the plug-in where you would typically specify images/stories and then use the activation tag {gallery}fruit{/gallery} in an article to display images from the very same folder root/images/stories/fruit.
Gallery layout
Local parameter layout
Parameter type/value [fixed|flow]
Available ≥ 1.3.0 (implicitly derived for < 1.3.0)
Summary The way the image gallery is rendered. Fixed layout is a table-like environment with a set number of rows and columns, and a fixed width and height, where preview images occupy cells of a table. Flow layout renders preview images as if they were words of a text, allowing the series of images to span multiple lines if they would not fit into a single line, just as normal text breaks into lines if it is too long to fit into a single line. Flow layout is very flexible but does not permit an image slider.
Details  
Language key SIGPLUS_LAYOUT
Example {gallery layout=flow}fruit{/gallery}
Preview image count
Local parameter count
Parameter type/value integer
Available ≥ 1.1.0 (< 1.3.0 in the back-end)
Summary Number of preview images to show simultaneously on a single image gallery page.
Details

This setting is deprecated as of sigplus version 1.3.0 and cannot be used in conjunction with rows and columns.

  • If set to a positive value, as many images as specified will be displayed on a single image gallery page, and (if enabled) an image slider engine will be activated to let the user navigate to the next (and as appropriate, previous) page. For instance, if you have 12 images in a gallery and would like to show 5 preview images at a time, set count to 5 for the image slider to have three pages, the first two of which to have 5 images and the last page to have 2 images.
  • If set to zero, no image slider engine will be activated, the gallery will use flow layout, and all images in the gallery will be shown as previews.
  • If set to a negative value, only (the absolute value of) the specified number of images will be shown even if the gallery folder contains more images. Even though the user is not displayed the excess images on the web page, s/he can still use the navigation controls in the pop-up window to view these images as well. This setting (esp. with the value -1) is useful for blog layouts. (This setting is for backwards compatibility with earlier releases, you can achieve the same effect by using a positive count and setting the image slider engine to none.
Language key  
Rows
Local parameter rows
Parameter type/value integer
Available ≥ 1.2.2 (≥ 1.3.0 in the back-end)
Summary Number of rows used to display preview images. This setting has no effect when flow layout is used.
Details Setting the number of rows and columns does not affect slider orientation, which determines the direction the image slider moves. Images are ordered in the grid to take into account orientation.
Language key SIGPLUS_ROWS
Example {gallery rows=2 cols=3}fruit{/gallery}
Columns
Local parameter cols
Parameter type/value integer
Available ≥ 1.2.2 (≥ 1.3.0 in the back-end)
Summary Number of columns used to display preview images. This setting has no effect when flow layout is used.
Details See the explanation for rows.
Language key SIGPLUS_COLUMNS
Example {gallery rows=2 cols=3}fruit{/gallery}
Maximum preview image count
Local parameter maxcount
Parameter type/value integer
Available ≥ 1.3.0
Summary Maximum number of preview images to show. If set to zero, all images in the gallery will be shown as previews, possibly broken down into multiple pages. If set to a positive integer, only the specified number of preview images will be displayed, even though it is still possible to view all images when browsing the gallery inside the pop-up window.
Details  
Language key SIGPLUS_THUMB_MAXCOUNT
Example {gallery rows=2 cols=3 maxcount=5}fruit{/gallery} will show at most 5 preview images arranged in a 2-by-3 grid.
Preview image width
Local parameter width
Parameter type/value integer
Available ≥ 1.0.0
Summary Default width of preview images to generate [px].
Details width should be used in conjunction with height.
Language key SIGPLUS_THUMB_WIDTH
Preview image height
Local parameter height
Parameter type/value integer
Available ≥ 1.0.0
Summary Default height of preview images to generate [px].
Details height should be used in conjunction with width.
Language key SIGPLUS_THUMB_HEIGHT
Crop when resizing
Local parameter crop
Parameter type/value boolean
Available ≥ 1.1.8
Summary Crop overflowing dimensions when resizing to preview image size. If yes and the ratio of preview image width and height differs from that of the original image, excess parts of the original image are cropped from top and bottom or left and right (as applicable) when resizing to preview image dimensions. If no, the preview image always shows the entire image and the appropriate dimension is reduced.
Details

As an example, suppose preview image width and height is set to 100 px. With cropping on, the left and right part of an image with width 400 px and height 200 px (shown in gray) will be cut off, and the resulting center 200 px-by-200 px part (shown in blue) will be shrunk to preview image size (shown in red). With cropping off, the entire image will be used to generate the preview image such that the preview image will have dimensions 100 px and 50 px.

Cropping enabled:

 
 

Cropping disabled:

 
 
Language key SIGPLUS_THUMB_CROP
Example {gallery crop=1}fruit{/gallery} will enable cropping for the fruit gallery.
Alignment
Local parameter alignment
Parameter type/value [left|center|right|before|after|left-float|right-float|before-float|after-float|left-clear|right-clear|before-clear|after-clear]
Available ≥ 1.2.0
Summary Image gallery alignment on the page.
Details Variants that end in float allow text to wrap around the gallery, variants that end in clear do not. The options before and after use language-sensitive alignment, i.e. before automatically takes a value of left for LTR and a value of right for RTL languages, while the option after is the opposite of before. The options before and after are intended for multilingual sites (e.g. English and Hebrew). (In previous versions, before was called lang and after was called langinv.)
Language key SIGPLUS_ALIGNMENT
Example {gallery alignment=left-float}fruit{/gallery} will left-align the gallery, allowing text to wrap around.
Lightbox pop-up
Local parameter lightbox
Parameter type/value [none|boxplus|fancybox|prettyphoto|sexylightbox|slimbox|slimbox2]
Available ≥ 1.0.0
Summary Lightweight pop-up window engine to display images when a preview image is clicked.
Details

Engines that use MooTools use the version shipped with Joomla. Pop-up window options include boxplus with different themes (with jQuery), FancyBox (with jQuery), prettyPhoto with different themes (with jQuery), Sexy Lightbox 2 (with jQuery), Slimbox (with MooTools) and Slimbox2 (with jQuery). Only boxplus, prettyPhoto, Slimbox and Slimbox2 support HTML formatting in image description text; for other engines, any HTML tags will be removed.

The boxplus engine supports themes. Themes are specified with the syntax engine/theme, e.g. in order to use boxplus with the standard dark theme, type boxplus/darksquare. Currently supported themes are lightsquare, lightrounded, darksquare, darkrounded and prettyphoto. It is possible to have galleries with different boxplus themes on the same page.

[≥ 1.3.2] boxplus.facebook is available as a lightbox engine that features a Facebook Like button. Besides having a Like button in the image caption area, boxplus.facebook is identical to the standard boxplus engine in every respect. In particular, it accepts the same theme parameters. (The PHP class for boxplus.facebook inherits from the PHP class for boxplus. The JavaScript files use the decorator pattern to extend the standard boxplus pop-up window with social network integration.)

Language key SIGPLUS_LIGHTBOX
Example {gallery lightbox="boxplus/darksquare"}fruit{/gallery} will use the boxplus pop-up window dark theme to display images when a preview image is clicked.
Slideshow delay
Local parameter slideshow
Parameter type/value integer
Available ≥ 1.3.2
Summary Time each image is shown [ms] when slideshow mode is activated inside the lightbox pop-up window, or 0 to disable slideshow mode.
Details When the pop-up window displays, slideshow mode is not active by default. It can be activated with the slideshow Play control button that appears when slideshow mode is enabled, that is, this parameter has a nonzero value. When slideshow mode is disabled, the Play control button is not shown.
Language key SIGPLUS_LIGHTBOX_SLIDESHOW
Example {gallery slideshow=4000}fruit{/gallery} will make a slideshow control button appear in the pop-up window; pressing the button will trigger a slideshow, automatically showing the next image after 4 seconds of delay.
Image slider
Local parameter slider
Parameter type/value [none|boxplus.slider|boxplus.carousel|boxplus.transition]
Available ≥ 1.1.0
Summary Image slider engine to use. This setting is ignored if flow layout is used to render the gallery.
Details sigplus version 1.2.x supported a built-in image slider with a MooTools and a jQuery implementation. These are now obsoleted by the boxplus slider implementation. The boxplus slider supports row, column and table layout, arranges images in a grid with fixed cell size, and slides by a page at a time. The boxplus carousel supports row and column layouts, can accommodate images of differing sizes, and slides a single image at a time. The boxplus transition effect shows only a single image at a time and instead of sliding it uses configurable transitions (e.g. fading bars, dropping bars, shutter).
Language key SIGPLUS_SLIDER
Example {gallery slider=boxplus.slider}fruit{/gallery} will use boxplus' slider implementation.
Image slider orientation
Local parameter orientation
Parameter type/value [horizontal|vertical]
Available ≥ 1.2.0
Summary Orientation of the image slider viewport. Horizontally oriented sliders move from the right to the left, vertically oriented sliders move from downwards to upwards.
Details  
Language key SIGPLUS_SLIDER_ORIENTATION
Example {gallery orientation=vertical}fruit{/gallery}
Navigation bar
Local parameter navigation
Parameter type/value [bottom|top|both]
Available ≥ 1.1.6
Summary Position of navigation bar for the image slider.
Details  
Language key SIGPLUS_SLIDER_NAVIGATION
Example {gallery navigation=bottom}fruit{/gallery}
Navigation buttons
Local parameter buttons
Parameter type/value boolean
Available ≥ 1.2.0
Summary Show navigation control buttons |< (first), < (previous), > (next) and >| (last) in the image slider navigation bar.
Details  
Language key SIGPLUS_SLIDER_BUTTONS
Example {gallery buttons=0}fruit{/gallery} will not show navigation buttons first, previous, next and last in the navigation bar.
Page counter
Local parameter counter
Parameter type/value boolean
Available ≥ 1.2.0
Summary Show page counter (i.e. 1 of 4) in the image slider navigation bar.
Details This may be turned off for galleries with two or three pages, as well as to conserve space, especially for vertical image slider orientation. The page counter text 1 of 6 is language-dependent.
Language key SIGPLUS_SLIDER_COUNTER
Overlay navigation
Local parameter overlay
Parameter type/value boolean
Available ≥ 1.2.2
Summary Show navigation buttons that overlay the image slider. These buttons do not take up additional space and are shown only when the mouse moves over the image gallery (either at the left and right side for horizontally oriented sliders or at the top and bottom for vertically oriented sliders).
Details  
Language key SIGPLUS_SLIDER_OVERLAY
Example {gallery overlay=1}fruit{/gallery} will enable overlay navigation buttons.
Slide duration
Local parameter duration
Parameter type/value integer
Available ≥ 1.3.0
Summary Time taken for the slider to move from one page to another [ms].
Details  
Language key SIGPLUS_SLIDER_DURATION
Example {gallery duration=800}fruit{/gallery} will make the slide animation between pages to take 0.8 seconds.
Animation delay
Local parameter animation
Parameter type/value integer
Available ≥ 1.3.0
Summary Time taken between successive automatic slide steps when the mouse moves away from over the slider [ms]. Use a value of zero to disable automatic “idle” animation.
Details  
Language key SIGPLUS_SLIDER_ANIMATION
Image captions
Local parameter captions
Parameter type/value [none|boxplus.caption|boxplus.hover]
Available ≥ 1.1.6
Summary Preview image overlay captions engine to use. The engine is not activated if an image does not have a caption.
Details The standard boxplus captions engine displays the title assigned to the image in the labels file using a translucent box that shows up in the bottom part of the preview image. In contrast, the boxplus hover window shows the image in the same size as it would be displayed in a pop-up window in such a way as not to cover the preview image when the mouse moves over the preview image.
Language key SIGPLUS_CAPTIONS
Default title
Local parameter deftitle
Parameter type/value text/html
Available ≥ 1.3.0
Summary Title assigned to images when no image titles are supplied in a labels file.
Details The local override does not support HTML tags. You can, however, use HTML tags when assigning a value to this setting in the back-end.
Language key SIGPLUS_CAPTIONS_TITLE
Default description text
Local parameter defdescription
Parameter type/value text/html
Available ≥ 1.3.0
Summary Description text assigned to images when no image descriptions are supplied in a labels file.
Details The local override does not support HTML tags. You can, however, use HTML tags when assigning a value to this setting in the back-end.
Language key SIGPLUS_CAPTIONS_TEXT
Download icon
Local parameter download
Parameter type/value boolean
Available ≥ 1.2.4
Summary Show download icon in pop-up window and overlay captions. When the user clicks the icon, the browser prompts the user to save the original image to their local computer. If a high-resolution image is available in a separate folder, the user will be prompted to download that image, otherwise the same image will be downloaded as displayed in the pop-up window.
Details See setting Folder for originals below.
Language key SIGPLUS_CAPTIONS_DOWNLOAD
Metadata icon
Local parameter metadata
Parameter type/value boolean
Available ≥ 1.2.4
Summary Show metadata icon in pop-up window and overlay captions. When the user clicks the icon, digital camera information and other image metadata like caption, summary, creator and copyright are displayed in a separate scrollable pop-up window. Some pop-up window implementations do not permit displaying metadata.
Details

If you use no external labels file (a.k.a. labels.txt) to attach captions to images or the caption is missing, sigplus will use IPTC tags Headline and Caption-Abstract to label images. The metadata icon is hidden if the image has no metadata.

Metadata are extracted from the APP13 IPTC block, which can negatively affect performance if there are many images in a gallery. The implementation uses the PHP function iptcparse. This function is known to fail, thereby not returning any metadata whatsoever, if the image contains non-standard proprietary tags added by commercial applications (e.g. Photoshop). These software can usually be configured in such a way as to restrict the tags added to images to those in the standard set.

Only boxplus and Fancybox support displaying metadata; if you use another pop-up window implementation, a boxplus window will be used to show metadata.

Language key SIGPLUS_CAPTIONS_METADATA
Margin
Local parameter margin
Parameter type/value integer
Available ≥ 1.2.6
Summary Margin around thumbnail images [px]; use a number without a unit. The margin clears a completely transparent area around the border. If omitted, the margin specified in the style sheet file (sigplus.css) applies.
Details

Margin (shown in gray), border width (shown in black) and padding (shown in tan) add up to a total amount of space to reserve around the image (shown in white).

image
Language key SIGPLUS_CSS_MARGIN
Example {gallery margin=4}fruit{/gallery} will add a margin of 4 pixels around the border of each image in the gallery.
Border style
Local parameter borderstyle
Parameter type/value [default|none|dotted|dashed|solid|double|groove|ridge|inset|outset]
Available ≥ 1.2.6
Summary Style of border to display around preview images. The border lies around the padding and the preview image. If set to default, the border style specified in the style sheet file (sigplus.css) applies.
Details See figure at margin.
Language key SIGPLUS_CSS_BORDER_STYLE
Border width
Local parameter borderwidth
Parameter type/value integer
Available ≥ 1.2.6
Summary Width of border to display around preview images [px]. If omitted, the border width specified in the style sheet file (sigplus.css) applies.
Details If border style is none, this setting has no effect.
Language key SIGPLUS_CSS_BORDER_WIDTH
Border color
Local parameter bordercolor
Parameter type/value color
Available ≥ 1.2.6
Summary Color of border to display around preview images. If omitted, the border color specified in the style sheet file (sigplus.css) applies. Specify a hexadecimal value between 000000 and FFFFFF inclusive in the RGB system (red: FF0000, green: 00FF00, blue: 0000FF), or use the color picker.
Details If border style is none, this setting has no effect. When used as an inline parameter, the hexadecimal color code must be quoted.
Language key SIGPLUS_CSS_BORDER_COLOR
Example {gallery borderwidth=1 borderstyle=dotted bordercolor="000000"}fruit{/gallery} will add a black dotted border of a single pixel width around each image in the gallery.
Padding
Local parameter padding
Parameter type/value integer
Available ≥ 1.2.6
Summary Padding around preview images [px]; use a number without a unit. The padding clears an area directly around the preview image within border bounds. If omitted, the padding specified in the style sheet file (sigplus.css) applies.
Details See figure at margin.
Language key SIGPLUS_CSS_PADDING
Example {gallery padding=2}fruit{/gallery} will add a padding of 2 pixels around each image in the gallery.

Advanced parameters

Use cache for generated images
Local parameter n/a
Parameter type/value boolean
Available ≥ 1.0.0
Summary Whether to use Joomla cache folder for storing preview images and thumbnails. If yes, the preview and thumbnail image folders are created inside the cache folder. Since this folder is shared, image names are hashed to avoid name conflicts.
Details

This setting has no performance implications, it only affects how preview images are organized on the server. If you are not supplying your own preview images and thumbnails, it is recommended to use the cache folder because it lets you clean up generated images directly from the Joomla back-end with a few clicks and ensures that images are re-generated when some configuration settings are altered.

Keep in mind the side effects of setting Use cache for generated images to No. In such a situation, sigplus does not compute a hash but uses the same file name as for the original image, and places the generated file into the thumb or preview image subfolder, as appropriate. This means that sigplus is not able to determine whether the current settings for image dimensions, cropping method or image quality match those of an image it locates in the thumb or preview image subfolder. For instance, if you set cropping on, have sigplus generate preview images by viewing a page with the gallery and then set cropping off, sigplus will not overwrite the images it finds in the preview image subfolder and will use the cropped versions it had generated earlier. You must manually clean the preview image subfolder to have sigplus regenerate the images.

In computing the hash, sigplus uses the path to original image in file system, target image dimensions, cropping method and image quality.

Language key SIGPLUS_THUMB_CACHE
Thumbnail folder
Local parameter n/a
Parameter type/value string
Available ≥ 1.0.0
Summary Subdirectory to store thumbnail images. Thumbnail images are low-resolution images with width and height of at most 100 pixels used inside a pop-up window to help navigation. Use a relative path, which is interpreted w.r.t. the image folder (or the cache folder). With no cache folder use, default image base and thumbnail folder, using sigplus/birds as the images folder causes thumbnails to be read from root/images/stories/sigplus/birds/thumbs. Appropriate file permissions are required to automatically create this folder and the thumbnails within.
Details See base folder for which characters are permitted in a relative path.
Language key SIGPLUS_THUMB_FOLDER
Preview folder
Local parameter n/a
Parameter type/value string
Available ≥ 1.3.0
Summary Subdirectory to store preview images. Preview images are low- to medium-resolution images typically displayed in an image slider. Preview images are retrieved from the server on demand, i.e. only those preview images are downloaded that are being shown. Use a relative path, which is interpreted w.r.t. the image folder (or the cache folder). With no cache folder use, default image base and preview image folder, using sigplus/birds as the images folder causes preview images to be read from root/images/stories/sigplus/birds/preview. Appropriate file permissions are required to automatically create this folder and the preview images within.
Details See base folder for which characters are permitted in a relative path.
Language key SIGPLUS_PREVIEW_FOLDER
Folder for originals
Local parameter n/a
Parameter type/value string
Available ≥ 1.2.4
Summary Subdirectory to look for high-resolution original images. When the user clicks the download icon, the browser will prompt to save the image in this folder to the user's local computer instead of the (possibly lower-resolution) image that is being shown in the lightbox pop-up window. The full-size image folder is useful for providing a high-quality image version for archival or printing rather than web browsing. If no high-quality version is available, the same image as shown in the pop-up window will be downloaded. Use a relative path, which is interpreted w.r.t. the image folder.
Details See base folder for which characters are permitted in a relative path.
Language key SIGPLUS_FULLSIZE_FOLDER
Base URL
Local parameter n/a
Parameter type/value string
Available ≥ 1.3.3 (for 1.3.x) and ≥ 1.4.1 (for 1.4.x)
Summary Base URL that corresponds to the base folder or image folder specified either with an absolute or a relative path w.r.t. the Joomla root. This field should be normally be left empty if the image (base) folder is a relative path w.r.t. the Joomla root directory. However, if an absolute path is specified for the image (base) folder, which typically happens when images are served from the same file system but under a different domain or subdomain, this setting determines what to prefix image folder paths with.
Example The following examples assume your Joomla root folder is /home/example/www/joomla/, which is served under the fictitious URL http://example.com/joomla/.
Image (base) folder Base URL Path to the image sample.jpg URL to the image sample.jpg
images/stories blank /home/example/www/joomla/images/stories/sample.jpg http://example.com/joomla/images/stories/sample.jpg
images/stories http://images.example.org /home/example/www/joomla/images/stories/sample.jpg http://images.example.org/sample.jpg
/home/images/www http://images.example.org /home/images/www/sample.jpg http://images.example.org/sample.jpg
Language key SIGPLUS_BASE_URL
Thumbnail quality
Local parameter quality
Parameter type/value integer
Available ≥ 1.2.0
Summary Image quality parameter for generating thumbnails with the lossy JPEG compression. Ranges from 0 (worst quality, smaller file) to 100 (best quality, biggest file) inclusive. Other image types with lossless compression (e.g. PNG or GIF) are not affected.
Details  
Language key SIGPLUS_THUMB_QUALITY
Filename for labels
Local parameter labels
Parameter type/value string
Available ≥ 1.1.0
Summary Name to use for the text file (without extension) that contains image titles and descriptions.
Details The name should validate against the regular expression [A-Za-z0-9._-]+ (POSIX fully portable filename is required). This setting also affects multilingual labeling. When this setting has the special value filename, sigplus labels each image with their filename without extension (e.g. a file Parliament.jpg will be labeled Parliament).
Language key SIGPLUS_LABELS
Example Supposing the folder fruit contains files Apple.jpg, Banana.jpg and Lemon.jpg, the activation tag {gallery labels=filename}fruit{/gallery} will use image captions Apple, Banana and Lemon provided that a captions engine is enabled.
Multilingual support
Local parameter n/a
Parameter type/value boolean
Available ≥ 1.0.1
Summary Support language-sensitive image file labeling. If enabled, labels file is selected based on the site language, e.g. English (UK) uses labels.en-GB.txt.
Details Multilingual support is useful if your site displays in multiple languages, e.g. by means of the Joomfish component. Should you have a labels file labels.en-GB.txt for English visitors and a labels.pt-PT.txt for Portuguese visitors, sigplus will use the language file that matches the visitor's current language. If no labels file is found with the matching language, there is a fallback to labels.txt as if multilingual support was not enabled. If your site uses a single language (which should not necessarily be English), you can safely disable multilingual support and use a labels.txt file to store your captions.
Language key SIGPLUS_LABELS_MULTILINGUAL
Default sort criterion
Local parameter sortcriterion
Parameter type/value [labels-filename|labels-mtime|filename|mtime|random|randomlabels]
Available ≥ 1.1.5
Summary Criterion to use to arrange images within a gallery: images are sorted according to the specified criterion in the specified order. Criteria that are based on a labels file have a fallback option: when no labels file is found, the fallback criterion is used to sort images.
Details

The criterion can be either labels file order with fallback to file name order (labels-filename), labels file order with fallback to last modification time order (labels-mtime), file name order (filename or fname), last modification time order (mtime), random (random), or random with shuffling labels file entries (randomlabels).

The option labels-filename sorts based on the labels file, displaying images in the order they are listed in the file, respecting any repetitions. However, if you point sigplus to a folder where there is no labels file, sigplus uses the fallback option (filename) to arrange images in a logical order as opposed to dumping them in any arbitrary order they happen to be in the file system. labels-mtime exhibits a similar behavior, using mtime as fallback.

The option filename sorts based on the file name, irrespective of the order of entries in a possible labels file. If a labels file exists but some files are not listed in it, they will still be shown but without captions. The semantics of mtime is very similar.

Setting the sort criterion to random displays all images in the image folder in a different random order each time the page is displayed. The option randomlabels is similar to random except that it shuffles only those images listed in the labels file and not all images in the image folder. If no labels file exists, the behavior is identical to random.

Language key SIGPLUS_SORT_CRITERION
Example {gallery sortcriterion=fname sortorder=asc}fruit{/gallery} will sort images in the fruit gallery by filename in ascending order (A to Z).
Default sort order
Local parameter sortorder
Parameter type/value [ascending|asc|descending|desc]
Available ≥ 1.1.5
Summary Order to use within the specified sort criterion: images are sorted according to the specified criterion in the specified order.
Details This setting should be used in conjunction with sortcriterion.
Language key SIGPLUS_SORT_ORDER
Example {gallery sortcriterion=mtime sortorder=desc}fruit{/gallery} will sort images in the fruit gallery by last modification time in descending order (image last uploaded first).
Data population method
Local parameter linkage
Parameter type/value [inline|head|external]
Available ≥ 1.3.0
Summary Determines how gallery data is embedded in or linked to the webpage. When a gallery is embedded, HTML code is emitted directly in the page body; this is recommended for galleries of small to medium size. When a gallery is generated from script, only a placeholder is emitted in the page body, and JavaScript code is used to populate the placeholder with gallery items. The JavaScript code can be placed either in the HTML head or in an external file; the latter is strongly recommended for large galleries (100 or more images). The downside to script-based population as opposed to embedding the gallery directly in the page body is that search engines are unable to index galleries created in this manner.
Details The linkage option external is not compatible with authentication enabled.
Language key SIGPLUS_LINKAGE
Example {gallery linkage=external}fruit{/gallery} will use external linkage: a .js file will be generated in the cache folder and included using the link tag in the HTML head.
Use public AJAX libraries
Local parameter n/a
Parameter type/value boolean
Available ≥ 1.1.0
Summary Enable this setting when the contents of the site are exposed to the public internet, in which case Google AJAX Library API services are utilized. You might want to set this setting to no if your site is accessible only within a (corporate) intranet. This setting only affects performance, not functionality.
Details The setting has no effect when only the MooTools framework is in use, which is served by Joomla.
Language key SIGPLUS_AJAXAPI
Image processing library
Local parameter n/a
Parameter type/value [none|gd|imagick]
Available ≥ 1.2.7
Summary Image processing library to use for generating thumbnail and preview images. Only those PHP libraries are listed that are supported by your system. When this setting reads none, you will not be able to use automatic thumbnail and preview image generation services normally provided by sigplus, and will have to supply your own thumbnail and preview images generated off-line.
Details  
Language key SIGPLUS_LIBRARY
Activation tag (plug-in only)
Local parameter n/a
Parameter type/value string
Available ≥ 1.2.0
Summary Sets the activation tag used for invoking sigplus. Changing this setting is recommended only if sigplus conflicts with another image gallery plug-in that would also be activated with the {gallery} tag. The tag name may only contain (English) letters and is case-sensitive.
Details This setting is not applicable to the module version of sigplus, where no activation tag is required.
Language key  
Debug mode
Local parameter n/a
Parameter type/value boolean
Available ≥ 1.2.3
Summary Whether to use uncompressed versions of lightbox, slider and captions engine scripts. Normally, compressed and obfuscated versions of these scripts are used to conserve network bandwidth usage. Debug mode is useful if you experience a script error on a page and you would like to discover its cause, which is difficult to perform with obfuscated names. When asking for support, please make sure to enable debug mode.
Details  
Language key SIGPLUS_DEBUG
Backup/Restore settings
Local parameter n/a
Parameter type/value n/a
Available ≥ 1.3.0
Summary Backs up parameters to or restores parameters from a textual representation. This utility is useful to transfer settings from the plug-in to the module version, or from one system to another, or persist settings when upgrading to a newer version.
Details Click the button Backup to get a textual representation of all back-end settings. Click the button Restore to set back-end parameters based on the contents of the text box.
Language key  

Parameters available as local overrides only

Position for image captions
Local parameter imagecaptions
Parameter type/value [overlay|above|below]
Available ≥ 1.3.2
Summary Position of box that reserves space for image captions added by a captions engine.
Details No additional space is reserved for the option overlay, the captions appear over the image.
Custom identifier
Local parameter id
Parameter type/value identifier
Available ≥ 1.2
Summary Image thumbnail galleries are wrapped inside an HTML div element. Normally, the identifier is generated automatically based on the image source folder but this setting overrides this behavior and specifies the identifier to use for the id attribute explicitly. This is useful for custom CSS styling.
Details  
Authentication
Local parameter authentication
Parameter type/value boolean
Available ≥ 1.2.4
Summary Demand Joomla authentication for viewing and downloading images. Only logged-in users will be able to view and download images. The image folder can be password-protected to prevent unauthorized access: sigplus will use a separate dynamic download mechanism to serve images.
Details When authentication is required for a gallery, sigplus will marshal all image requests through a file download.php that will verify whether a user is logged in. If they are, they will be served the image to be shown; if not, they will be returned a Not found error message. download.php uses a hash value (a series of characters that starts with ?h= in the URL), which is computed based on a number of properties, including the last time the user has logged in to the website. Hence, links that contain download.php and use authentication are temporary links: other visitors cannot make use of them to access the gallery images directly (they are not logged in) and not even a logged-in user can save them for future reference (the last visit date will change the next time the user logs in). Once you have set up authentication for a gallery (e.g. for images/stories/buildings), you would typically password-protect the directory that contains the images (i.e. visitors will get an error response when they try to access files in images/stories/buildings). Password-protection does not affect sigplus: download.php uses the PHP function readfile to serve images.
Example {gallery authentication=1}fruit{/gallery} will allow only logged-in users to view images in original size or download high-resolution image versions, other visitors will be prompted an error message.
Progressive loading
Local parameter progressive
Parameter type/value boolean
Available ≥ 1.3.0
Summary Whether to use progressive loading when displaying an image gallery. Progressive, on-demand or incremental loading allows the browser to procrastinate fetching those images from the server that are not visible to the user. For example, should you have a gallery that consists of 25 slider pages, it is not necessary to fetch all preview images from the server immediately, it is enough to get images for pages 1 and 2, which the visitor is currently viewing or is expected to view in the very near future. This improves site responsiveness and hence user experience.
Details Progressive loading is enabled by default, and is automatically applied to images shown in the pop-up window, irrespective of this configuration setting.
Recursion limit
Local parameter depth
Parameter type/value nonnegative integer or -1
Available ≥ 1.3.3 (for 1.3.x) and ≥ 1.4.1 (for 1.4.x)
Summary Recursion limit for scanning directory hierarchies in the file system. The default value of 0 restricts images to be included in generating a gallery to those in the folder specified. The value -1 will perform a recursive traversal of the directory hierarchy and include any images that are found in the specified folder or any of its descendants. A positive value sets a depth limit on the recursion.
Details Sort criterion and sort order apply globally. For instance, setting sort criterion and order such that the last modified image is shown first means that the image last modified irrespective of which subfolder it is in will be shown first.
Example

{gallery depth=-1}buildings{/gallery} will generate a gallery of images in the folder images/stories/buildings or any of its subfolders.

{gallery depth=1}buildings{/gallery} will produce a gallery of images in the folder images/stories/buildings or any of its subfolders that are directly in the folder buildings.

Engine-specific parameters

sigplus ships with multiple pop-up window, slider and overlay caption engines. Engines of a specific type share common attributes; e.g. all image sliders have a parameter to adjust slide duration and delay between successive animation steps. Other attributes, however, are specific to a particular engine; e.g. the default slider has an opacity parameter to control how much the preview image fades when the user moves the mouse pointer away from the image. To attach engine-specific parameters to a particular gallery instance, add an engine type qualifier before the parameter name:

{gallery slider:opacity=1}fruit{/gallery}

Such parameters are passed unaltered to the engine implementation. Below you find parameters applicable to the boxplus family of products. You should consult the respective documentation on what parameters are accepted by third-party engines like Fancybox, prettyPhoto or Slimbox.

Advanced users' note: Type conversions apply when interpreting parameter values. Values that comprise of digits are converted into type integer, other numeric values are converted into type float, and the rest are marshaled as type string. Parameters are passed to implementations as a JSON object.

If an engine-specific parameter is meant to be applied to all galleries on your site, a practical way to set defaults is to use the Custom settings entry in the Advanced parameters section of the sigplus configuration page in the Joomla administration back-end. Like with other configuration directives, parameter values set directly in the activation tag override those set in the back-end.

boxplus lightweight pop-up window engine (lightbox)

Automatically fit to window
Local parameter lightbox:autofit
Parameter type/value boolean
Available ≥ 1.3.0
Summary Whether to reduce dimensions of oversized images to fit the browser window when they are displayed.
Details When autofit is enabled, an expand/contract icon will be shown in the top right corner of the image to let the user view the image in its original size.
Example {gallery lightbox=boxplus lightbox:autofit=0}buildings{/gallery} will not shrink the image if it is too large to fit into the browser window.
Allow context menu when right-clicking images
Local parameter lightbox:contextmenu
Parameter type/value boolean
Available ≥ 1.3.1
Summary Whether the context menu appears when right-clicking an image inside the pop-up window. The context menu typically allows the user to copy or save the image to a local folder.
Details Even if the context menu is disabled with this configuration parameter, an advanced user may configure their browser to show the context menu; boxplus subscribes to the contextmenu event of the document object and programmatically causes the event to be ignored, but such event subscriptions can be disabled altogether with appropriate browser settings, which cannot be overridden from JavaScript code.
Example {gallery lightbox=boxplus lightbox:contextmenu=0}buildings{/gallery} will ignore right mouse clicks in the image inside the pop-up window.
Easing effect
Local parameter lightbox:easing
Parameter type/value [swing|linear]
Available ≥ 1.3.0
Summary Speed at which the pop-up window animation progresses at different points during the change image or content animation.
Details The default setting swing produces an elastic, rubber-like animation, the setting linear causes the pop-up window to be animated at constant speed. For details see the animate method in the jQuery API documentation.
Example {gallery lightbox=boxplus lightbox:easing=linear}buildings{/gallery} will cause the pop-up window frame to contract and expand at constant speed when the pop-up window is opened or a navigation button is clicked and another image is to be shown.
Loop when navigating
Local parameter lightbox:loop
Parameter type/value boolean
Available ≥ 1.3.0
Summary Whether the image sequence loops such that the first image follows the last when clicking navigation buttons.
Details  
Example {gallery lightbox=boxplus lightbox:loop=1}buildings{/gallery} will have the navigation button previous show the last image when clicked and the current image shown is the first.
Position for quick-access navigation bar
Local parameter lightbox:thumbs
Parameter type/value [inside|outside]
Available ≥ 1.3.2
Summary Placement of thumbnail navigation bar that lets users jump quickly to a particular image in the gallery. The navigation bar may be placed either over the image shown (inside) or in the caption area typically below the image (outside).
Details When the navigation bar is superimposed over the image, it is only shown while the mouse pointer is within the bottom part of the image container. In contrast, a navigation bar outside the image container is permanently visible. The quick-access navigation bar is not shown when the gallery compises of a single image, and no space is reserved in this case even with the outside placement option.
Example {gallery lightbox=boxplus lightbox:thumbs=outside}buildings{/gallery} will place the quick-access thumbnail navigation bar in the caption area, below the image.

boxplus image slider engine

A slider displays images aligned in a row, in a column, or in a grid. The images are expected to be of uniform size; should they differ in their dimensions, an appropriate amount of spacing will be added on the sides.

Allow context menu when right-clicking images
Local parameter slider:contextmenu
Parameter type/value boolean
Available ≥ 1.3.1
Summary Whether the context menu appears when right-clicking an image inside the pop-up window. The context menu typically allows the user to copy or save the image to a local folder.
Details For details, see lightbox:contextmenu.
Example {gallery slider=boxplus.slider slider:contextmenu=0}buildings{/gallery} will ignore right mouse clicks inside an image in the image slider.
Preview image opacity
Local parameter slider:opacity
Parameter type/value float
Available ≥ 1.3.0
Summary Opacity degree when the mouse pointer moves away from over a preview image in the slider. A value of 1.0 means a totally opaque image; there is no visual effect when the mouse pointer leaves the bounds of a preview image. A value of 0.0 translates into a totally transparent image; the preview image becomes invisible when the mouse pointer leaves its bounds. Floating point numbers in between the two extreme values give a nice visual clue; images dim somewhat depending on the opacity value.
Details  
Language key SIGPLUS_SLIDER_OPACITY
Example {gallery slider=boxplus.slider slider:opacity="0.5"}fruit{/gallery} will make the preview images partially transparent when the mouse moves away from over them.
Step size
Local parameter slider:step
Parameter type/value [page|single]
Available ≥ 1.3.2
Summary Unit to advance the slider upon clicking navigation controls Previous and Next.
Details The value page navigates the user to the next set of images, i.e. all images currently shown are replaced with another image or empty space by the time the sliding completes. In contrast, the value single moves the slider forward or backward by the smallest unit possible (i.e. a single image, a single row or a single column).
Example

{gallery rows=1 cols=3 orientation=horizontal slider=boxplus.slider slider:step=single}fruit{/gallery} will make the slider advance by a single image when using navigation controls Previous and Next.

{gallery rows=2 cols=3 orientation=horizontal slider=boxplus.slider slider:step=single}fruit{/gallery} will cause the slider to advance by a single column when using navigation controls Previous and Next.

boxplus image carousel (rotator) engine

A carousel (rotator) shows a series of images aligned either in a horizontal or in a vertical line. The images fit tightly even if they differ in dimensions and a slide step moves by one image at a time. The carousel is infinite: there is always a previous and a next image in the sequence.

Edge blending
Local parameter slider:edges
Parameter type/value [sharp|blurred]
Available ≥ 1.3.2
Summary Transition effect with which the images blend into the background near the edges. The value sharp applies no blending, while with the value blurred images dim gradually into the background.
Details Blending is applied on both edges for centered positioning but only on the right (respectively, left) edge for LTR (respectively, RTL) languages. Blending is implemented with a gradient of constant color and varying transparency. The color is chosen as the background color of the first non-transparent ancestor of the carousel in the HTML DOM tree. Only the CSS property background-color is inspected, CSS background-image settings are ignored. (Future versions might use a mask instead of a gradient in which case choosing a background color would not be an issue. However, at the time of writing, masks have not gained wide-spread browser support yet.)
Example With {gallery slider=boxplus.carousel slider:positioning=center slider:edges=blurred}fruit{/gallery} images will fade into the background near the edges.
Positioning
Local parameter slider:positioning
Parameter type/value [side|center]
Available ≥ 1.3.2
Summary Whether the current image is shown at the (left or right) side of the viewport or centered in the middle of it.
Details Languages with LTR reading order are anchored at the left edge, while languages with RTL reading order are anchored at the right edge for the setting side.
Example Using {gallery slider=boxplus.carousel slider:positioning=center}fruit{/gallery}, the current image will be centered in view.
Window size
Local parameter slider:windowSize
Parameter type/value integer or CSS length
Available ≥ 1.3.2
Summary Size of the viewport window through which images are seen measured relative to its parent container. The window size determines the length of the dimension that corresponds to slider orientation, i.e. width for horizontally oriented sliders and height for vertically oriented sliders.
Details Dimensionless values are interpreted in pixels (px). The viewport window size is fixed; if images are of differing sizes, images on the right (or left) may be partially visible. The other dimension (i.e. height for horizontally oriented sliders and width for vertically oriented sliders) is the maximum of image height or width values, respectively, of images in the carousel. The default value for a horizontally oriented carousel is 100%.
Example

{gallery orientation=horizontal slider=boxplus.carousel slider:windowSize="75%"}fruit{/gallery} will create a carousel of width occupying three-fourths of the total width of the parent container.

{gallery orientation=vertical slider=boxplus.carousel slider:windowSize="400px"}fruit{/gallery} will create a carousel of 400 pixels height.

boxplus image transition engine

Loop when navigating
Local parameter slider:loop
Parameter type/value boolean
Available ≥ 1.3.0
Summary Whether the image sequence loops such that the first image follows the last when clicking navigation buttons.
Details  
Example {gallery slider=boxplus.transition slider:loop=1}fruit{/gallery} will have the navigation button previous show the last image when clicked and the current image shown is the first.
Number of slices
Local parameter slider:slices
Parameter type/value integer
Available ≥ 1.3.0
Summary Number of pieces to use in the transition animation. Higher numbers usually mean a more smooth transition at the cost of processing power.
Details Extremely high values may make the page less responsive.
Example {gallery slider=boxplus.transition slider:slices=15}fruit{/gallery} will animate 15 pieces to realize the transition animation.
Animation effect
Local parameter slider:effect
Parameter type/value [none|fade|bars|bars+fade|shutter|shutter+fade]
Available ≥ 1.3.0
Summary Animation effect to use when navigating from one image to another.
Details Effect names that contain a plus sign should be enclosed in double quotation marks (see example).
Example {gallery slider=boxplus.transition slider:effect=shutter}fruit{/gallery} will use the shutter animation effect.
{gallery slider=boxplus.transition slider:effect="bars+fade"}fruit{/gallery} will use the dropping bars animation effect with fading.

boxplus image captions engine

Always show captions
Local parameter captions:alwaysOnTop
Parameter type/value boolean
Available ≥ 1.3.0
Summary Whether the preview image overlay captions should always be shown, or only when the mouse pointer is moved over the image.
Details  
Example {gallery captions:alwaysOnTop=1}fruit{/gallery} will always show overlay captions even if the mouse pointer is not within the bounds of the preview image.

Watermark

The most practical way to set these parameters is to use the Custom settings entry in the Advanced parameters section of the sigplus configuration page in the administration back-end.

Enable watermarking
Local parameter watermark
Parameter type/value boolean
Available ≥ 1.3.0
Summary

Whether to superimpose a watermark over original images. The image to use as a watermark should be an image file with alpha channel transparency called watermark.png and placed in either the image gallery folder (where the images that are shown in the gallery are), the subfolder watermark, or the image base folder.

Assuming your image base folder is /images/ and original images are in the folder /images/sampledata/fruitshop/ the three possible locations for watermark.png are (1) /images/sampledata/fruitshop/ (2) /images/sampledata/fruitshop/watermark/ and (3) /images/. Only the first two options make sense for the sigplus module, which has no notion of base folder. In most cases, you want to use the second option.

Details When the watermark is superimposed, the original image is not altered but a new watermarked image is created instead. The generated image is saved in a subfolder watermark either in the Joomla cache folder or in the image gallery folder.
Example {gallery watermark=1 watermark:position=se watermark:x=15 watermark:y=10}buildings{/gallery} applies a watermark to each image in the folder buildings. The watermark is placed in the bottom right (southeast) corner, 15 pixels from the right edge and 10 pixels from the bottom edge.
Watermark positioning
Local parameter watermark:position
Parameter type/value [n|ne|e|se|s|sw|w|nw|c]
Available ≥ 1.3.0
Summary The position of the watermark within the image.
Details Placement north (n), northeast (ne), east (e), southeast (se), south (s), southwest (sw), west (w), northwest (nw) and center (c) all have their obvious effect.
Watermark distance from vertical edge
Local parameter watermark:x
Parameter type/value integer
Available ≥ 1.3.0
Summary The distance to keep from the left or right edge, as appropriate.
Details The distance from the vertical edge is not meaningful for placements center, north and south for which the watermark is automatically centered.
Watermark distance from horizontal edge
Local parameter watermark:y
Parameter type/value integer
Available ≥ 1.3.0
Summary The distance to keep from the top or bottom edge, as appropriate.
Details The distance from the horizontal edge is not meaningful for placements center, east and west for which the watermark is automatically centered.