A central notion to sigplus is image captions. This article shows how to assign captions to images and how to use caption templates.

Introduction

The term caption may refer to

  • short image title or
  • summary text.

The title, which is usually a few words long, will typically appear

  • directly on the page, either in an overlay caption, or above or below preview images, and
  • inside the lightbox pop-up window as a window title, in a distinctive position.
  • as alternate text for the img element in the generated HTML content (to help search engines identify images)

In contrast, the summary text, which is usually a sentence long, will appear below or next to the magnified image within the lightbox pop-up window.

The following all act as sources for image captions (in decreasing order of precedence):

  1. an explicit entry in a labels.txt file
  2. image metadata (IPTC and EXIF)
  3. default caption set via a labels.txt file with a wildcard pattern containing ? and *
  4. default caption specified in the back-end

This implies that if you use no external labels file (labels.txt) to attach captions to images or the caption is missing, sigplus will use IPTC tags Headline and Caption-Abstract to label images. Metadata are extracted from the APP13 IPTC block. 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.

Labels file

A labels file (typically called labels.txt) is a plain text file in the image folder with a three-fold function:

  1. binds a short title and summary text to images,
  2. defines a relative order of images in the gallery, and
  3. associates default captions with wildcard patterns.

Image file name, title and summary in labels.txt are separated by a | (vertical bar).

A sample labels.txt is shown below:

example.png|An image title|A longer, more verbose description.
example.jpg||A description that may contain <em>html formatting</em>.
apple.jpg|A ripe apple|This apple not only looks great but tastes just as good.
bunny.jpg|A cute bunny|This terra-cotta bunny has been laser-scanned at Budapest University of Technology.
example.jpg
*|Default title|Default summary text for <a href="http://hunyadi.info.hu/projects/sigplus/">sigplus</a>

As shown in the example, both title and summary are optional. Similarly to the back-end where you can specify a default title and summary associated with images that do not have an explicitly assigned title and summary or image metadata, a labels.txt file has the special entry *. Whenever an item has no title or summary, the default will be assigned.

Wildcard patterns

sigplus can interpret more complex wildcard expressions like *.jpg, which act as fall-back patterns. Two special wildcard characters are understood, inspired by operating system pattern matching:

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

Whenever an image lacks a title or summary, sigplus tries to match the file name against wildcard expressions from top to bottom: the first pattern that matches assigns the associated title or summary to the image. This implies that it makes sense to put the most general pattern (typically a single * entry) last.

In order to illustrate how the wildcard matching mechanism works, consider the following example:

*.jpg|A photo|A photograph taken with a digital camera.
car*|A car|A Porsche model.
*|Default title|Default summary text.
*.png|A graphic image

sigplus will make the following assignments to image titles based on the above labels.txt file:

  1. The file car.jpg matches *.jpg and will be assigned the title A photo. Even though car.jpg would also match car*, that pattern has lower priority.
  2. car.png does not match *.jpg but matches car* and thus will have the title A car.
  3. cat.png matches neither of the first two patterns, it will get the default title.
  4. No file will match the pattern *.png because the pattern * has higher precedence.

Entries without wildcard characters always take precedence over entries with wildcards, regardless of their position in labels.txt.

Multilingual support

Labeling supports multilingual sites. If multilingual support is enabled in the administration panel and a file labels.xx-XX.txt exists in a folder, where xx-XX is the placeholder for the ISO language code, e.g. en-GB for English (United Kingdom) or hu-HU for Hungarian, the language-specific labels file is used, with fallback to the default labels.txt.

Note that multilingual support is disabled by default for a new sigplus installation. Look for Use multilingual labels on the Advanced settings tab of the sigplus plug-in configuration page in the Joomla administration back-end to opt in to multilingual support.

Encoding

All label files are assumed to be UTF-8 encoded. (If you use English characters only, your text automatically qualifies as UTF-8.) For Windows, the editor Notepad++ has the option Convert to UTF-8 without BOM in the Format menu. sigplus can also recognize and remove the redundant byte-order mark (BOM) inserted by the default Windows text editor Notepad at the beginning of a UTF-8 encoded file.

