Usage



Installation

Demo: Basic installation and usage

  1. Create your thumbnails

    Your thumbnails should be placed inside a container and link to their respective full-size images, like this: 
    <div class="yoxview">
    <a href="img/01.jpg"><img src="img/thumbnails/01.jpg" alt="First" title="First image" /></a>
    <a href="img/02.jpg"><img src="img/thumbnails/02.jpg" alt="Second" title="Second image" /></a>
</div>

    The viewer displays the TITLE attribute of the image tag as the image's title inside the viewer, so it's recommended to use it.

    Note - If you use YoxView's plugins to get your images from Flickr/Picasa, it creates the thumbnails for you, so you can bypass this step.

  2. Include the YoxView script in your page

    Put the following line in the HEAD section of your page (just make sure that the SRC points to the correct folder):
    <script type="text/javascript" src="yoxview/yoxview-init.js"></script>

  3. Apply YoxView to  the element that contains your thumbnails (choose one of the following two methods):

    • Simple use (use if you don't know jQuery or as a shortcut):

      First make sure that the element containing your thumbnails has the class "yoxview", like shown above (<div class="yoxview">). Then, open the file yoxview-init.js and uncomment the last line:
      LoadScript(yoxviewPath + "yoxview-nojquery.js");

    • Regular jQuery plugin use:

      (Don't forget to call it from within $(document).ready!) 
      $("#thumbnails").yoxview([options]);

Options

You can specify options when calling YoxView, either from your script or, if you're using the yoxview-nojquery.js file, from there. 
$("#thumbnails").yoxview({
    backgroundColor: 'Blue',
    playDelay: 5000
});
Demo: Using options

These are all the available options:

Option name Type Default value Version Description
allowedUrls Regex - 2.09 This option expands the allowed URLs for images. By default, YoxView considers as images only URLs that end with '.jpg', 'jpeg', '.png' or '.gif'.
Use this option in case your images are served dynamically from the server, as a stream rather than an image file.

For example, to allow YoxView to display images that are generated with PHP, and have a URL of */image.php?imageId=(number), set this option to:
/\/image.php\?imageId=(?:\d+)$/i
allowInternalLinks Boolean false 2.0 If set to true, local links (with anchors, e.g '#options', 'flashPanel', etc.) are read and displayed by YoxView.
autoHideInfo Boolean true 1.85 If set to false, the info bar (with image count and title) is always displayed.
autoHideMenu Boolean true 1.85 If set to false, the menu bar is always displayed.
autoPlay Boolean false 1.1 If true, slideshow mode starts when the popup opens.
backgroundColor String '#000000' 0.9 The RGB hex color used to shade the website when the viewer's popup is on display. Use the full 6 characters, not the short 3-chars version.
backgroundOpacity Float, 0-1 0.8 0.9 The opacity of the background used to shade the website. Values can be between 0 and 1.
buttonsFadeTime Number 500 0.9 The time in milliseconds to show the viewer's buttons when it's opened. Setting this to 0 forces "Next" and "Prev" buttons to remain visible.
cacheBuffer Number 5 1.98 The number of images to cache ahead of the current image (directional, depends on the current viewing direction). This is the number of images that are cached before the viewer's popup is loaded, unless the option cacheImagesInBackground is set to false.

If you wish to cache all the images at once, set this to 0.
cacheImagesInBackground Boolean true 0.9 If true, full-size images are cached even while the gallery hasn't been opened yet.
controlsInitialFadeTime Number 1500 1.88 The time, in milliseconds, it takes the menu and prev/next buttons to fade in and out when the popup is opened.
controlsInitialDisplayTime Number 1000 1.88 The time, in milliseconds, to display the menu, prev/next buttons and the info bar when the popup is opened. Set to 0 to not display them by default
dataFolder String yoxviewPath + "data/" 1.0 Plugins folder location
dataUrl String - 1.9 Set this option to a URL from Picasa or Flickr to load images from those serives (YoxView's data plugins).
More info and demo
defaultDimensions Object {
  flash: { width: 720, height: 560 },
  iframe: {width: 1024 }
}		 2.09 Default dimensions (width/height) for content types that YoxView can display.
For example, if you'd like all the iframes displayed by YoxView to have a width of 500px, set this to:
defaultDimensions: { iframe: { width: 500 }}

Setting only one content type doesn't cancel the settings for other types.
flashVideoPlayer String "jwplayer" 2.0 The name of the Flash video player to use for. At the moment, only jwplayer is supported.
flashVideoPlayerPath String "/jwplayer/player.swf" 2.0 The path for the used flash video player's SWF file.
infoBackOpacity Float, 0-1 0.5 0.9 The opacity of the info bar, at the bottom of the viewer, which contains the image's title and position. Values can be between 0 and 1.
infoBackColor String '#000000' 0.9 The color of the info bar. Use the full 6 characters, not the short 3-chars version.
infoButtons Object - 1.98 Use this option to add custom buttons to the info bar (bottom right of the viewer). More info and demo.
imagesFolder String yoxviewPath + "images/" 1.0 The folder of the viewer's icons and graphics.
isRTL Boolean false 0.9 For bidirectional support, switches prev/next sides. For RTL languages such as Hebrew or Arabic, for example.
lang String 'en' 0.9

The language for tooltips and button names. Value should be the language's two-letter abbreviation (en, es, fr, etc.). A language file should exist in the lang/ folder corresponding to the specified language.

Click here for a list of available languages.
langFolder String yoxviewPath + "lang/" 0.9 Language packs folder location
linkToOriginalContext Boolean true 1.9 If true, a small icon is added to the right of the info bar, linking to the image in its original context, if the image is pulled from an external source, such as Picasa or Flickr.
loopPlay Boolean true 0.9 If true, slideshow play starts over after the last image.
menuBackgroundColor String '#000000' 2.0 The background color of the menu panel. Use the full 6 characters, not the short 3-chars version.
Available only on browsers that support the rgba CSS function (not available in IE up to version 8).
menuBackgroundOpacity Float, 0-1 0.8 2.0 The opacity of the menu panel. Values are between 0 and 1.
Available only on browsers that support the rgba CSS function (not available in IE up to version 8).
playDelay Number 3000 0.9 Time in milliseconds to display each image in slideshow mode.
popupMargin Number / String 20 2.0 The minimum number of pixels between the popup and the window. If the value is a number, it's the value for top, right, bottom and left margins.
By using a string, it's possible to specify different values for each side. Values are given like in CSS, but without units, since it's always in pixels (for now):

"20 40" - top and bottom margins are 20px, left and right are 40px.
"20 30 40" - top: 20px, right and left: 30px, bottom: 40px.
"20 30 40 50" - top: 20px, right 30px, bottom 40px, left 50px.
popupResizeTime Number 600 1.93 The time in milliseconds it takes to make the resize transition from one image to the next. Set to zero to disable animations when changing images.
renderButtons Boolean true 1.1 Set to false if you want to implement your own Next/Prev buttons, using the API.
renderInfo Boolean true 1.95 Set to false to avoid rendering the info bar (in case you want to implement it by yourself, for example).
renderInfoExternally Boolean false 2.0 If set to true, the info bar is rendered outside the viewer's window, useful for skins where you might like to have the bar fixed positioned.
renderInfoPin Boolean true 1.95 If set to false, the pin/unpin button to the right of the info bar isn't rendered.
renderMenu Boolean true 1.1 Set to false if you want to implement you own menu (Play/Help/Close) using the API.
showBarsOnOpen Boolean true 1.1 If true, displays the top (help) bar and bottom (info) bar momentarily when the popup opens.
showButtonsOnOpen Boolean true 1.1 If true, displays the Prev/Next buttons momentarily when the popup opens.
showDescription Boolean true 2.2 If set to false, the description property from imported content (Flickr, YouTube or custom images JSON data) will not be shown in the viewer's info bar. Note that this doesn't affect the title, which is shown regardless.
skin String - 2.0 The name of the skin to display YoxView with. At the moment, only one skin is available: 'top_menu'.
textLinksSelector String '.yoxviewLink' 2.1 A jQuery selector to identify links that are not thumbnails, which YoxView should try to open.

Important note - this selector always refers to an anchor element ('<a>'), so you don't need to specify the anchor in the selector. So, instead of "a.yLink", use ".yLink", or instead of "a:last-child", use ":last-child".

More info and demo
thumbnailsOptions Object { thumbnailsClass: "yoxview_thumbnail" } 2.2 See info in Plugins page
titleAttribute String 'title' 1.0 The thumbnail's attribute to use as the image's text inside YoxView. For example, to use the ALT attribute, set this to 'alt'.
titleDisplayDuration Number 2000 0.9 The time in milliseconds to display the image's title, after which it fades out.
titlePadding Number 6 0.9 Padding, in pixels, for the image's title.



Demos

Here's a full list of the available demos:


How to...

  • Display other content with YoxView


    Demo: Displaying different media types

    YoxView has built-in support for video, Flash, iframes and any other type of content which can be placed in a web page. Examples:

    • Video (Flash)

      First, Download JW Player and place its folder in the root of your website (/jwplayer).

      To load a video, simply create a thumbnail with the video file's URL for the thumbnail's HREF attribute. Important - the location of the video file is relative to the location of the JW Player's files, which defaults to /jwplayer (absolute path). Therefore, to avoid location issues, it's best to set an absolute path for your video file (meaning - full path, like '/yoxview/media/cats.f4v' rather than 'media/cats.f4v' or '../media/cats.f4v').

      The width and height of the video can be speicifed as query parameters. If not specified, the default width and height are used (720x560 pixel).

      The video's preview image (the one that displays before the video is played) can also be set as query parameter. If no image is specified, the thumbnail image is used as preview.

      At the moment, Flash video is displayed using JW Player, but other players will be supported in the future.
      Usage example:

      <a href="/media/video1.f4v?image=/media/video1_image.jpg&width=640&height=480">
    <img src="media/video1_thumbnail.jpg" alt="First video" title="My first video" />
</a>
      Supported file types: flv, f4v, f4p, f4a, f4b, aac.

    • Online video (YouTube, Vimeo, Hulu, etc.)

      Demo: Displaying online video
      Use the videoSize option to specify video size, if you don't want to use the default size.

      Supported video providers: YouTube, Vimeo, Hulu, Viddler, Flickr, MySpace, Qik, Revision3, Dailymotion & 5min. If you'd like to use an unsupported provider, please contact me. Example: 
      <a href='http://vimeo.com/5604684'>
    <img src="images/items/thumbnails/geva.jpg" alt="Come Race Me" title="Geva Alon - Come Race Me" />
</a>

    • Flash files

      To display a Flash file, simply link to it from your thumbnail. Width, height and flashvars can be specified by query parameters, like this: 
      <a href='myfile.swf?width=800&height=600&customVal=123'>
    <img src="media/flash1_thumbnail.jpg" alt="Flash presentation" title="Name of the Flash" />
</a>

    • Other web pages (iframes)

      YoxView can display other pages by using an iframe. To do this, link to the desired page from your thumbnail and give it a TARGET attribute with value 'yoxview': 
      <a href='http://www.xkcd.com' target='yoxview'>
    <img src="media/xkcd_thumb.jpg" alt="XKCD" title="XKCD" />
</a>

    • Inline elements and other media types

      To display inline elements, the options allowInternalLinks should be set to true.
      Then, simply link to the element's ID with an anchor: 
      <a href='#mycontent'>
    <img src="inline_thumbnail.jpg" alt="Inline" />
</a>

<div id="mycontent" title="The element's title" style="display: none">Some content...</div>

      It's important to note that YoxView removes the element from the page. To avoid a flicker in the page when it loads, specify 'display: none' in its CSS.

      Also important, the width and height of the element (which you set using CSS) are used by YoxView for max size and width/height ratio.

      To display other media types, such as PDF, Quicktime or Java applets, use the inline element method by placing the object inside a DIV:

      <a href='#pdf_test'>
    <img src="pdf_thumbnail.jpg" alt="PDF" />
</a>

<div id="pdf_test" title="Document's name" style='display:none; width: 800px; height: 1000px;'>
    <object data="test.pdf" type="application/pdf" width="100%" height="100%">
        <a href="test.pdf">test.pdf</a>
    </object>
</div>

  • Add a hyperlink to the text title inside YoxView

    You can do this, and in fact add any HTML to image titles, by escaping the HTML and adding it to the TITLE attribute of the images. For example:

    <a href='images/photo1.jpg'>
    <img src='thumbnails/photo1.jpg' alt='thumbnail1' 
    title="First photo. &lt;a href='http://otherpage.com'&gt;Go to the other page&lt;/a&gt;" />
</a>

    Basically, you need to replace double-quote marks with '&quot;' (so the TITLE attribute of the image isn't closed) and the angle brackets ('<' and '>') with '&lt;' and '&gt;' (respectively).

    Demo: Using hyperlinks and other HTML inside YoxView's title text
  • Demo: Open YoxView from text links

    Since version 2.1, it's possible to open YoxView from text links as well as thumbnails (links with images). To do this, you should either add the class "yoxviewLink" to your links, or use the option textLinksSelector to specify which links should be opened with YoxView:

    $(document).ready(function(){ 
    $(".yoxview").yoxview();
    $("#yoxviewText").yoxview({ textLinksSelector: "" };
});

<div class='yoxview'>
    Would you like to see a photo of 
    <a class='yoxviewLink' href='images/items/monkey.jpg' title='Behind you!'>a three headed monkey?</a>
</div>

<div id='yoxviewText'>
    There are also photos of <a href='images/items/scully.jpg'>hot redheads</a>
    and <a href='images/items/mulder.jpg'>amusing skepticists</a>!
</div>
    Please read the notes for textLinksSelector in the options table before using it. 

  • Set multiple images for a single thumbnail

    Example You can specify any number of images to display when clicking a thumbnail. This is done by specifying the images with the images option.

    First, create your thumbnail: 
    <a id='yoxviewGallery' href='anyimage.jpg'><img src='thumbnail.jpg'></a>
    Now you need to specify the images this thumbnail displays, and it's done when calling YoxView. Here's the code for the example above: 
    $(document).ready(function(){
    $("#multipleExample").yoxview({
        images: [
            { media: { src: 'images/items/large/avocado.jpg', title: 'Avocado' }},
            { media: { src: 'images/items/large/flower.jpg', title: 'Flower' }},
        ]
    });
});
    
<a href='images/items/large/fire.jpg' id='multipleExample'>
    <img src='images/items/thumbnails/fire.jpg' title='Multiple image example' alt='Example' />
</a>
    As you can see, you can set the title for each image as well as the image file.

    If you use the yoxview-nojquery.js file to call YoxView, you need to enter this code there, instead or in addition to the line: $(".yoxview").yoxview();

    Demo: Set multiple images for a single thumbnail

  • Display tooltips and help in a language other than English

    YoxView has multilingual support for all its tooltips and help panel. The direction of the language can also be specified, for full support of right-to-left languages, such as Arabic or Hebrew.

    The language packs are .js files, in the lang/ folder. Each file should be named according to the language it represents (en.js for English, fr.js for French, etc.). To create your translation, simply copy an existing language file (here's the English version) and change the values for each field. Note the "Direction" value in the language files, its value should be either "ltr" (left to right) or "rtl" (right to left) and specifies the correct directionality for the language.

    Language files should be saved with UTF-8 encoding, to ensure that special characters are displayed properly.

    If you create a new language pack, I'd appreciate it if you'd send it to support@yoxigen.com with the desired credit (name + website, if available), so I can make it available.

    List of available languages

  • Create an image gallery using images from Flickr/Picasa with YoxView

    Please refer to the Plugins page.

  • Add custom buttons to the YoxView viewer

    Custom icons are added using the infoButtons option, as you can see in the source code of this page. You should use the onSelect event handler, which is called when the viewer opens or the image changes, to change the behavior of the custom icon according to the current image.

    Demo: Adding custom buttons

  • Display images from inside a frame/iframe

    YoxView works from inside a frame or iframe the same as on a regular page. The popup is created on the top document, the one which holds the frame.

    One thing to make sure - give a name attribute to the frame. This allows YoxView to reference the frame and correctly position thumbnails (when opening or closing the viewer).

    The parent page contains the frame like this: 
    <iframe name='yoxview_iframe' src='gallery.html' />
    then, inside gallery.html, yoxview is called regularly, as if it's not in a frame at all.

    Demo: YoxView inside an iframe

Troubleshooting

  • YoxView doesn't work, clicking on a thumbnail just opens a page with the large image

    This indicates that for some reason, YoxView has not loaded properly and your thumbnails haven't been connected to it. There may be a number of reasons for this:

    • One or more of the files required for YoxView to run hasn't loaded properly

      If you're using yoxview-init.js to load YoxView, make sure you're referencing it correctly. For example, if you use: 
      <script type='text/javascript' src='yoxview/yoxview-init.js'></script>
      The yoxview folder should be placed in the same folder where your HTML (or any other type of page) is placed.

    • You're using a Javascript library other than jQuery on the same page. (Prototype, Mootools, Dojo, etc.)

      This could happen if other plugins are used on the same page and one or more of them use a different JS library. To fix this, you should run YoxView in No-Conflict mode: If you use the yoxview-nojquery.js file, simply uncomment the third line, so it looks like this: 
      jQuery(document).ready(function($){
    // Uncomment the following line...
    jQuery.noConflict();
    $(".yoxview").yoxview();
});
      If you are a jQuery user, just make sure you run jQuery in noConflict mode, like demonstrated above.

  • Flash movie / embedded video is always over the YoxView viewer

    If your flash movie, YouTube video, etc. stays on top of the YoxView viewer, you should add wmode="transparent" to your embed tag, like so: 
    <object width="640" height="385">
    <param name="movie" value="http://web1.nyc.youtube.com/v/IONyLZn0pLI&hl=en_US&fs=1&"></param>
    <param name="allowFullScreen" value="true"></param>
    <param name="allowscriptaccess" value="always"></param>
    <embed src="http://web1.nyc.youtube.com/v/IONyLZn0pLI&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="640" height="385" wmode="transparent"</embed>
</object>

  • Getting error - "Error: Media is unavailable." (in YoxView) or "Error: media is undefined" (in Firebug)

    This happens if YoxView doesn't recognize the type of the large image it should display. Supported image types are JPG, JPEG, GIF or PNG.

    If, however, you're using a dynamic page to serve your images, such as PHP or ASP.NET, and require a different extension in the URL, you can add a query parameter to the image URL, so YoxView's regex recognizes your images. Example:

    <a href='img.php?img_id=100&size=large&type=.jpg'>
    <img src='img.php?img_id=100&size=thumbnail' />
</a>

  • When testing on Chrome locally (not on a server or localhost), Flickr and Picasa plugins don't work

    You might see a message in the Chrome inspector that says "Uncaught ReferenceError: yox_flickr is not defined" or "Uncaught ReferenceError: yox_picasa is not defined".

    This issue is due to Chrome's security policy (last checked: July 19th, 2010), which doesn't allow to read local files using AJAX, which is how YoxView loads its plugin files.

    The solution: test Chrome in localhost or on a server.

For developers

  • Event handlers

    You can add event handlers for certain events on YoxView. You pass a function delegate as an option when calling the yoxview plugin, like this:

    $(".yoxview").yoxview({ 
    onOpen: function(){ 
        alert('YoxView is now open!'); 
    }
});
    You can also define the event handler outside the yoxview call, like this: 
    function yoxviewOnOpen()
{
    alert('YoxView is now open!');
}

$(document).ready(function(){
    $('.yoxview').yoxview({onOpen: yoxviewOnOpen});
});
    Event handlers are useful if, for example, you need to clear another popup when YoxView loads, or do something after it closes.

    These are the available events:
    Event Description
    onBeforeUnload(unloadCallback) If the unload method is called, this handler can be set to do something before the actual unload occurs.

    Demo: Changing options, uses the onBeforeUnload event handler.
    onClose() Called when the viewer opens.
    onEnd() Called in the following cases: 1. When playing a slideshow and the last image was passed, 2. When "next" has been pressed and the viewer is on the last image, 3. When "previous" has been pressed and the viewer is on the first image. For example, to close the viewer after the last image: 
    $(".yoxview").yoxview({
    loopPlay: false,
    onEnd: function(){
        $.yoxview.close();
    }
});
    Demo: onEnd event usage
    onOpen() Called when the viewer opens.
    onSelect(imageIndex, image) Called when an image is selected. Example:
    $('.yoxview').yoxview({ onSelect: function(imageIndex, image){
    alert(' Image number ' + imageIndex + ' is now selected. Its title is: ' + image.media.title);
    }
});

  • API

    YoxView's API is exposed, so you can create your own UI to control the viewer. If you create a custom template for YoxView, please send it to support@yoxigen.com, I'd love to see it!

    Important note  - since version 2.1, the API uses variable $.yoxview instead of yoxviewApi.

    The API's methods are called using the $.yoxview variable, like this:
    $.yoxview.play();
$.yoxview.next();
$.yoxview.close();
    Or, when specific to an element, by using methods (since v2.1):
    $("#yoxview1").yoxview("open");
    These are the available API methods:
    Method signature Description
    close() Closes the viewer and stops the slideshow if playing.
    closeHelp() Closes the help panel, if open.
    currentImage Holds the currently displayed image's data. The object's structure is like this:
    {
    media: {
        alt: "The image's ALT attribute",
        description: "Long optional text, if available is rendered below the title.",
        height: 500, (image's height in pixels)
        loaded: true, (whether the image has already been cached in the browser)
        src: "/images/image1.jpg",
        title: "The text that should be displayed in YoxView.",
        width: 700 (image's width in pixels)
    },
    thumbnailImg: [img /images/thumb1.jpg] (jQuery object representing the image's thumbnail),
    thumbnailSrc: "/images/thumb1.jpg" (the thumbnail's SRC attribute)
}
    first() Takes the viewer to the first image.
    help() Opens the help panel in the viewer, if the viewer is open.
    last() Takes the viewer to the last image.
    next() Advances the viewer to the next image in line.
    .yoxview("open", [callback]) Note - before version 2.1 this method was named openGallery.
    Opens the popup at a specified position. The method has two optional parameters:

    element: a jQuery-wrapped element, which is either a container for YoxView or an anchor that links to media.
    callBack: A function to call after the popup has been opened. For example, if you want to open the popup in slideshow mode, do this: 
    $("#yoxview2").yoxview("open", function(){
        $.yoxview.play();
    }
);
    options({ options })
    options(name, value)    		 Changes one or more options for the specified YoxView instance(s).
    Demo

    Examples: 
    // Change all YoxView instances to use Spanish and auto play slideshow:
$.yoxview('options', { lang: 'es', autoPlay: true });

// Change the data URL for a specific instance of YoxView (to load a different Picasa album):
$('#yoxview_picasa').yoxview('options', 'dataUrl', 'http://picasaweb.google.com/yoxigen/Trips');
    play() Start/stop slideshow mode.
    prev() Takes the viewer to the previous image.
    resize() Resizes the viewer according to the document's size and the viewer's options. Used in the window.resize event.
    select(imageIndex, [pressedBtn]) Displays the specified image and shows the specified button, if specified. Use when the viewer is open.

    imageIndex: The 0-based index of the image to display.
    pressedBtn: a jQuery element of a button to display momentarily in the viewer. For example, if the image has been selected by pressing the Next button on the keyboard, specify the Next button. If no button should be display, leave blank.
    setDefaults(options) Can be used to set options for all following instances of YoxView to be called: 
    $.yoxview.setDefaults({
    skin: 'top_menu',
    cacheBuffer: 10
});

// both following instances will have the options set above:
$("#yoxview1").yoxview();
$("#yoxview2").yoxview();
    unload() Unloads YoxView from the page by removing the popup from the DOM, unbinding the click events from thumbnails and removing the yoxview API from memory. After calling this method you can't use the yoxview API.
    update() Updates one or more YoxView instances in the page. For example, in case your images change in response to an AJAX call, update() can be called to load the new images. Example: 
    $("#yoxview_ajax").yoxview("update"); // single instance
$.yoxview.update(); // updates all YoxView instances on the page