Custom thumbnail templates

This article describes how you can build custom thumbnail templates for search results, galleries, lightboxes and so on. There are five different viewing styles that you can configure via Site configuration, Thumbnail pages. The modal lightbox page uses a grid type thumbnail. The code editor provides code examples for each of the styles (grid, list, small, large and flow), and for the modal lightbox thumbnails – that you can use as a starting point. If you load the first example code for one of the thumbnail templates and save it without making changes, then the client facing result is the standard result (i.e. what you get without customized thumbnail templates).
There is also example code that you can use if you have configured your pages to use Google Icons instead of button images.

Note that you can change just one or a few viewing style templates. You don’t have to make a custom template for every viewing style if for instance you just want to change the large thumbnail template.

Before you begin

Recommended reading: Thumbnail hover text macro, Using the code editor, Infradox XS customisation.

Depending on what you want to achieve, there may be no need to make custom thumbnail templates. A lot can be done by chosing settings in back office and/or changing the CSS, adding Javascript and so on. Custom templates offer more flexibility and may result in better performance (by removing what you don’t need), but the caveat is that future XS updates may interfere with your custom templates. I.e. you may have to make changes to your custom templates as a result of a version update.

Make sure that you understand how the XS tags work, before changing the templates described here. You can find more information in the article Infradox XS functions, tags and conditions. You also need to know about constants, locales and repository properties before you start working on the thumbnail templates.

Configuring related settings

It is recommended that you start configuring the thumbnail pages before you use the code editor to make template changes – because the settings will also affect your custom templates. Note that the default templates are complex and use several classes so that everything can be configured with back office settings without making code changes. If however you are going to make code changes, then the code can be simplified (and as a result smaller and faster) by removing classes and/or HTML you don’t need for your specific requirements.

The above screenshot shows where you can configure the thumbnail templates in backoffice

Google icons

If you decide to use Google icons, then make sure to set this up first. You can then use the example templates that are ready for Google Icons as a starting point. In Site configuration, go to Website style and open the Button images section. If you haven’t changed the settings before, then you’ll see the default Google icon names already filled in. Select the Google icons option and save your settings. You can of course specify different icon names and codes but this is beyond the scope of this article. You can find more information here. Note that the icon names are followed by a colon (:) and a code. The code is used for older browsers, specifically MSIE 9 and lower.

The above screenshot shows the set up for Google Icons

The Grid template explained

This paragraph explains how the grid thumbnail template works and how it can be changed. The other templates are more or less the same, and you should be able to work on those once you have successfully changed the Grid template.

Note that the classes and attributes (set with tags) are important because the script “looks for” elements having – or not having – certain class names and or attribute values.

In the code editor, select Grid (90) in the dropdown box at the top. Then click “Load example” and load the default code into the editor.

The first line looks like this:

<div class="gridModeBox tfbox supp<?xs slot('supplierid') ?> 
<?xs slot('rf','boxrf','boxrm') ?>" id="slot_<?xs slot('nr') ?>">

The HTML output of this line may look something like this:

<div class="gridModeBox tfbox supp100 boxrm" id="slot_1">

The tags used in this code are:

<?xs slot('supplierid') ?> // outputs the supplier id 
<?xs slot('rf','boxrf','boxrm') ?> // outputs boxrf if the file is a RF file, otherwise it outputs boxrm
<?xs slot('nr') ?> // outputs the number of the thumbnail on the page. This is an important element for the XS script, you should not remove it.

The second line:

<div class="vicon<?xs slot('mediatype') ?> trans50"></div>

uses the ‘mediatype’ tag. This will output 0 for images, 1 for video, other numbers for other media types. If your website uses only images, then this line can be removed, otherwise it should be there because it’s used to position video players and icons.

Important: starting with version 30, the above div (with class “vicon”) must be moved inside the div with the class “thumbnail”. E.g.

<div class="thumbnail na<?xs slot('unavailable') ?>" id="<?xs slot('api_uid') ?>" br="<?xs slot('br','1','0') ?>" mt="<?xs slot('mediatype') ?>" rnk="<?xs slot('ranking') ?>">
     <div class="vicon<?xs slot('mediatype') ?> trans50"></div>
     <a class="filepreview" href="<?xs slot('previewurl') ?>">
         <img decoding="async" class="thmbimg" src="<?xs slot('tcache') ?>" alt="<?xs slot('alttext') ?>" title="<?xs slot('titletext') ?>" /> 
     </a>
