jAlbum Mirage Skin
User’s Guide
Version 11
14 May 2024

1

1 Overview
Most of the jAlbum skins are intended to show photograph albums. However, I needed to show an artist’s portfolio, and therequirements are a bit different. Without going into the philosophy, let’s just say that I felt a new design was needed.
Although Mirage was originally intended to display art, it also works well for photo albums, as long as you don’t want toshow photo meta-data (e.g. aperture, focal length). Since its original release, its scope has expanded considerably, and it canhandle diverse requirements.
These are the main features:
 Albums are compliant with HTML5, and they display correctly in all the major web browsers.
 An album can contain:o Images (JPG, GIF, PNG).
o Videos, YouTube, Vimeo, PDF files. These are embedded, so that they blend with the album’s overall
appearance.
o Thumbnail links to other albums. Each linked album can be created with any skin. This allows you to easily
combine multiple albums (or portions of albums) into a master album.
o jAlbum web locations. This allows you to include links to external content that complements your photocollection.
 Slide pages:o Since art looks best without distractions, each image appears on its own page, without thumbnails of otherimages. There are navigation buttons as well, but these are kept out of the way.
o Optionally, each page can contain up to 17 clickable thumbnails (“variants”) that are related to the main
image. E.g. these could be magnified details, the artwork in its frame, views from different angles if it is3-dimensional, or the artwork at different stages of completion. A variant can be any supported file type.
o The variants on a slide page can play in a slide show.
o A smaller image can be superimposed over or beside the main image. Typically, this shows a magnified
portion of the main image, to emphasise fine details.
o A panoramic image is wider than regular images, and can be scrolled horizontally.
o An image can be zoomed (using Zoomify or OpenSeadragon), so that you can see fine details.
 Index pages:
o The number of columns can be automatically adjusted, so that the thumbnails fit any browser window.
o Each folder is depicted by a “folder icon” that contains an embedded thumbnail of any local image.
o A “For Sale” or “Sold” label is superimposed on the thumbnails of paintings that are for sale.
o A “New” label is superimposed on the thumbnails of new album objects.
o Multiple index pages are supported (by setting “number of rows” to a non-zero value).
 While browsing an album, images in the next slide are pre-loaded. This eliminates the pause while an image isdownloaded.
 There are many options to customise the album’s appearance.
 Swiping is available on mobile devices.
 44 styles are included.

2 Why use the Mirage skin?







If you want to create an art gallery, I think this is the best available skin.
With any skin, it is possible to combine multiple albums into a master album, but this is complicated. Mirage
simplifies this task, by using Windows shortcuts or Internet shortcuts in the jAlbum GUI, to include your otheralbums (or portions of albums). This approach also avoids duplication of the album images.
The “variants” feature allows a slide page to contain thumbnail links for related images, videos and web pages.
This provides a more focussed view than an index page.
The “superimposed” feature allows you to combine a main image and a secondary image on the same page. You
won’t want to use this regularly, but on occasion it can provide extra impact.
I have tried to make the skin easy to use, and to prevent confusing errors during album generation.
I will continue to support the skin. If it doesn’t meet your expectations, let me know, and I will try to fix it.

2

3 Sample Albums
On the jAlbum site, go to the Mirage Skin and open the sample album. This contains a “demo” album that shows
many of the skin’s features. This “master album” links to real albums that have been created with the Mirage skin.

4 Limitations






This skin requires jAlbum 11.6.17 or later.
All testing has been done on Windows 10, Linux Mint and Android 12+, with◦ Microsoft Edge
◦ Firefox◦ Chrome◦ OperaIf you find any incompatibilities with any operating systems or web browsers, your suggestions are welcome.
Your Java version must be at least 8.
The following jAlbum features are not supported:o Link to originals via scaled images.

5 Additional Software
The following third-party software is distributed with Mirage. You may want to install newer versions as they become
available, although a newer version may be incompatible with Mirage.

5.1 JavaScript Libraries
Mirage automatically detects newer installed versions.
Name

Web site

Installed as

jQuery 3.7.1

jQueryMirage\res\jquery-3.7.1.min.js

jQuery Touch Events 2.0.3

jQuery Touch Events

Mirage\res\jquery.mobile-events.min.js

HTML5 Boilerplate 9

