Creating an image gallery with sigplus is super easy but it it not much more difficult either to set some basic options. This article shows how.

Getting started

In order to use the extension you should type the name of an image folder in between the so-called activation tags into the body of an article. The image folder contains your pictures, and is searched for by default inside the folder images located in your Joomla root folder:

{gallery}hungary{/gallery}

The plug-in will automatically produce a preview of all the images in the folder images/hungary, and unless you change any configuration settings in the administration back-end, the result will look as follows:

Clicking on any of the previews will bring up a pop-up window with squared corners and white as the basic background color.

Adding labels

To attach labels to images in a gallery, the steps to take are as follows. Suppose you would like to add labels for the image gallery folder fruit with files cherry.jpg, pears.jpg and strawberry.jpg you have already uploaded in the Joomla administration back-end clicking the menu Content and choosing Media.

  • Create a text file called labels.txt on your computer.
  • For each image, add a caption line with a vertical bar separating file name, short title and longer description. In our example, this means labels.txt could have the following contents:
cherry.jpg|Cherry|The first item in my fruit collection.
pears.jpg|Pears|The second item in my fruit collection.
strawberry.jpg|Strawberry|The third item in my fruit collection.
  • Save the file.
    For text that contains non-English characters, users should save their file with UTF-8 encoding. If you have used Notepad (shipped with Windows) to edit the file, choose Save as… from the File menu, and set Encoding at the bottom of the pop-up dialog box to UTF-8.
  • Use the Media (or an FTP client) to upload labels.txt to the folder fruit where your images are.
  • Type {gallery}fruit{/gallery} into an article and see how the captions are shown when you click the images.

Getting started with customizing back-end options

Below you will find the further examples how to use sigplus and create beautiful galleries easily. There are two ways for fine-tuning how the galleries will look on your site. The first option is configuring sigplus in the administration back-end for which the information can be read in the first part of each example. The second option is entering all the necessary parameters you want to change directly into the body of the article as attributes of the activation tag. You can find the parameter names and values at the end of each example.

If you choose the first approach of configuring the extension in the administration back-end then all the galleries will share the same settings across the entire site. However, if you would like to display galleries customized in different ways then choose the second approach and type the necessary parameter names and values into the the body of the article as attributes of the activation tag. In this case you can have different gallery features for each usage of the sigplus activation tag. New parameter values set with the second approach override the settings inherited from the administration back-end.

After you have installed and enabled the extension for the first time, you will find the following basic settings in the administration back-end:

  • Base folder: images
  • Gallery layout: fixed
  • Image row count: 1
  • Image column count: 3
  • Maximum image count: 0
  • Crop when rescaling: no
  • Alignment on page: center
  • Preview image width: 200
  • Preview image height: 200
  • Lightbox pop-up type: boxplus dark color theme
  • Center on scroll: no
  • Fit to window: no
  • Lightbox navigation bar: overlaying image
  • Slideshow delay (in ms): 0
  • Autostart slideshow: no
  • Image rotator orientation: horizontal
  • Hotspot navigation: show
  • Navigation bar: bottom
  • Paging buttons: show
  • Navigation trigger: click
  • Trigger action step: single
  • Slide duration (in ms): 800
  • Animation delay (in ms): 0
  • Wrap around at end: on
  • Image caption visibility: on mouse over only
  • Image caption position: overlay bottom

In the examples that follow, we will see investigate what each of these options mean and how to use each to make the gallery appear the way you intend it to.

How to display all the images at once

Configuration in the administration back-end

  • Gallery layout: flow (without rotator)

Description and live example

As shown in the previous example, only a fixed number of images are shown at a time, and you may use navigation links to slide to the next set of images, which is practical if the image gallery contains many images. This layout is called fixed layout and is meant to align images in a row, column or grid. If you want no image slider but to display all image previews at once, simply activate flow layout (without rotator) in the administration back-end. Flow layout arranges images in a free-flow manner, as if they were characters in a piece of text.

The previews will look as follows:

Usage in article text

If you would like to show several galleries with different settings on your site, type the following parameters into the body of the article as part of the activation code:

{gallery layout=flow}myfolder{/gallery}

If you choose this approach there is no need to change any of the parameters in the administration back-end.

How to change the gallery alignment, number of rows and columns

