sigplus Advanced usage

Advanced usage

The sections below cover more advanced topics. A marker [≥ 1.3] at the beginning of a paragraph indicates the information in that single paragraph is specific to sigplus version 1.3.x, and the feature is not available in version 1.2.x.

Labels and description

Image labels have a two-fold function: a labels.txt file in the image folder is used to bind images to short title and description text, and it can restrict displayed images to those listed in that file. The title will appear as alternate text for the img element and possibly presented as the title of the pop-up window, while the description text will appear below or next to the magnified image within the window. Image file name, title and description in labels.txt are separated by a | (vertical bar). The order in which images are listed is respected and the same image may be listed multiple times. 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 description text for <a href="http://hunyadi.info.hu/projects/sigplus/">sigplus</a>

[≥ 1.3] As shown in the example, both title and description are optional. You may supply a default title and description with the special entry *. Whenever an item has no title or description, the default will be assigned. Note that only a single * is understood (it may put anywhere within the labels.txt file), sigplus cannot interpret wildcard expressions like *.jpg.

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.

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.

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>.

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.

Custom preview image styling

If you do not like the way image previews are displayed, you can use CSS styling to customize it. The subfolder sigplus/css contains the stylesheet file sigplus.css, which all image galleries use. (You find it in joomlaroot/plugins/content/sigplus/css once the plug-in has been installed.) You can change, among others, image margin (spacing outside border), border and padding (spacing inside border). W3schools has a practical reference on CSS rules.

The example below applies a border, changes margin to 6 pixels and padding to 4 pixels.

div.imageSlider ul > li img {
border:thin solid gray !important;
margin:6px !important;
padding:4px !important;
}

[≥ 1.3] The example below applies a border, changes margin to 6 pixels and padding to 4 pixels.

div.sigplus-gallery ul > li > img,
div.sigplus-gallery ul > li > a > img {
border:1px solid gray !important;
margin:6px !important;
padding:4px !important;
}

The !important rule forces style application even if a conflicting rule would occur in your Joomla template. Without !important, the style you set in sigplus.css may be overriden by the stylesheet of the template you use, which is included after sigplus.css, possibly leading to weird slider behavior.

The example below illustrates more advanced usage. It will apply a gray border around thumbnail images, which changes to red when the user moves the mouse over an image.

div.imageSlider ul > li img {
margin:2px !important;
border:thin solid gray !important;
padding:2px !important;
}

div.imageSlider ul > li a:hover img {
border:thin solid red !important;
}

[≥ 1.3] The example below illustrates more advanced usage. It will apply a gray border around thumbnail images, which changes to red when the user moves the mouse over an image. Each image cell is then surrounded by a blue border.

div.sigplus-gallery ul > li > a > img {
margin:2px !important;
border:thin solid gray !important;
padding:2px !important;
}

div.sigplus-gallery ul > li > a:hover > img {
border:thin solid red !important;
}

div.sigplus-gallery ul > li {
margin:4px !important;
border:thin solid blue !important;
padding:2px !important;
}

Customization with overrides

sigplus Image Gallery Plus galleries can be configured globally (in the administration backend) as well as locally (within content item text). Local settings are attached to the {gallery} marker as key-value pairs, e.g. {gallery count=4}sigplus/birds{/gallery}. When present, local parameters override global settings, e.g. {gallery width=100}sigplus/birds{/gallery} overrides the default preview image width.

Downloading images

Images with high resolution (e.g. with size much larger than ~600 x 800 pixels) are usually not suitable for use on a website because they take considerable time to display on the client computer due to network latency. Besides, sigplus may easily run into memory allocation problems on the server when trying to load huge images into system memory in order to generate preview images. In addition, some pop-up window engines lack an auto-resize feature and/or do not allow saving an image by right-clicking the magnified image in the pop-up window and selecting a local folder to download to.

To remedy these issues and ensure maximum performance, sigplus classifies images into four categories in increasing order of detail: thumbnails, preview images, images displayed in a pop-up window, and high-resolution images. Thumbnails and preview images are typically generated by sigplus (based on the image displayed in the pop-up window) but images to be displayed and optional high-resolution images are to be uploaded by the site maintainer. When the user clicks the download icon, sigplus checks whether a high-resolution image version is available in a subfolder of the image gallery folder (the name of the subfolder is fullsize by default). If yes, the user is prompted to select a local folder for this high-resolution image. Otherwise, the user is prompted to save the same image as displayed in the pop-up window. This approach is a best of two worlds: you can have your visitors shown moderately-sized images quickly while they are browsing the gallery in the pop-up window, and let them download images they are interested in with full detail.