</div>

The following div is the container of the thumbnail:

<div class="thumbnail na<?xs slot('unavailable') ?>" id="<?xs slot('api_uid') ?>" br="<?xs slot('br','1','0') ?>" mt="<?xs slot('mediatype') ?>" rnk="<?xs slot('ranking') ?>">
...
</div>

It uses the following important tags:

<?xs slot('unavailable') ?> // outputs 1 if the file is unavailable on the server
<?xs slot('api_uid') ?> // outputs the unique id, e.g. 0_00082881 - where 0 is the API id, and the 2nd part is the file id
<?xs slot('br','1','0') ?> // outputs 1 if the file has a blocking restriction, 0 if it doesn't.
<?xs slot('previewurl') ?> // outputs the complete preview url
<?xs slot('tcache') ?> // outputs the path to the normal sized thumnail in the tcache folder

The next div in the template holds html that either displays when hovering only or always – depending on what you have configured in back office.

<div class="buttononlyhover matrixt hover<?xs rproperty('tmb_hover','0') ?>">

<?xs rproperty('tmb_hover') ?>

The above tag outputs 0 or 1, depending on what you have configured with regards to hovering. So the output will look like either

<div class="buttononlyhover matrixt hover0"> or <div class="buttononlyhover matrixt hover1">

The above div contains elements for thumbnail buttons, file id’s, restriction info and so on – which is explained below.

The flow template

The flow template uses the tag flowwidth. It outputs HTML required for the thumbnails based on settings you have configured in Back office:

<?xs slot('flowwidth',{'for':'style'}) ?> // outputs e.g. style="width:250px" or style="height:250px"
<?xs slot('flowwidth',{'for':'image'}) ?> // outputs e.g. "width:250" or "height:250"

As you can see this tag outputs the complete HTML, have a look at the template below to see how the tag is used:

<div class="flowbox2 grid-item grid-item--width<?xs slot('fileorientation') ?> <?xs slot('rf','boxrf','boxrm') ?>" id="slot_<?xs slot('nr') ?>" <?xs slot('flowwidth',{'for':'style'}) ?>>
	<div class="thumbnail na<?xs slot('unavailable') ?>" id="<?xs slot('api_uid') ?>" br="<?xs slot('br','1','0') ?>" mt="<?xs slot('mediatype') ?>">
		<a class="filepreview" href="<?xs slot('previewurl') ?>">
			<img decoding="async" class="flowimage thmbimg" src="<?xs slot('mcache') ?>" title="<?xs slot('titletext') ?>" alt="<?xs slot('alttext') ?>" <?xs slot('flowwidth',{'for':'image'}) ?>>
		</a>        
	</div>
	<div class="flowbuttons searchlinks">
		<ul class="buttons b<?xs slot('api_uid') ?>">
		<li class="lightbox"><a title="<?xs constant('cThmbtolightbox','','1') ?>" href="javascript:thumbnailtools(0,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);"></a></li>
		<li class="order <?xs slot('ba','noagents','agents') ?>"><a title="<?xs constant('cThmbtocart','','1') ?>" href="javascript:thumbnailtools(1,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);"></a></li>
		<li class="preview"><a class="filepreview" title="<?xs constant('cThmbViewdetails','') ?>" href="<?xs slot('previewurl') ?>"></a></li>
		</ul>
	</div>
</div>

Constants

Like all other templates, constants are used to output text depending on the active locale (language). Even if you don’t need support for multiple user interface languages, it is still recommended to use constants because it allows you to manage texts in a central place. Simply change the value for a constant and it will be changed everywhere automatically. To find out more about managing constants, read the article: Website constants.

The constants used in the thumbnail templates can have a 3rd parameter, e.g.

<?xs constant('cThmbtolightbox','','1') ?>

This 3rd parameter can only be used in thumbnail templates. It tells the parser to replace the constant with data from the repository. It is best to keep these tags as they are in the example code.

<li class="fileid<?xs rproperty('tmb_refer','0') ?>"><?xs slot('contentreffield') ?></li>

The above line uses the tag

<?xs rproperty('tmb_refer'),0') ?>

to output either fileid0 or fileid1 as CSS class name. Class name fileid0 is then used to hide the element (in this case a list item).

Restriction icons

To display the restriction icons, the following logic is used:

