This page describes the syntax of and demonstrates how to use the plug-in activation tag.

Basic syntax

By typing

{gallery}imagefolder{/gallery}

into the body of an article (content item), the plug-in will automatically produce previews of all the images in the folder /images/imagefolder. Clicking on any of the preview images will bring up a pop-up window. For example, type the following into the body of an article:

{gallery}sampledata/parks/landscape{/gallery}

The extension will produce a gallery of all the images drawn from the folder /images/sampledata/parks/landscape:

sigplus galleries can be configured globally (in the administration back-end) as well as locally (within content item text). Local settings are attached to the {gallery} marker as key-value pairs, e.g.

{gallery maxcount=4}sigplus/birds{/gallery}

When present, local parameters override global settings, e.g. {gallery preview-width=100}sigplus/birds{/gallery} overrides the default preview image width.

The syntax for the activation tag attribute list is very flexible. The following attribute lists are all equivalent:

{gallery preview-width=300 preview-height=200}birds{/gallery}
{gallery preview_width=300 preview_height=200}birds{/gallery}
{gallery preview-width="300" preview-height="200"}birds{/gallery}
{gallery preview-width='300' preview-height="200"}birds{/gallery}
{gallery preview-width=|300| preview-height=|200|}birds{/gallery}

Observe how the syntax permits exchanging hyphens (-) with underscores (_) as name component separators, and double or single quote characters (' and ") with the vertical bar character (|) as delimiters. Attribute values that comprise of more than one word must always be delimited to avoid ambiguity.

Wildcard patterns

sigplus can interpret more complex wildcard expressions like *.jpg in the path expression between the activation opening and closing tag. Two special wildcard characters are understood, inspired by operating system pattern matching:

  1. * matches zero or more characters, and
  2. ? matches a single character.

The following example demonstrates how wildcard pattern matching works. The example will match any file whose name contains the word australia at any location within the file name component:

{gallery id=parks}sampledata/parks/landscape/*australia*{/gallery}

Wildcard patterns are understood only in the file name component of the path. When sigplus encounters a path with a special wildcard character, the path is split into a directory component (e.g. sampledata/parks/landscape) and a pattern component (e.g. *australia*). The pattern will act as a filter on files in the directory.

Wildcard expressions are supported for only those galleries that are backed by the same file system where Joomla is running (local file system).

User name substitution

For logged-in users, sigplus can substitute the user name in the image source reference. Use

{gallery}users/{$username}/images{/gallery}

to have the log-in name of the current user be substituted in place of {$username}. Galleries created with such activation tags are accessible to registered users only, anonymous users are prompted an access forbidden message.

Embedding modules into articles

Occasionally, you may want to embed a sigplus gallery with the same configuration settings into the article body on several pages while keeping the gallery settings in sync with one another. This can be accomplished with the help of module instances. First, you should create a sigplus module instance in the Joomla module manager (with the button New) for each set of configuration settings. Next, you should assign them to fictitious template positions such as mygallery1 or mygallery2 by typing text into the drop-down list box Position. (Feel free to type any text and then hit ENTER. The new position name will immediately appear near the bottom of the list as an Active position.) Then, you should use the loadposition tag to load the desired sigplus module into a content item (such as a Joomla article):

{loadposition mygallery1}

The tag above loads the module that has been assigned to the fictitious template position mygallery1. (The module must be enabled and assigned to be shown on all pages. loadposition triggers the Load module plug-in that ships with standard Joomla, and embeds module content at the spot where the tag has been typed.)

Activating the lightbox

Occasionally, you do not need to have sigplus generate a possibly rotating gallery of images drawn from a particular folder but you would like to associate a pop-up window with a link targeted at an image or another resource. In order to cope with these situations, sigplus offers the possibility to directly invoke the pop-up window on a mouse click event associated with an anchor (HTML <a>).

Create a lightbox-powered link to

  • a local image: Owl
    {lightbox href=images/owl.jpg}Owl{/lightbox}
  • an external image: Hungary, 1956
    {lightbox href=https://www.google.com/logos/2010/hungarynationalday2010-ps.jpg title="October 23"}Hungary, 1956{/lightbox}

Create an anchor to an existing gallery (previously created with {gallery})

  • linking to the first image: A gallery
    {lightbox link=parks}A gallery{/lightbox}
  • linking to the specified image: A gallery
    {lightbox link=parks index=2}A gallery{/lightbox}

Make all anchors that meet a selector criterion lightbox-powered anchors:

  • associate with all links whose href attribute ends in the extension .jpg: {lightbox selector=|a[href$='.jpg']| /}
  • associate with all links whose rel attribute equals lightboxlightbox selector=|a[rel=lightbox]| /}

The selector can be an arbitrary CSS selector understood by the JavaScript HTML DOM function document.querySelector.

When creating a lightbox-powered link, activation tag parameters id, rel, class, style and title turn into HTML attributes with the same name and value. This allows, for instance, customizing the appearance of the generated links with a stylesheet. Likewise, all activation tag parameters whose name starts with data- turn into HTML data attributes of the generated anchor element. This may be used to customize the behavior of the lightbox engine. For example, the activation tag {lightbox href=images/owl.jpg style="font-weight:bold;" data-my-custom-attribute=my-custom-value}Owl{/lightbox} produces the link Owl.

Custom settings

Not all settings are explicitly spelled out in the list of back-end configuration settings. Some less frequently used options are only available as key=value pairs that you can set in the Additional settings multi-line text field on the Advanced settings tab of the sigplus plug-in configuration page, or use with the plug-in activation tag.

Consider the example of OpenGraph tags, automatically generated by sigplus and embedded in the page <head> section to help advertise galleries to social media websites:

<meta property="og:image" content="https://example.com/cache/preview/0dd26bdd99cef6e1dedf90fa1c09af5a.jpg" />
<meta property="og:image:width" content="727" />
<meta property="og:image:height" content="1000" />
<meta property="og:image:alt" content="A sample image" />

However, your site might have another extension, e.g. Phoca OpenGraph, which also produces OpenGraph tags, essentially leading to duplicates. If you do not like the way sigplus is generating the OpenGraph tags, you can switch them off altogether with the configuration open_graph=0. Although there is no way to set this directly on the graphical interface, you can type the following to Additional settings on the Advanced settings tab of the sigplus plug-in configuration settings:

open_graph=0

This will apply to all sigplus plug-in or module instances. If you want the setting to apply to a single module instance, use the configuration page of the module instance. If you want the setting to apply to a particular use of the sigplus plug-in, use activation tag parameters:

{gallery open_graph=0} path/to/folder {/gallery}