Caption templates

In addition to caption and default caption, sigplus has a notion (and configuration parameter) of caption templates referred to as Image title template and Image summary template in the back-end. A template is a format-description text with special semantics, including placeholders like {$text}, {$name}, {$filename}, {$current} and {$total}, which define how a caption is formatted when it appears as an image label. The placeholder semantics are as follows:

  • {$text} is substituted with the caption text, either explicitly specified using a labels.txt file or extracted from image metadata, or the default caption as specified in the configuration.
  • {$current} and {$total} are substituted with the ordinal number of the image in its gallery and the total number of images in the gallery, respectively.
  • {$filename} is substituted with the image file name including the extension (but not the path).
  • {$filesize} is replaced with the image file size in bytes, KB or MB, whichever is appropriate.
  • {$name} is substituted with the image file name only (without extension).

An insightful example is as follows:

Back-end settings:

  • Image title template: {$text} ({$current} of {$total})
  • Default image title: Unidentified fruit

labels.txt contents:

cherry.jpg|Three cherries|Some cherries in my fruit collection.
pears.jpg|Two pears|A few pears in my fruit collection.
strawberry.jpg|A strawberry|A strawberry in my fruit collection.

Folder directory listing:

cherry.jpg
pears.jpg
peas.jpg
strawberry.jpg

Formatted caption for each file:

  • Three cherries (1 of 4)
  • Two pears (2 of 4)
  • Unidentified fruit (3 of 4)
  • A strawberry (4 of 4)

BBCode

Default image title, default image summary, image title template and image summary template support BBCode (bulletin board code). BBCode is a lightweight markup language used to format posts in many message boards. With BBCode markers in captions and caption templates, you can apply a subset of HTML formatting styles to title and summary text, getting around Joomla security measures that prohibit the direct use of HTML in many places, including back-end configuration settings. The following BBCode markers are supported:

  • [b]bold[/b], which maps to bold (HTML <b>bold</b>);
  • [i]italic[/i], which maps to italic (HTML <i>italic</i>);
  • [u]underline[/u], which maps to underline (HTML <u>underline</u>);
  • [s]strikeout[/s], which maps to strikeout (HTML <s>underline</s>);
  • [sup]superscript[/sup], which maps to superscript (HTML <sup>underline</sup>);
  • [sub]subscript[/sub], which maps to subscript (HTML <sub>underline</sub>);
  • [url]http://hunyadi.info.hu/projects/sigplus/[/url] and [url=http://hunyadi.info.hu/projects/sigplus/]link[/url], which map to http://hunyadi.info.hu/projects/sigplus/ and link, respectively.

In addition, linefeed characters are automatically converted into line breaks (HTML <br>).

Preview images as hyperlinks

sigplus can generate preview images that are clickable without the pop-up window effect. If you disable the pop-up window either globally or with a local override, and add an anchor tag to the description in labels.txt, sigplus will transform the preview image into a hyperlink: when a visitor clicks the image, they are taken to the specified location. All attributes of the anchor tag are preserved and carried over to the generated gallery. For example, suppose a labels.txt contains the following entries:

parliament.jpg|The Hungarian Parliament Building|The seat of the National Assembly of Hungary.
bme.jpg|BME|The main building of <a href="http://www.bme.hu" target="_blank">Budapest University of Technology</a>.
bme-q.jpg|BME Building Q|Building Q of <a data-article-id="11" target="_blank">Budapest University of Technology</a>.

If you insert the activation tag {gallery lightbox=none}buildings{/gallery} into an article (where buildings is the folder that contains the images), the second preview image will link to Budapest University of Technology. Notice the attribute target="_blank", which will cause the page to open in a new browser tab.

Occasionally, you may want the image to link to a Joomla article within the same site (an internal link), rather than to a page of another site (an external link). To help maintain link association between labels.txt and the Joomla site, sigplus supports a special attribute called data-article-id. The value of this attribute determines the Joomla article ID the internal link will target, article ID 11 in the example. The HTML anchor, in turn, expands into a full URL (using the Joomla router).