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
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
flashDefaults Object { width: 720, height: 560 } 2.0 Default parameters for Flash and Flash video content. Can be overriden by specifing query parameters when linking to a Flash file.
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.
iframeSize Object { width: 1024, height: 768 } 2.0 The default width and height (in pixels) for iframes that open in YoxView.
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.
skin String - 2.0 The name of the skin to display YoxView with. At the moment, only one skin is available: 'top_menu'.
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.
videoSize Object - 1.8 A specified max size for displaying videos. Example:
{ maxWidth: 720, maxHeight: 560 }

The JSON object should have both maxWidth and maxHeight, which specify the max size, in pixels, videos may have.
Consider this size as a bounding box in which the videos are rendered, while keeping their aspect ratio.



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

  • 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="A1">
    <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

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 name Signature Description
    onClose onClose() Called when the viewer opens.
    onOpen onOpen() Called when the viewer opens.
    onSelect 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!

    The API's methods are called using the yoxviewApi variable, like this:
    yoxviewApi.play();
yoxviewApi.next();
yoxviewApi.close();
    Let's say you want to use a text link to open the viewer: 
    <a href='#' onclick='yoxviewApi.openGallery(); return false;'>Open gallery!</a>
    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.
    openGallery([viewIndex, [imageIndex]], [callBack]]) Opens the viewer popup. The method has two optional parameters:

    viewIndex: The 0-based index of the view to open, in case there are multiple instances of YoxView on the same page. Default is 0.
    imageIndex: The 0-based index of the image to open, in the specified view. Default is 0.
    callBack: A function to call after the gallery has opened. For example, if you want to open the popup in slideshow mode, do this: 
    yoxviewApi.openGallery(
    0, // the view's index - defaults to 0 if not specified
    0, // the index of the first image to display, defaults to 0
    function(){
        yoxviewApi.play();
    }
);
    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.
    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.