html5boilerplate.com

Mirage\res\main.css
Mirage\res\normalize.css

ImagesLoaded 5

imagesloaded

Mirage\res\imagesloaded.pkgd.min.js

OpenSeadragon 4.1

OpenSeadragon

Mirage\res\openseadragon.min.js
Mirage\res\openseadragon.min.js.map

Name

Web site

Installed as

Apache Commons IO 2.15.1

commons.apache.org/
proper/commons-io

Mirage\lib\commons-io-2.15.1.0.jar

JDOM 2.0.6.1

jdom.org

Mirage\lib\jdom-2.0.6.1.jar

json simple 4.0.1

json-simple

Mirage\lib\json-simple-4.0.1.jar

jsoup 1.17.2

jsoup.org

Mirage\lib\jsoup-1.17.2.jar

OpenJDK Nashorn 15.4

org.openjdk.nashorn

Mirage\lib\nashorn.jar

WindowsShortcuts

github.com/codebling

Mirage\lib\windows-shortcut.jar

5.2 Java Libraries

36 Instructions
This section describes how to create an album, with special emphasis on the Mirage features. For additional information
about how to use the generic jAlbum features, refer to the jAlbum documentation.

6.1

Album Preparation

Create a folder; this will be the “Image Directory” when you create the jAlbum project. Optionally, create subfolders; in the generated album, the contents of each sub-folder will appear on a separate index page.
Populate the album with image, video, pdf files, Windows shortcuts and Internet shortcuts, by moving the files into
the Image Directory and its sub-folders. Alternatively, if you want to leave these files in their original locations,
you can link to them later (see section 6.2).

6.2 Album Creation











Open jAlbum. Create a new project.
Select the Mirage skin. Select the style.
Populate the album by dragging folders and files into the jAlbum window. To create a link (instead of replicating
the file), press the ctrl key while dragging; “linked” files are identified by a “shortcut arrow” in the bottom left
corner.
Optionally, for each folder and slide, adjust the Mirage settings to customise its appearance (see Appendix 2).
Optionally, create variants and superimposed images:o On a slide page, in addition to the main image, you can display some “variants”. Within jAlbum, rename up to
17 files in the same folder (these can be any supported file type), so that they are named the same as the main
image, followed by “_1_” through “_17_”.
E.g. If the main image is “abc.png”, a variant could be “abc_1_.jpg”, “abc_2_.mp4” or“abc_9_.url”.
o On a slide page for an image file, you can superimpose a smaller image over or beside the main image. Within
jAlbum, rename an image in the same folder, so that it has the same name as the main image, followed by“_s_”.
E.g. If the main image is “xyz.jpg”, the superimposed image could be “xyz_s_.gif”.
o Each variant or superimposed image will be shown on its related slide page, not on the index page.
o The “overlap” setting allows you to adjust the superimposed image’s horizontal position (see Appendix 2).
Optionally, use the jAlbum editor to:o Create a comment for each folder. This will appear on the index page above the thumbnails.
o Create a title for each folder. If this is omitted, the title will be deduced from the folder name. If you don’t
want this to be displayed, choose the “Hide title” setting (see Appendix 2).
o Create a title for each image, video, etc. If this is omitted, the title may be deduced from the file namedepending on the “Label type” setting (see Appendix 1).
o Create a comment for each image or video.
o Choose a thumbnail image for each folder. Alternatively, to select a thumbnail image from a different folder,select an image in the folder’s Mirage settings. If you don’t choose a thumbnail image, Mirage chooses animage from within the folder.
Optionally, customise the settings in “Album Settings / Mirage” (see Appendix 1).
Make the album.
o If there are any errors in the album’s structure or settings, error messages are shown, and the album is
incomplete; correct the errors and re-generate the album.
o Warning messages do not prevent the album from being generated. Correct them if necessary.
o You can browse all messages for the current session in the System Console (F7 key, or click on “Tools /System Console”).

6.3 Fine Tuning

After you have generated the album, and you have done some basic testing, review the options that are available in
the album settings. You may find some features that will improve the album’s appearance.
Section 7 contains instructions for customizing each file type.

4

7 File Types
This section describes the file types that Mirage supports. Mirage does not support all of the file types that jAlbum allows(e.g. audio files). If your project contains a file type that Mirage does not support, a warning message is shown during
album generation.

