This article discusses key concepts in sigplus terminology that are used extensively in the documentation, including the description for extension parameters.
Base URL
When you specify a relative path for the setting base folder on the plug-in configuration page in the administration back-end, sigplus prefixes relative image paths with the Joomla root folder and the Joomla site URL when building absolute paths or URLs. Consider the following example:
| Site root folder | /home/username/www/ |
| Site URL | http://example.com/ |
| sigplus base folder | images/stories |
| Activation tag in article | {gallery}birds{/gallery} |
| Folder to look for images | /home/username/www/images/stories/birds/ |
| URL to look for images | http://example.com/images/stories/birds/ |
As seen in the example, the image source birds given with activation tag {gallery}birds{/gallery} expands into images/stories/birds/, which is then prefixed with the base folder /home/username/www/ to arrive at an absolute path. Likewise, images/stories/birds/ is prefixed with the site URL http://example.com/ to arrive at http://example.com/images/stories/birds/.
When an absolute path (or a relative path including parent folder components ..) is specified for base folder in the administration back-end, however, the URL to prefix image paths with is no longer obvious. For instance, the following situation would produce an invalid URL:
| Site root folder | /home/username/www/ | |
| Site URL | http://example.com/ | |
| sigplus base folder | /home/username/images/ | |
| Activation tag in article | {gallery}birds{/gallery} | |
| Folder to look for images | /home/username/images/birds/ | |
| URL to look for images |
As apparent from the example, /home/username/images/ is not inside the Joomla site folder /home/username/www/ and hence neither a descendant of the umbrella URL http://example.com/. In this case, the configuration setting base URL cannot be left empty to have sigplus automatically determine base URL and therefore the URL to look for images. You must explicitly specify the URL associated with the folder /home/username/images/, which is typically a different domain or subdomain. For example,
| Site root folder | /home/username/www/ | |
| Site URL | http://example.com/ | |
| sigplus base folder | /home/username/images/ | |
| sigplus base URL | http://images.example.com/ | |
| Activation tag in article | {gallery}birds{/gallery} | |
| Folder to look for images | /home/username/images/birds/ | |
| URL to look for images | http://images.example.com/birds/ |
Image categories
To ensure maximum performance, sigplus classifies images into four categories in increasing order of detail:
- thumbnails,
- preview images,
- original images displayed in a pop-up window,
- and high-resolution images.
Thumbnails and preview images are typically generated by sigplus (based on the image to be displayed in the pop-up window) but images to be displayed and optional high-resolution images are to be uploaded by the site maintainer.
Image sizes
Images with high resolution (e.g. with size much larger than ~600x800 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.
Do not be deceived by file size, most image formats used on the internet, including JPEG, PNG or GIF, store images in a compressed format, which have to be decompressed in order for sigplus to open them. In the decompression process, they may inflate to many times their original file size. The only objective criterion to judge image size is to inspect image width and height. A typical digital camera takes images of several times the size of a computer display. It is recommended that you rescale these images to some more feasible size before uploading them to the server. (As a last resort, consult your system administrator to increase the PHP memory limit for you.)
As a compromise solution, sigplus has an option to upload high-resolution images into a dedicated folder (whose name defaults to fullsize). The following example illustrates a possible folder hierarchy:
/images/stories/fruit /images/stories/fruit/thumbs /images/stories/fruit/preview /images/stories/fruit/fullsize
In the example, the folder /images/stories/fruit/fullsize is where you would upload the original images taken with the digital camera without any modification, whereas the folder /images/stories/fruit would store downscaled versions of the original images.
When download access is set to public, or access is set to registered and the user is logged in, sigplus displays a download icon in the caption area and inside the lightbox pop-up window. When the user clicks the download icon, sigplus checks whether a high-resolution image version is available in corresponding subfolder (whose name is fullsize in the example). 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 (which has a high-resolution version) and /images/stories/fruit/banana.jpg for banana.jpg (which does not).
Retina displays
sigplus is retina-ready, or in other words, is compatible with displays whose device pixel ratio (dpr) is higher than 1, which includes many mobile devices. On these devices, each logical pixel is associated with more than one physical pixel. In order to fully utilize the physical capabilities of these devices, sigplus generates two sets of thumbnail and preview images, e.g. if you set the desired preview image size to 100×100, sigplus will generate both 100×100 and 200×200 images (assuming a dpr of 2), and will use the 100×100 version on desktop devices and the 200×200 version on many mobile devices, while the perceived relative image size (as compared to other page elements, e.g. text) will remain the same. (For the technically savvy, this is accomplished with the srcset attribute of the img HTML element.)