For example, suppose your images apple.jpg and banana.jpg are in the folder images/stories/fruit. Should you wish to let visitors download a high-quality version of apple.jpg, you should create a folder images/stories/fruit/fullsize and upload the high-quality version into that folder (the file name has to be the same so that sigplus knows which high-resolution image belongs to which moderate-quality version). When a visitor clicks the download icon, they will be prompted to download images/stories/fruit/fullsize/apple.jpg for apple.jpg and images/stories/fruit/banana.jpg for banana.jpg.

Opening a pop-up window gallery with a custom hyperlink

[≥ 1.3.4 and ≥ 1.4.2] sigplus supports activating a pop-up window and showing a gallery within by subscribing to the click event of a custom anchor. Suppose you would like to create a gallery but want to show the pop-up window for the gallery using a link rather than by having the visitor click one of the sigplus-generated preview images. First, create the gallery using the regular syntax but specify hidden as the layout to use and assign a unique id attribute to the gallery. If you use the plug-in, type

{gallery id=mygallery layout=hidden}myfolder{/gallery}

The parameter layout=hidden is optional and tells sigplus not to show the gallery in place of the activation tag. (In fact, the gallery will be embedded in the page surrounded with a div element whose style is set to display:none.)

In contrast, if you use the module, you should use the Custom parameters text box in the Advanced parameters panel, and type the following in a separate line:

id=mygallery

Once the gallery has been included either as a (possibly hidden) embedded gallery or a module, type the following in the body of the same article:

{gallery link=mygallery}Open gallery in pop-up window{/gallery}

This will create a link with the text Open gallery in pop-up window. Notice the link attribute, which tells sigplus which gallery to open when a visitor clicks the link, which is typically the id of one of the hidden galleries but it can point to any visible gallery as well. When the visitor clicks the link, the pop-up window will be shown with the images in the gallery.

You are not restricted to text inside the link, sigplus accepts any HTML content that is permitted inside a link. The following example illustrates that this includes images:

The code for the example above reads as follows:

{gallery link=buildings}<img height="56" width="75" src="/levente/strawberry.jpg" />{/gallery}

Showing Picasa web albums

This section describes an experimental feature. Even while it is fully functional in the latest public release, it has not been subject to the same amount of testing as other features. If you encounter problems with this feature, please feel free to This email address is being protected from spambots. You need JavaScript enabled to view it., providing as much detail as possible.

Important: This feature expects that it is able to retrieve documents from external domains (in particular, the Picasa site) using HTTP and as such requires PHP allow_url_fopen set to On. You can verify if this is so by opening System info in the administration back-end and clicking the tab PHP information, and finally finding the string allow_url_fopen in the table of configuration settings. Should allow_url_fopen be set to Off, Picasa album generation will fail and report an error. Please contact your server administrator when this happens, not the developer of sigplus, to have allow_url_fopen enabled for your site.

[≥ 1.3.4 and ≥ 1.4.2] sigplus can display Picasa web albums as an integrated part of a website in the text of an article or in a module position much like it can display galleries generated from a folder in your server file system. The plug-in syntax resembes the one to use in order to show galleries whose images are drawn from the file system:

{gallery}https://picasaweb.google.com/data/feed/base/user/USERID/albumid/ALBUMID{/gallery}

For the module, the Image folder has to be specified in the following way:

https://picasaweb.google.com/data/feed/base/user/USERID/albumid/ALBUMID

In the syntax above, USERID and ALBUMID are numeric identifiers used to specify which Picasa web album to show. (USERID can also be a friendly Picasa user name.) Such a link can be most easily obtained if you open one of your Picasa albums and right-click the link RSS and select Copy link location from the context menu. Be careful to use the RSS feed of one specific album and not your main Picasa page with several albums.

Displaying Picasa web albums is different from regular albums in that no images are stored or generated on your server. All images (including thumbnails and preview images) are referenced from the Picasa site. This means that preview image width and height is limited to what is provided by Picasa. Picasa supports maximum size specification (i.e. greatest of width and height), and only in pixel sizes 32, 48, 64, 72, 104, 144, 150, 160 (for both cropped and uncropped images) and 94, 110, 128, 200, 220, 288, 320, 400, 512, 576, 640, 720, 800, 912, 1024, 1152, 1280, 1440, 1600 (for uncropped images only). sigplus attempts to find the Picasa image size that is closest to the preview image width and height you specify.