7.1

Image
Mirage supports JPG, PNG, GIF and BMP files.

7.2

Video
Videos play in an embedded player, so they conform to the look and feel of the Mirage skin.

7.3

PDF file
A local PDF file can be embedded or shown in an external PDF reader (by checking the “New window” setting).
A remote PDF file is configured as a Web Location (see 7.4). However, many web servers do not allow their PDF files
to be embedded in a web page in a different domain, so you may need to download it. If you encounter this restriction,
your slide page will contain a blank panel without an error message (an explanatory message is shown in the Web
Developer’s Console).

7.4

Web Location
This requires jAlbum 14.
A Web Location adds a web page to an album.
The web page can be:- YouTube video- Vimeo video- PDF file
- Remote linked album
To add a Web Location to an album:◦ Open the web page in a web browser.
◦ Drag the URL into the jAlbum Explorer window.
◦ If the Web Location is an album, check “Album” in the Mirage settings. It isthen shown as a folder on the index page.
◦ The remote web page may have been configured to prevent embedding in a
web page in a different domain. If the web page is blank, check “NewWindow” in the Mirage settings; this causes the web page to be displayed ina separate tab outside the album.
◦ Optionally, select a thumbnail in “Image URL”. Leave this empty for
YouTube or Vimeo; it will be calculated automatically.
◦ Optionally, change the file name or title.

7.5

Windows Shortcut
A Windows Shortcut represents either: A linked album in a master album. This can also be accomplished with an Internet Shortcut (see 7.6), but aWindows Shortcut is easier.
 A tiled Zoomify image.
To add a Windows Shortcut to an album, do the following.
 In File Explorer, right click on an album folder or an“index.html” file. Click on “Copy”.
 Right-click on the project’s “image directory”, or one of its subfolders. Click on “Paste Shortcut”.
 Optionally, rename the shortcut, so that it has a more appropriate
name. Do not give it a suffix; it has a hidden suffix “lnk”.
 In jAlbum, open the album project. The shortcut is automatically
added to the project. Select its thumbnail image in the5

“Thumbnail” setting. (Hint: if the shortcut links to a Mirage album, Mirage automatically uses the same thumbnail
as in the linked album).
Limitations: Navigation to the linked album uses a relative path. If you intend to publish a master album and its linked albums,
the web site must have the same relative folder structure; otherwise you will not be able to navigate to the linked
albums.
 A Windows shortcut is represented by the same icon as an Internet shortcut. If you prefer to use thisicon instead, apply the following change to “jAlbum\system\filetypes.xml”.
Replace<type name="Link" icon="url.png"><ext>url</ext><ext>lnk</ext></type>with<type name="Link" icon="url.png"><ext>url</ext></type><type name="Shortcut" icon="shortcut.png"><ext>lnk</ext></type>

7.6

Internet Shortcut
An Internet shortcut represents:
 A linked album in a master album.
 A web page.
 A tiled Zoomify image.
In jAlbum 14 and later, you should use a Web Location to attach a web page, since this is easier and it is portable toother skins.
To add an Internet shortcut to an album, do the following. These instructions are for a Windows 10 installation.
 Create an Internet shortcut.
o Open the album’s image directory in Windows Explorer.
o Open a web page or a local HTML file in a web browser. Drag the URL into the image directory.

Optionally, rename the shortcut, so that it has a more appropriate name. Do not add a suffix; it has a hidden suffix“url”.
Open the Internet shortcut, and make sure that it opens the correct web page or album in the web browser.
In jAlbum, open the project. The Internet shortcut is
automatically added to the project. Change its settings:
o “Thumbnail” identifies the thumbnail image. (Hint: if theshortcut links to an album’s sub-folder, Mirage
automatically uses the same thumbnail as in the linked
album).
o If the shortcut refers to an album on a web site, check“Album” to depict it as a folder on the index page.

Limitations: A local URL (i.e. a file on your hard drive) must be an album
index page or a Zoomify image (see section 7.9). This URL canrefer to either the folder, or the index.html page inside thefolder. Other types of local URL are not supported.
 A linked album must not be a variant.
6



7.7

Navigation to a local URL uses a relative path. If you intend to publish a master album and its linked albums, theweb site must have the same relative folder structure; otherwise you will not be able to navigate to the linked
albums.