<li title="<?xs constant('cRights_RF') ?>" style="display:none" class="rightsicon rightsicon<?xs slot('rf','rf','norf') ?> rmrf<?xs rproperty('con_rht') ?>"></li>

The HTML output may look something like this for an RF file:

<li title="Royalty Free" style="display:none" 
class="rightsicon rightsicon rf rmrf1">
</li>

<?xs rproperty('con_rht') ?>

The above tag outputs 1 if you have configured “Rights info” to display on thumbnail pages (Site configuration, Metadata display, General settings).
XS uses CSS and Script to hide or show elements based on the HTML output, e.g. rmrf1 to display the info, rmrf0 to hide it.

If for example, you decide not to use these settings because you always want it to show – then you can replace the tag with a hard coded value. E.g.:

<li title="<?xs constant('cRights_RF') ?>" 
class="rightsicon rightsicon<?xs slot('rf','rf','norf') ?> rmrf1">
</li>

In the above example, style=”display:none” has been removed and the class rmrf1 is hard coded.

<?xs slot('contentreffield') ?>

The tag above outputs the value for the field that you have configured as the field that has the file ids. This can be configured via Website Configuration in back office.

You may have to remove most of the standard HTML if you need to implement a thumbnail template that is completely different. This is possible too.

<?xs slot('caption',{maxlen:100,add:'...'}) ?> 
// outputs max 100 positions of the caption, not truncating words. Adds ... if the caption is truncated (nothing if the caption is shorter than 100 characters)

<?xs slot('creditnamefield') ?> 
// outputs the value of the field that is configured as the credit field, e.g. the photographer name

The grid thumbnail template used for the modal lightbox

The modal lightbox uses a grid type layout for the thumbnails by default. You can create a custom version for this template too. To do this, select “Modal lightbox (100)” in the Code editor drop down. Then load the example template into the editor with the “load example” button at the top.

The template is mostly the same as the normal grid styke template, but it has a few different classes and it uses tags that may be used in this template only. These are:

<?xs slot('oncartpage') ?>

Outputs 1 if the the lightbox is opened when on the cart page.

<?xs slot('lightboxpreviewurl') ?>

Outputs the URL to the preview page (or modal preview).

An overview of all the slot tags that you need to understand

<?xs slot('supplierid') ?>
Outputs the supplier id

<?xs slot('mediatype') ?>
Outputs the mediatype as a number, 0 for images, 1 for video, 2 for audio etc

<?xs slot('nr') ?>
Outputs the number of the thumbnail on the page starting at 1 for the one on the top left

<?xs slot('unavailable') ?>
Outputs 1 if the file is (temporarily) unavailable 

<?xs slot('api_uid') ?>
Outputs the unique file ID, the part before the underscore is the index of the API 

<?xs slot('ranking') ?>
Outputs the ranking value

<?xs slot('previewurl') ?> 
Outputs the full url to the preview page 

<?xs slot('fileorientation') ?>
Outputs 0,1,2,3 for Vertical, Horizontal, Square and Panoramic files respectively. Use only in the Flow template.

<?xs slot('flowwidth') ?>
Outputs the calculated image width based on the file's orientation. Use only in the Flow template.
Tags used to output text (these need to be configured via Site configuration, Thumbnail pages)

<?xs slot('alttext') ?> 
outputs the ALT text

<?xs slot('titletext') ?> 
outputs the TITLE text

<?xs slot('hovertext') ?> 
outputs the long text (e.g. used to display when hovering)

Tags for rights / restrictions

<?xs slot('rf','true','false') ?> 
outputs 'true' if the file is RF or else 'false'. The output values are just examples and can be anything. The templates use e.g. <?xs slot('rf','rf','norf') ?> to output class names.

<?xs slot('rm','true','false') ?> 
as above but for RM

<?xs slot('mr','true','false') ?> 
as above but for Model Release

<?xs slot('pr','true','false') ?> 
as above but for Proeprty Release

<?xs slot('rs','true','false') ?> 
outputs the first parameter if there are restrictions or else the 2nd parameter value.

<?xs slot('tr','true','false') ?> 
outputs the first parameter if there are restrictions for the user's territory or else the 2nd parameter value.
Tags for series / similar files / galleries

<?xs slot('seriespartof') ?>
outputs 1 if the file is part of a series (can also be used for similar files)

<?xs slot('seriesurl') ?>
outputs the full url to the series page

<?xs slot('seriesglbid') ?>
outputs the id of the series