In order to avoid having to retrieve the RSS feed each time the gallery displays, sigplus caches the gallery code generated based on the RSS XML response in the folder cache/sigplus the same way it caches other generated content. This means that changes in the Picasa gallery are only reflected on your website when the cache lifetime expires. This happens immediately if you clear the contents of the folder cache/sigplus (or in sigplus debug mode).

Helpful comments

Picasa album RSS feed URLs have the format

https://picasaweb.google.com/data/feed/base/user/USERID/albumid/ALBUMID

For example

https://picasaweb.google.com/data/feed/base/user/107879259713551876815/albumid/5593901925599403297

As apparent, these URLs produce an XML document for machine data exchange, and not a picturesque gallery people can browse, the actual gallery with the images is little help to sigplus.

In order to get a feed URL in Google+, open the gallery, e.g.

https://plus.google.com/photos/107879259713551876815/albums/5593901925599403297?banner=pwa

and click the link Click here to go back to Picasa Web Albums that displays at the top of the page, which takes you back to the old Picasa page, e.g.

https://picasaweb.google.com/107879259713551876815/040911AutowerkRusselsheim?noredirect=1

The old Picasa page has a link with the caption RSS on the right-hand side of the page. The URL behind that link is the Picasa RSS feed URL you are after if you would like to display a Picasa album in sigplus.

Full customization

This feature is under revision. For an alternative, see boxplus for MooTools, which has been explicitly designed to display arbitrary content (including images) and offers flexibility superior to boxplus for jQuery (integrated into sigplus 1.4 and earlier) in full customization mode. boxplus for MooTools and sigplus can be used side-by-side provided that you do not use a sigplus gallery and a boxplus anchor on the same HTML page or select a lightbox other than boxplus for jQuery in sigplus (boxplus for MooTools and boxplus for jQuery are not compatible with each other).

As opposed to the longer syntax {gallery}imagefolder{/gallery}, the compact syntax {gallery /} leaves more flexibility to the content item author. Whenever it occurs in a content item, any a (anchor) elements with href attribute pointing to a (magnified) image will show up in a separate pop-up window as opposed to standard browser behavior of navigating away from the currently viewed page to the (enlarged) image. Typically, the anchor wraps an img element that acts an image thumbnail but this is not required. This allows maximum level of customization: the exact layout, thumbnails to use, etc. can be set directly by the user. Most configuration settings (including preview image width, height, count, image labels) are not meaningful in this case.

Typically, you would want to make use of full customization when you would like to have the pop-up window functionality but do not need galleries automatically generated from a particular folder.

As a demonstration, click any of the anchors in list below; a pop-up window should appear with the image inside that has been referred to by the hyperlink. All three anchors have a href attribute that is a URL ending in .jpg, the last two point to the same image. Notice that the first anchor has a title attribute: when you move the mouse over the link a text appears and the exact text is shown under the image when the pop-up window opens. The last anchor wraps an image: when you click the image, the href attribute of the anchor will be used to determine the image to show in the pop-up window, which is the same as for the second anchor.

• sigplus logo
• boxplus logo
• 

The images above are shown independently. If you would like them to be part of the same gallery, supply a rel attribute to each of the anchors, beginning with the lightbox engine identifier and ending with a custom gallery name. For instance, consider the links to the sigplus logo and the boxplus logo. Both of them are annotated with the rel="boxplus-logo" attribute name-value pair, where boxplus is the lightbox engine identifier and logo is the unique gallery name. Click on one of the links to see how the pop-up window lets you navigate from one image to the other.

For the examples to work, you need to activate sigplus in full customization mode:

{gallery /}

Once the activation code is entered anywhere in an article, create links that point to resources which have an extension that indicates an image. Two of the examples above look as follows in source mode:

<a href="/levente/images/stories/sigplus/sigpluslogo.jpg">sigplus logo</a>
<a href="/levente/images/stories/boxplus/boxpluslogo.jpg">
  <img alt="A strawberry" height="56" src="/levente/images/stories/fruit/strawberry.jpg" width="75" />
</a>