YouTube Video
A YouTube video is treated as a special type of Web Location or Internet shortcut. The video is shown in the YouTube
iframe player, which is embedded in a slide page. Thus the video is integrated into the album, but it is streamed fromthe YouTube web site. To view the video, you must have an active Internet connection.
To add a YouTube video to an album:• On the YouTube website, open the video.
• In jAlbum 14 or later, create a Web Location, as described in section 7.4.
• In older versions of jAlbum, create an Internet Shortcut, as described in section 7.6.
• Make the album. The thumbnail is downloaded automatically.

7.8

Vimeo VideoA Vimeo video is treated as a special type of Web Location or Internet shortcut. The video is shown in the Vimeo
Player, which is embedded in a slide page. Thus the video is integrated into the album, but it is streamed from theVimeo web site. To view the video, you must have an active Internet connection.
To add a Vimeo video to an album:• On the Vimeo website, open the video.
• In jAlbum 14 or later, create a Web Location, as described in section 7.4.
• In older versions of jAlbum create an Internet Shortcut, as described in section 7.6.
• Make the album. The thumbnail is downloaded automatically.

7

7.9

Zoomify
Use Zoomify to zoom an image. The maximum zoom shows part of the imageat its original size, so this technique is most effective for a high-resolution
image. It is available in Windows and Mac versions.
Zoomify is available in four versions. The Free, Express (paid) and Pro (paid)versions are supported.
A Zoomify image is either a folder of image tiles or a zif file. The free version
does not support zif files.
7.9.1 Zoomify integration• Download Zoomify.
• [Free only] The Zoomify Viewer is broken; it violates security
restrictions in modern web browsers. Instead, tiled images are viewed
in OpenSeadragon, which is included in Mirage.
• [Express and Pro only] Copy these files to the project's “res” folder orthe Mirage “res” folder:• The Zoomify Viewer (ZoomifyImageViewerExpress-min.js or
ZoomifyImageViewerPro-min.js)• The Assets folder. This contains the skins. To speed up album generation and deployment, exclude theskins that your project does not use.
• [Express and Pro only] If your jAlbum version is less than 13.7, you must add support for zif files. Edit
“jAlbum\system\filetypes.xml”, and add this entry:<type name="Zoomify image" icon="image.png"><ext>zif</ext></type>•[Express and Pro only] In the Mirage album
settings, open the “Add-ons” tab. Select theZoomify skin and enter the Zoomify parameters.

7.9.2 Tiled Image
These images require jAlbum 17.1
To add an image to a project:• Run the Zoomify converter. This creates a “Zoomify Folder” that contains image tiles.
• Create a shortcut for the Zoomify folder (in Windows, create a Windows shortcut [see section 7.5]; on a Mac,
create an Internet shortcut [see section 7.6]). Move this to the project's image folder.
7.9.3 zif file [Express and Pro only]
These images require jAlbum 30.
••••

This is easier to use than a tiled image.
Album generation and deployment is faster.
Skins allow customisation.
A zif file cannot be viewed locally. You must upload the album to a web server to view it.

To add an image to a project:• Run the Zoomify converter. This creates a zif file. Move this to the project's image folder.

87.10 Folder
On an index page, each sub-folder is shown as athumbnail image inside a folder icon. You can choose a
thumbnail image either in the jAlbum Explore window(“Use as folder thumbnail”) or in the folder’s Mirage
settings.
Also, refer to the Mirage album setting “Show folder
icons”.
If no thumbnail is selected, the sub-folder is justrepresented by a folder icon.

or98 Special Features and Techniques
8.1

Build a Master AlbumYou can build an album that contains embedded “linked albums”. Each of the linked albums is generated separately byjAlbum. A “master album” then combines these albums, so that they seem to be a single album.

8.2



Steps:o In jAlbum, create each of the “linked albums”. These can use different Mirage styles or other skins.
o For each linked album, create a Windows Shortcut (see section 7.5) or an Internet Shortcut (see section 7.6). A
shortcut can link to any of the album’s index pages; it doesn’t have to be the top index page.
o In jAlbum, create a “master album”, containing these shortcuts. This produces an index page containing
thumbnail links to each of the linked albums.
o If a linked album uses a different skin, there is no mechanism to return to the master album, so choose the“New window” setting (see Appendix 2). This causes the linked album to open in a separate tab or window.