<?xs slot('seriesfilecount') ?>
outputs the number of files that are part ofthe series

Tags for thumbnail files

<?xs slot('lcache') ?> 
path to the small (mini) thumbnail 

<?xs slot('tcache') ?> 
path to the normal (grid) size thumbnail

<?xs slot('mcache') ?> 
path to the large thumbnail - also used for hover previews

The html and code for the thumbnail buttons

If you have configured thumbnail icons to use images (not Google icons) then the buttons HTML will look like lines below. The CSS has background images configured.

<div class="searchlinks bhvr">
     <ul class="buttons b<?xs slot('api_uid') ?>">
     <li class="lightbox"><a title="<?xs constant('cThmbtolightbox','','1') ?>" href="javascript:thumbnailtools(0,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);"></a></li>
     <li class="order <?xs slot('ba','noagents','agents') ?>"><a title="<?xs constant('cThmbtocart','','1') ?>" href="javascript:thumbnailtools(1,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);"></a></li>
     <li class="preview"><a class="filepreview" title="<?xs constant('cThmbViewdetails','') ?>" href="<?xs slot('previewurl') ?>"></a></li>
     <li class="comp"><a title="<?xs constant('cThmbcompimage','') ?>" href="javascript:thumbnailtools(9,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);"></a></li>
     </ul>
</div>

If you use Google icons, then the buttons HTML needs to be changed (there’s a ready made example available to load into the code editor). Note that the links (<a>) have the class material-icons. And the link text is the icon code between square brackets. E.g. [cadd] for the add-to-cart icon. The icon codes are:

• [ladd] add to lightbox
• [lremove] remove from lightbox
• [cadd] add to cart
• [cremove] remove from cart
• [preview] preview
• [comp] download comp image
• [email] e-mail image

<div class="searchlinks bhvr">
     <ul class="buttons b<?xs slot('api_uid') ?>">
     <li class="lightbox"><a class="material-icons" title="<?xs constant('cThmbtolightbox','','1') ?>" href="javascript:thumbnailtools(0,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);">[ladd]</a></li>
     <li class="order <?xs slot('ba','noagents','agents') ?>"><a class="material-icons" title="<?xs constant('cThmbtocart','','1') ?>" href="javascript:thumbnailtools(1,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);">[cadd]</a></li>
     <li class="preview"><a class="filepreview material-icons" title="<?xs constant('cThmbViewdetails','') ?>" href="<?xs slot('previewurl') ?>">[preview]</a></li>
     <li class="comp"><a class="comp material-icons" title="<?xs constant('cThmbcompimage','') ?>" href="javascript:thumbnailtools(9,'<?xs slot('api_uid') ?>',<?xs slot('nr') ?>);">[comp]</a></li>
     </ul>
</div>

Examples

Example 1 – how to display the RF / RM icons

This example explains how you can display an icon to indicate that a file is RM or RF at all times while having hovering enabled.

1) Load the custom CSS into the code editor
2) Add the following CSS:

.rightsiconbox {
     float:left;
     width:20px;
     height:20px;
     margin-top:-15px;
     margin-left:2px;
}

This is the place holder div element in which the icon will be positioned. The div will be added underneath the thumbnail box later. In this example, it has a top margin of minus 15px to move it up. Note that what the CSS should look like for your particular situation depends of course on how you have configured the thumbnail templates and CSS. The above CSS is just an example.

3) Load the “Large” thumbnail template into the code editor
4) Underneath the div with the class “thumbnail” add the following code:

<div class="rightsiconbox">
     <img decoding="async" src="<?xs path('xscss') ?>/../images/1_0/<?xs slot('rf','RF','RM') ?>icon.png" />
</div>

The red box in the above screen shot shows where you need to add the html

<?xs path('xscss') ?>

The above tag outputs the relative path to the css folder. You need to go up one folder and then to the images/1_0 folder. Hence the .. in the html.

<?xs slot('rf','RF','RM') ?>

The above will output RF for RF files, or else RM. Therefore, the example below will output either RFicon.png or RMicon.png

<?xs slot('rf','RF','RM') ?>icon.png

You can of course use your own icons instead. Upload your images via Site configuration, Website files, Website artwork. You will then need to change the path accordingly.
For example:

<img decoding="async" src="/siteowner/artwork/artwork/<?xs slot('rf','myrficon','myrmicon') ?>.png" />

5) Change the other thumbnail templates as required.