sigplus galleries can be aligned to the left or right, either allowing or not allowing text to flow around the gallery, or can be centered. Alignment is sensitive to text directionality (left-to-right vs. right-to-left languages). Text following the activation tag of a left-aligned image gallery that permits text wrapping around should appear to the right of the gallery. (Left-aligned image galleries are implemented as left floated HTML elements.) Text following a right-aligned image gallery activation tag should appear to the left of the gallery provided that text is allowed to wrap around. Centered image galleries should clear any text from both their left and right side. Any text following the gallery activation tag will appear below the gallery. Likewise, left- and right-aligned image galleries that do not permit text wrapping around are rendered in a similar manner.

Configuration in the administration back-end

  • Image row count: 2
  • Image column count: 2
  • Alignment on page: right

All other settings are to be left with their defaults; refer to the list at the top.

Description and live example

The example shows a gallery with two rows and two columns on the right side of the page.

Usage in article text

{gallery rows=2 cols=2 alignment=right}myfolder{/gallery}</pre>

Show only a specified number of previews and let the text wrap around the gallery

Configuration in the administration back-end

  • Image row count: 2
  • Image column count: 2
  • Maximum image count: 3
  • Alignment on page: before-float
  • Lightbox pop-up type: boxplus light color theme
  • Image rotator orientation: vertical
  • Animation delay (in ms): 5000

All other settings are unchanged with respect to their defaults.

Description and live example

The example shows a gallery with two rows and two columns. Only three images display in the preview. The text is allowed to wrap around the gallery from the left (assuming left-to-right reading order). Clicking on the previews will bring up the pop-up window with a white background. The orientation of the image rotator is vertical, which means that rows move from downwards to upwards. Five seconds pass between successive automatic slide steps when the mouse moves away from over the rotator.

Usage in article text

{gallery rows=2 cols=2 maxcount=3 alignment=before-float lightbox=boxplus/light rotator_orientation=vertical rotator_delay=5000}myfolder{/gallery}

Configuration in the administration back-end

  • Image row count: 3
  • Image column count: 1
  • Alignment on page: right
  • Preview image width: 180
  • Preview image height: 180
  • Crop when rescaling: yes
  • Lightbox pop-up type: boxplus dark theme
  • Animation delay (in ms): 3000

All other settings are unchanged with respect to their defaults.

Description and live example

This gallery is shown with three rows and one column, located on the right side. All previews have the same width and height, which is 180x180 px. The pop-up window uses the dark theme. Three seconds pass between successive automatic slide steps when the mouse moves away from over the rotator.

Usage in article text

{gallery rows=3 cols=1 preview_crop=yes alignment=right preview_width=180 preview_height=180 lightbox=boxplus/dark rotator_delay=3000}myfolder{/gallery}

How to change the rotator orientation from horizontal to vertical and set the style of the pop-up window background

Images in a gallery with fixed layout can be arranged in a row, in a column, or in a grid. Orientation, on the other hand, determines whether images scroll horizontally or vertically, and if images are arranged in a grid, whether they are arranged column-wise (put images one under the other until there is no space left in the same column) or row-wise (put images one next to the other until there is no space left in the same row). The examples above and below illustrate the difference between horizontal and vertical orientation.

Configuration in the administration back-end

  • Image row count: 1
  • Image column count: 4
  • Preview image width: 200
  • Preview image height: 150
  • Crop when rescaling: yes
  • Lightbox pop-up type: boxplus dark theme
  • Lightbox navigation bar: hide
  • Image rotator orientation: vertical
  • Wrap around at end: off
  • Image caption position: overlay top

Description and live example

It shows a gallery with one row and four columns. Each and every preview has the same width and height, which is 200x150 px. The pop-up window features a dark color theme, and no navigation bar is shown. The images move from downwards to upwards when clicking on the navigation links because the orientation of the image rotator is vertical. After the last preview of the gallery is shown, the gallery will not start with the first image again when clicking the navigation button, you must navigate backwards to get back to the first preview image. The caption shows up above the preview image.

Usage in article text

{gallery rows=1 cols=4 preview_width=200 preview_height=150 preview_crop=yes lightbox=boxplus/dark lightbox_thumbs=none rotator_orientation=vertical loop=off caption_position=overlay-top}myfolder{/gallery}

Change the position of captions and thumbnails and make the gallery advance by a whole page