Runtime behaviour:o If a linked album was built by Mirage version 4 or later:
 Its “back” buttons are automatically changed, so that they return to the master album. Thus the linked
album behaves as if it is part of the master album.
 The automated return mechanism only works for the first link. If a linked album links to another album,
this album opens in a separate window. You can change this behaviour by choosing the “New window”
setting (see Appendix 2) for the first link; this disables the automated return for the first link, and enables
it for the second link.



Since the multi-album structure is created via links, images are not duplicated. Change a linked album, and thechanges automatically appear wherever it is linked.



For an example, refer to the sample album for the Mirage skin on the jAlbum site.

Caution: The master album uses relative paths to navigate to the linked albums. Consequently, the folder structureof the generated albums on your local computer must be the same as on the web server where you publish thealbums.

Blank titles
If you want to hide an image’s title, set it to “&nbsp;” (i.e. the HTML code for “a non-breaking space”).

8.3

Effects
jAlbum provides two types of effect:
 Album Effects: These are applied to all album images. They are entered in the “Album Settings / Effects” window.
Most of these have been tested with Mirage.
 Image-specific Effects: These are selected in the “Effects” toolbar in the “Edit” window.
Effects are applied to the main images, variant images and superimposed images. If an effect changes an image’s size(e.g. by adding a border), Mirage automatically adjusts the position of other components, to ensure that the page layout
conforms to the Mirage design.

10

8.4

Variants and Superimposed Images
This example shows how variant and superimposed images appear. Rename an album object so that it contains themain image’s root name followed by the appropriate suffix (“_s_” for superimposed images; “_1_”, “_2_” … forvariants). Mirage automatically positions all of these objects on the same slide page.

Index Page
jAlbumSlide Page

11

8.5

Variant Slide Show

On a slide page that contains variants, a slide show canrun automatically when the page is opened. To enable
this, open the “Mirage Slide Pages” settings:• Check the “Slide Show” checkbox.
• Set the delay; each image is displayed for thisnumber of seconds.
Features:• The slide show handles most types of album
object.
• The slide show can be disabled for a specificslide page, in its “Mirage” custom settings panel.
• The image is displayed for the “delay” period.
• Videos, including YouTube and Vimeo, are shown until the video finishes. The slide show then moves on to thenext variant.
• If the slide show loses focus (e.g. the user opens a different window), it pauses. It resumes when it re-gains thefocus.
• If the variant is a link to a web page, this opens in a separate browser tab and the slide show pauses. To resume theslide show, select the original tab.
• To pause the slide show, click the current variant’s thumbnail.
• To skip the current variant, click the next variant thumbnail.
• To stop the slide show, click any other variant thumbnail.
• To restart the slide show, click the browser’s refresh button.
• To change the delay, click the Help button and adjust the delay. This affects all of the user’s albums on the current
web server.

8.6

Breadcrumbs

The path from the top folder can be shown at the top leftof each page. This can be useful in a multi-level album,
so that you do not lose track of how you reached thecurrent page (especially if “Chain directories” is enabled).
Click a breadcrumb to return to that index.
This can be enabled in the “Mirage / General” settings.

12

9 Publishing
After uploading an album to the jAlbum web site, edit the album's settings, and select “Disable the automatic mobile
version for this album.” This ensures that the album displays correctly on mobile devices.

10 Feedback






Mirage supports multiple languages. If your language is not supported, copy “texts\texts.properties” to“texts_xx.properties”, where xx is your ISO language code, and translate the text strings in this file. Send me thisfile, and I will include it in the next upgrade.
If you want to comment on the skin, and you don’t want a reply, go to the Mirage skin page. Your appreciation andobjective criticism are welcome.
If you have any ideas for improving the skin, I welcome your suggestions. On the jAlbum site, go to the Otherskins forum.
I would like to know where this skin is used. If you have published a Mirage album, or you have copied some ofits features to another skin, please let me know. Alternatively, post your album in the User Album Showcase, andmention “Mirage” in its title.
If you have developed a Mirage album that you would like to share, send me its URL, a thumbnail and a short
description, and I will link to it from the Mirage Sample Album.

