Etalage instructions

View demo

# Etalage instructions

1. Example pages
2. Including the CSS
3. Including jQuery
4. Including the plugin
5. Applying the plugin
6. Head tag setup example
7. Plugin options
8. HTML setup
9. Customizing the CSS
10. Advanced: Callback functions
11. Troubleshooting

## Example pages

View the source of these samples to quickly learn/copy/experiment with the ways of including Etalage on your page.

- Absolute basic usage
- Using Etalage with Fancybox
- Using a custom element as zoom area
- Using callback functions
- Right-to-left language support
- Fancybox links without Etalage's default zooming area
- Initializing multiple instances with duplicate setups

## Including the CSS

The css file consists of both styling and functionality sections. It is required to make Etalage function.
Include it in the head tag before including the javascript. Example below.

## Including jQuery

Include an instance of jQuery. It is required to make Etalage function.
Include it in the head tag before including the plugin javascript. Example below.

## Including the plugin

Include either the minified version, or source version if you are editing it manually.
Include it in the head tag after including the css and jquery. Example below.

## Applying the plugin

Here you point out which element (html list) to apply the plugin to. Optionally provide plugin options.
See Plugin options for an example and full options list.

## Head tag setup example

<head>
<title>My first Etalage</title>
<!-- Include the Etalage CSS: -->
<link type="text/css" rel="stylesheet" href="css/etalage.css" />
<!-- Include jQuery: -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<!-- Include the Etalage plugin: -->
<script type="text/javascript" src="js/jquery.etalage.min.js"></script>
<!-- Applying the plugin when the document is ready: -->
<script type="text/javascript">
$(document).ready(function(){
// If your <ul> has the id "etalage":
$('#etalage').etalage();
});
</script>
</head>

## Plugin options

When you apply the plugin to your images, you can provide settings to your liking.
Example of applying Etalage with custom settings:
<script type="text/javascript">
$(document).ready(function(){
// If your <ul> has the id "etalage":
$('#etalage').etalage({
// These are the most common settings (because they are case specific)
thumb_image_width: 300,
thumb_image_height: 400,
source_image_width: 1200,
source_image_height: 1600,
zoom_area_width: 800
// Note: the last option does not end with a comma
});
});
</script>

Name | Description | Default
--- | --- | ---
align | Align of the Etalage container. The zoom area will appear on the opposite side ('left'/'right') | 'left'
thumb_image_width | The large thumbnail width (excluding borders / padding) (value in pixels) | 300
thumb_image_height | The large thumbnail height (excluding borders / padding) (value in pixels) | 400
source_image_width | The source/zoomed image width (not the frame around it) (value in pixels) | 900
source_image_height | The source/zoomed image height (not the frame around it) (value in pixels) | 1200
zoom_area_width | Width of the zoomed image frame (including borders, padding) (value in pixels) | 600
zoom_area_height | Height of the zoomed image frame (including borders, padding) (value in pixels / 'justify' = automatic (height of large thumb + small thumbs)) | 'justify'
zoom_area_distance | Distance between the zoom area and thumbnail (value in pixels) | 10
zoom_easing | Ease the animation while moving the zoomed image (true/false) | true
click_to_zoom | Will start zooming when image is clicked instead of when hovering (when true, click-callback functions are disabled) (true/false) | false
zoom_element | Supply your custom zoom area element as a CSS type selector ('auto'/'#selector'/'.selector'). This allows for more freedom in positioning the zoom area outside of the Etalage container. To change the dimensions, set the "zoom_area_width" and "zoom_area_height" options to their pixel values. | 'auto'
show_descriptions | Shows the description area if a title attribute is given to the source image (true/false) | true
description_location | Location of the description area ('top'/'bottom') | 'bottom'
description_opacity | Opacity of the description area (except for IE) (number between or equal to 0-1) | 0.7
small_thumbs | How many small thumbnails will be visible underneath the large thumbnail (minimum of 3) (number) | 3
smallthumb_inactive_opacity | Opacity of the inactive small thumbnails (number between or equal to 0-1) | 0.4
smallthumb_hide_single | Don't show the small thumb when there is only 1 image (true/false) | true
smallthumb_select_on_hover | This will scroll through the small thumbnails when hovering them, instead of clicking them (true/false) | false
smallthumbs_position | Where to position the row of small thumbnails ('bottom'/'left'/'right') | 'bottom'
magnifier_opacity | Opacity of the magnifier area (does not apply if magnifier_invert is true) (number between or equal to 0-1) | 0.5
magnifier_invert | Make the large thumbnail clear through the magnifier, opaque around it (opacity is the value of magnifier_opacity) (true/false) | true
show_icon | Shows the icon image in the middle of the magnifier (only if magnifier_invert is false) and left-bottom of large thumb (true/false) | true
icon_offset | The icon's offset to the left-bottom corner (value in pixels) | 20
hide_cursor | Hides the cursor when hovering the large thumbnail (only works in some browsers) (true/false) | false
show_hint | Show "hint" until image is zoomed for the first time (true/false) | true
hint_offset | The hint's offset to the right-top corner (value in pixels) | 15
speed | All animation speeds are based on this setting (value in ms) | 600
autoplay | Makes the thumbs switch automatically when not interacting (at each autoplay_interval below) (true/false) | true
autoplay_interval | Time showing each image if autoplay is on (value in ms) | 6000 (6 seconds)
keyboard | Left/right arrow keys to navigate (true/false) | true
right_to_left | Makes the thumbnails slide from right to left and the caption texts RTL (true/false) | false