Configuration in the administration back-end

  • Image row count: 2
  • Image column count: 3
  • Lightbox navigation bar: in caption area
  • Slideshow delay (in ms): 4000
  • Trigger action step: page
  • Image caption position: above

Description and live example

This example displays a gallery with two rows and three columns. In the pop-up window the navigation bar is placed in the caption area, above the title text. A slideshow control button appears in the pop-up window. Pressing this button will trigger a slideshow, automatically showing the next image after 4 seconds of delay. The image rotator advances by a whole page instead of a single column when using navigation controls _Previous_ and _Next_. Image captions show up above the preview images.

Usage in article text

{gallery rows=2 cols=3 lightbox_thumbs=outside lightbox_slideshow=4000 rotator_step=page caption_position=above}myfolder{/gallery}

Create an automatic slideshow in the pop-up window and let the rotator proceed by mouse-over

Configuration in the administration back-end

  • Image row count: 1
  • Image column count: 1
  • Alignment on page: right
  • Slideshow delay (in ms): 4000
  • Autostart slideshow: yes
  • Navigation bar: top
  • Navigation trigger: mouseover
  • Image caption visibility: always

Description and live example

This example shows up as a gallery with one row and one column, on the right side of the page. The slideshow control button also appears in the pop-up window, but there is no need to press the button because the slideshow starts automatically and shows the next image after 4 seconds. The navigation bar for the image rotator displays on the top. Moving the mouse pointer over the control links causes the rotator to start advancing. Image captions can always be seen, not only when the mouse pointer moves over the previews.

Usage in article text

{gallery rows=1 cols=1 alignment=right lightbox_slideshow=4000 lightbox_autostart=1 rotator_navigation=top rotator_trigger=mouseover caption_visibility=always}myfolder{/gallery}

How to integrate with Flickr

sigplus provides integration with Flickr to allow users to host and manage their albums in Flickr, and display them on their website with sigplus. As such, Flickr albums are externally hosted galleries, no data is stored on your server: thumbnails, preview images and originals all come from Flickr servers. This helps if you have limited hosting space available for your website. However, this also puts some limitations on the gallery sigplus produces.

Flickr generates images is a set of pre-defined sizes, see Size Suffixes in the Flickr Services documentation. sigplus does a best-effort attempt to match the specified preview image and thumbnail sizes with what is available in Flickr. For example, if you set preview image width and height to 250 px, sigplus will use the Flickr image that has 320 px on the longest side, and will scale down the image to fit in a rectangle of 250-by-250 px. It will not choose the Flickr image that has 240 px on longest side because it would produce inferior quality when scaled up.

Because the way sigplus inter-operates with Flickr in a read-only fashion, all configuration settings that would result in manipulating the image are ignored. Specifically, cropping and watermarking are not available for galleries generated from Flickr albums.

Instructions step by step

  1. Create an API key in Flickr (unless you already have one).
  2. Find your user ID and album ID. If you open an album on the Flickr website, the URL in the address bar looks as follows:
    https://www.flickr.com/photos/153530530@N04/albums/72157661954593228
    which you should match against the pattern
    https://www.flickr.com/photos/USER_ID/albums/ALBUM_ID
    to get your user ID and album ID. The user ID is a series consisting mostly of numbers (as shown above). If you have a "friendly" user ID (a human-readable string like a name), you should
    1. sign in to Flickr,
    2. navigate to flickr.places.placesForTags,
    3. find Your user ID on the right-hand side of the page below the label Useful Values.
  3. Insert a sigplus activation tag into a Joomla article that has the structure
    {gallery}https://api.flickr.com/services/rest/?api_key=API_KEY&photoset_id=ALBUM_ID&user_id=USER_ID{/gallery}
    where photoset_id is your album ID. For example,
    {gallery}https://api.flickr.com/services/rest/?api_key=aabbccddeeff11223344556677889900&photoset_id=72157661954593228&user_id=153530530@N04{/gallery}
    The URL does not have to be a real Flickr service URL (but it can be), sigplus ignores everything except the API key, user ID and album ID.
Note: Flickr API (called internally by sigplus) recognizes numeric user IDs but not human-readable user IDs; using the human-readable version will cause Flickr to return an empty result set and in turn produce an empty sigplus gallery. Make sure you follow the above steps to get the numeric user ID if you have a "friendly" user ID.

Live example