13

11 Troubleshooting

After re-generating an album with a different Mirage style, some of the buttons and colours are from thepreviously selected style.
o In Firefox, you need to refresh the page. Until you do this, some components from the previous version of thealbum will be shown. You may have to refresh more than once.

If you encounter any other problems with this skin, post a message in the Other skins forum. I will do my best to helpyou.

12 Known Issues
If you know of solutions or workarounds to these problems, please let me know via the feedback channels.


If you open a Mirage project, then change to a different skin, then re-select Mirage, the Mirage-specific album
settings revert to their default values. This is intentional jAlbum behaviour, so don’t do it.

14

Appendix 1: Album Settings
The “Album Settings” window contains a “Mirage” tab, where you can enter settings that are specific to the Mirage skin.
These default to the most useful choices (the following links show the default settings), so you can generate an album
without changing any of these settings. However, to get the most out of the skin, you should review and customise thesesettings.

GeneralIndex Pages
Header/Footer
Thumbnails
Links
Slide Pages
Add-ons
This documentation can also be accessed from the Help button in the jAlbum Settings.

15

Appendix 2: Slide / Folder settings
In the “jAlbum Edit” window, a “Mirage Custom” panel
contains settings for the current album object that are
specific to Mirage. These default to the most usefulchoices, so you can generate an album without changing
any of these settings. However, to get the most out of theskin, you should review and customise these settings.
Mirage Settings - Slide / Folder

This documentation can also be accessed by clicking the Help button in the “Mirage Custom” panel (jAlbum 12.3.5 andlater).

16

Appendix 3: Settings examples
This section shows pages from a sample album, and describes the required Mirage settings.

Index Page

Album settings

Slide / Folder settings• “Mirage / General” taboLabel type is set to “Label”. For each image that
does not have a title, the label is taken from its
file name (e.g. Feel.jpg).

• “Mirage / Index pages” tabo The header graphic was selected by entering its
o
o
o
o
o

path in Header image.
Centre the header image on and Centre thetitle & comment on are both set to “Window”.
A 2px border is drawn around each thumbnail.
This is specified in the Border width setting.
Show folder labels and Show other labels arechecked. This causes a label to be shown undereach thumbnail.
7 Links were entered, and Menu bar isselected.
Show “for sale” icons is checked.
17oFor “Feel” and “Gerard”, a price has beenentered. This causes the “For Sale” icon to beshown.

oThe “New” icons are added by checking New
for “Derwentwater” and “Gerard”.

Slide Page

Album settings

Slide / Folder settings• “Mirage / General” tab
o

o
o
o
o
o

The header text comes from:
Medium: Gouache on Paper
Size: 21.25 x 29.25 “ (540 x 743 mm)
Date: 2006
Price: 1250, unframedo

The email button appears automatically when a
Price is entered.

oThere is a tooltip for each image:
Tooltip: Full Painting
Tooltip: Details
Tooltip: View frameoFor each variant, on the “General” tab, there is atitle:
Title: Detail
Title: FramedThis is shown under each thumbnail.

o

The horizontal position of the superimposed
image “Feel_s_.jpg” is adjusted. The value isthe percentage of the main image that isoverlapped (between -100 and 100; a value 0
centres the image).
Overlap: 85

Label type is set to “Label”. Since the image
does not have a title, its label “Feel” was takenfrom its file name (Feel.jpg).

• “Mirage / Slide pages” tabooFor the main image, Show title is checked. This
causes the title “Feel” to be shown.
A 2px border is drawn around the main image.
This is specified in the Border width setting.
Thumbnail position is set to “Left”. This
positions the column of variant thumbnails on
the left.
Thumbnail dimensions is set to “50 x 50 px”.
This limits the height and width of the variant
thumbnails.
Variants / Show title is checked. This causes atitle to be shown under each thumbnail.
Currency is set to “£”. This appears in theprice.

18

Appendix 4: Keyboard, Mouse and Touch Screen Navigation
You can navigate through an album by using the mouse, keyboard or touch screen. The following commands are available.
Index Pages

Slide Pages

Keyboard navigation may not work on a slide page that contains a PDF file.

19

Appendix 5: Development team
Chris Twist:

Designer, Programmer

Translators:

French - Eyael

20