click_callback

Provide your own callback for the click event (function). Takes 2 arguments: image_anchor, instance_id. The old callback function method (up to v.1.3.1) is still supported in case you are already using those. Example:
$('etalage').etalage({
click_callback: function(image_anchor, instance_id){
alert('Callback example:\nYou clicked on an image with the anchor: "'+image_anchor+'"\n(in Etalage instance: "'+instance_id+'")');
}
});

function(){ return true; }

change_callback

Provide your own callback for the change event (thumb switching) (function). Takes 2 arguments: image_number, instance_id. The old callback function method (up to v.1.3.1) is still supported in case you are already using those. Example:
$('etalage').etalage({
change_callback: function(image_number, instance_id){
alert('Callback example: New active image: '+image_number+' (in Etalage instance: '+instance_id+')');
}
});

function(){ return true; }

## HTML setup

Create a list of images in an Unordered List. One image as the source image, another as the thumbnail. The thumbnail will be a resized source image if not provided (not recommended for beauty and performance).
Be sure to check out the example html pages and their source code.
<!-- Give it any id or class to identify it with: -->
<ul id="etalage">
<li>
<!-- This is the large (zoomed) image source: -->
<img class="etalage_source_image" src="/images/large_image_1.jpg" title="Optionally, your description goes here." />
<!-- This is the thumb image source (if not provided, it will use the large image source and resize it): -->
<img class="etalage_thumb_image" src="/images/thumb_image_1.png" />
</li>
</ul>

## Customizing the CSS

The css contains comments to guide you through. It is mostly used for setting borders, background colors and padding of the elements, the rest of the setup is done through the plugin settings.

## Advanced: Callback functions

Currently there are two callback functions: click_callback (triggered when clicking the large thumbnail (if it has an <a> tag)) & change_callback (triggered when the active image changes).
To use this optional functionality, you can provide your javascript to the plugin options as functions. They are then automatically triggered at the right time.
The click-callback function provides 2 arguments: the anchor (href) of the anchor tag and the ID attribute of the Etalage instance. For change-callback it is the new active image number and also the instance ID.
Example:
...
<script>
$(document).ready(function(){
$('#etalage').etalage({
// This is the optional image-click-callback function:
click_callback: function(image_anchor, instance_id){
alert('Callback example:\nYou clicked on an image with the anchor: "'+image_anchor+'"\n(in Etalage instance: "'+instance_id+'")');
},
// This is the optional change-callback function:
change_callback: function(image_number, instance_id){
alert('Callback example: New active image: '+image_number+' (in Etalage instance: '+instance_id+')');
}
});
});
</script>
</head>
<ul id="etalage">
<li>
<a href="#abc">
<img class="etalage_thumb_image" src="/img/thumb_image_1.jpg" />
<img class="etalage_source_image" src="/img/large_image_1.jpg" />
</a>
</li>
...
Above example will alert:
Callback example:
You clicked on an image with the anchor: "#abc"
(in Etalage instance: "etalage")
Fancybox example:
function etalage_click_callback(image_anchor){
$.fancybox({
'href': image_anchor
});
}

## Troubleshooting

Difficulty with implementing:

1. Check out this instructions page
2. Check out the example pages

Can not get it/something to work:

- Do the example pages work in your situation? That means something went wrong in your custom implementation. Try comparing them or starting out by modifying one of the sample pages step by step.
- Look for your issue in the Etalage FAQ
- Look for your issue on the Etalage comments page
- Post a comment with your question / request
- Email the author directly at please@frique.me