[≥ 1.3] In full customization mode, one is not restricted to showing images in the pop-up window; the href attribute of the anchor can be a document identifier (e.g. #id) or an external URL (e.g. index.html or http://hunyadi.info.hu/projects/sigplus). In the first case, the descendants of the referred element in the DOM tree will be shown in the pop-up window. For instance, if the identifier points to a div element, all elements inside the div element will be shown in the window. In the second case, the referred external document will be downloaded in the background using an asynchronous HTTP request and then displayed in the window. The styling of the current document will affect the styling of the downloaded document. As an example, view the extract of GPL, the license sigplus uses, in a boxplus pop-up window.

Note: Retrieving an external document is subject to security restrictions. You might not be able to fetch a document that is from a different domain than your website.

[≥ 1.3] Not all pop-up window engines support displaying custom content, only boxplus and Fancybox can show arbitrary HTML content (limitations may apply as to what the content may actually be). To indicate that the contents referred to by the anchor should be shown in a pop-up window, you should add a rel attribute to the anchor with value either lightbox (for both boxplus and Fancybox), or boxplus and fancybox, respectively.

Examples of links to use with full customization

An anchor that points to an image:

<a href="/images/stories/boxplus/boxpluslogo.jpg">anchor</a>

An anchor to an image with a title attribute that will be shown as a description:

<a href="/images/stories/boxplus/boxpluslogo.jpg" title="A boxplus pop-up window.">boxplus logo</a>

An anchor to an image that wraps a thumbnail:

<a href="/images/stories/boxplus/boxpluslogo.jpg">
<img alt="A strawberry" src="/images/stories/fruit/strawberry.jpg" width="75" height="56" />
</a>

An anchor to a part of the page (see bottom), tagged with an id attribute. The contents of the identified element (i.e. whose id attribute is set accordingly) is copied to and displayed in the pop-up window. The anchor attribute rel="boxplus" indicates that boxplus should subscribe to the click event of the anchor rather than let the browser scroll the referenced element into view, which would be the normal behavior for such a link:

<a href="#license" rel="boxplus">GPL</a>

An anchor to an external document. Your browser may impose restrictions on what external content you can show, typically the external document has to be in the same domain as the currently shown web page to be fetched by boxplus:

<a href="http://example.com/example.html" rel="boxplus">An example document</a>

[≥ 1.3.2] An anchor to Flash (SWF) content or video. You should explicitly specify width and height for the Flash content:

<a href="http://www.adobe.com/products/flashplayer/include/marquee/design.swf?width=792&amp;height=294">A Flash (SWF) video</a>

[≥ 1.3.2] An anchor to a YouTube video (a tutorial video on sigplus not endorsed by us). Like in the case of Flash content, you should specify width and height:

<a rel="boxplus" href="http://www.youtube.com/v/SZpOyP0ZUZ0?width=640&height=390">A YouTube video</a>

Advanced example: creating a gallery and opening its pop-up window programmatically

[< 1.3.4 and < 1.4.2] The syntax described in this section has been superseded by a new syntax, and is preserved here only to help you migrate to the new syntax. In addition, this section uses inline JavaScript, which is not compatible with Joomla 1.6 due to new security measures introduced in that version.

Customization lets you create galleries and links that activate these galleries independently. Suppose you would like to create a gallery but want to show the pop-up window for the gallery using a link rather than by having the visitor click one of the sigplus-generated preview images. First, create the gallery using the regular syntax. In order to help referring to the gallery later, you should assign an id attribute to the gallery. If you use the plug-in, type

{gallery id=mygallery}myfolder{/gallery}

In contrast, if you use the module, you should use the Custom parameters text box in the Advanced parameters panel, and type the following in a separate line:

id=mygallery

Once the gallery has been generated, place the following link in a content item text:

<a href="javascript:__jQuery__('#mygallery a:first').boxplusDialog();">mylink</a>

When a visitor clicks the link, the boxplus pop-up window engine will be triggered. The engine will pick up any neighboring items in the same gallery and show them in the same window as if the visitor clicked the first preview image. Of course, you can link to not only the first image but any arbitrary image of your choice. The following example opens the pop-up window showing the second image in the gallery (indexing is zero-based):

<a href="javascript:__jQuery__('#mygallery a:eq(1)').boxplusDialog();">mylink</a>

If you do not want the original gallery to appear in the document, you can wrap it into a div HTML element whose display style is set to none:

<div style="display:none;">{gallery id=mygallery}myfolder{/gallery}</div>

Caching explained

Information in this section is tentative.

In order to improve server-side performance, sigplus saves generated images (thumbnails and preview images) as well as generated content (HTML and/or JavaScript). The folders used for this purpose are thumbs, preview and watermark (you can customize their name and location in the administration back-end) and sigplus (which is always created in the Joomla cache folder).

When a page with a gallery is first displayed, sigplus generates preview images for display in a slider or in flow layout, and thumbnails for display on the fast navigation bar inside the lightbox pop-up window. Since image processing is computationally expensive, sigplus saves the generated images for future re-use, therefore subsequent loading time for the page will be drastically reduced.

[≥ 1.3.4 and ≥ 1.4.2] Saving generated images, however, is only the first step. Not only are images cached but also the gallery code itself. With data population method set to inline (which is the default), this means the HTML code embedded in the page sent to the browser but when the gallery is constructed from a script, this means JavaScript usually served as a separate file. Like generating images, putting together gallery code can be expensive, especially if metadata and other properties have to be extracted from the images. Without caching, this means that each time the page is seen in a browser, the labels file has to be parsed and image files have to be opened and read on the server, looking for data of interest. With caching, the server only checks a (set of) timestamps (accessing only a few entries in file system) and if a cached copy of the gallery code is available, it returns that temporary copy instead of generating it on the fly, which saves all image file operations. If sigplus detects a temporary copy has expired, it regenerates it anew, which is only marginally more expensive than the case when caching gallery code is disabled.

In detecting whether a gallery has changed, sigplus uses a hash of all gallery parameters in determining the filename of the cached copy, and compares the timestamp of the directory in which images reside to the timestamp of the cached copy with the computed filename. This implies the following:

• Whenever you change some gallery parameters (e.g. preview image width or height), you can be sure sigplus will generate a new cached copy for the gallery.
• Whenever you copy new files to or remove existing files from the image gallery folder or update the labels file, sigplus will detect the cached copy has expired. Operating systems update the last modified time of a folder whenever files in that folder change. If images from a gallery come from a folder hierarchy, sigplus checks all folders involved. The labels file is treated as a special case because when you edit the labels file, you expect the changes in image title and description to be applied even if you did not actually place new images in the gallery folder or deleted existing ones.

Terminology explained

To help you find the settings you need and decipher any error messages you may encounter, this section contains explanation for common terms in the sigplus vocabulary.

Folders

• The image gallery folder is the folder you specify with the {gallery}folder{/gallery} activation tag. An example is birds, which is set with {gallery}birds{/gallery}.
• The image base folder is the folder you specify in the administration back-end as a configuration option. An example is images/stories, which corresponds to the usual article image folder of a Joomla installation.
• The preview image folder and the thumbnail folder are created inside the cache folder if cache usage is on (default), or the image gallery folder if cache usage is off. Supposing cache usage is off, the image gallery folder is birds, the base folder is images/stories, and the preview image and thumbnail folders are preview and thumbs, respectively, the preview images and thumbnails will be generated in the directories joomlaroot/images/stories/birds/preview and joomlaroot/images/stories/birds/thumbs. Supposing cache usage is on, you find generated preview images and thumbnails in joomlaroot/cache/preview and joomlaroot/cache/thumbs regardless of image gallery folder.
• The full-size image folder is optional and is always a subfolder of the directory where the images resize. It stores high-resolution image versions that are intended for printing and not web viewing. When the user clicks the download button in the pop-up window or in the overlay caption, an image from the full-size image folder will be served if one is available.

Gallery layout

Depending on the value of the back-end setting Gallery layout or the inline parameter layout, sigplus uses one of the two different layouts:

• With flow layout, images are rendered inline as if they formed part of a text; images are arranged side by side, close to one another. Like regular text, this alignment lets the series of images 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. This layout is very flexible as it accommodates to container and browser window size but does not permit an image slider. From the way this layout mode works, it follows that it is not possible to set an explicit number of rows and columns, and such settings are ignored.
• In contrast, 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 the table. A gallery that uses fixed layout never breaks into multiple lines automatically (but can be configured to render in the specified number of rows) and may be partially hidden if its parent container does have enough space for the gallery to display. Navigation controls are activated if the number of images to display is greater than the product of row count and column count.

In sigplus version 1.2.x, flow layout would be activated when Thumbnail count or the inline parameter count was set to 0, and fixed layout would be used otherwise.

Acknowledgements

This plug-in incorporates the MooTools-based Slimbox and the jQuery-based Fancybox, prettyPhoto, Sexy Lightbox 2 and Slimbox 2 lightbox pop-up engines. In addition, the developer has used prettyGallery and Easy Slider as inspiration for the standard image slider in sigplus.

Translations

sigplus is currently available in the following languages (both front-end and back-end):

• English
• Dutch (courtesy of José Nieuwenhout)
• French (courtesy of oweb)
• German (courtesy of Robert Sonnabend)
• Hungarian
• Portuguese (courtesy of António Correia)
• Russian [1.2.x only] (courtesy of Basil Guskov aka BasiLka)
• Slovak (courtesy of Libor Gabaj)
• Spanish [1.2.x only] (courtesy of Pedro Martín and Andrés Escudero)

Should you want your own language included in sigplus by default, please apply as a maintainer for the respective translation by sending an e-mail to This email address is being protected from spambots. You need JavaScript enabled to view it..