kGallery Documentation

JavaScript and jQuery gallery which able to function efficiently with hundreds of photos.

First significant advantage of this gallery is ability to work stable with hundreds of pictures or with huge pictures without freezing browser. This effect is achieved by retrieving the list of images from the external source (JSON or XML) and downloading pictures gradually while slideshow is playing, not all in once.

kGallery includes kSlideshow and kThumbnailPicker components, each of them could be used independently.

Note that this gallery is supposed to work on server not on local computer. Most of browsers will refuse XHR request to JSON list of pictures which is located on local file system (such as file:///C:/gallery/files.json). Try to use kSimpleSlides if you need just simple slideshow which works without JSON and XHR stuff.

Do not hesitate to contact author if you have any questions or enquiries about kGallery:
Andrew Kondratev e-mail:andr@kopolo.ru
Andrew speaks Russian and English.

Usage

  1. Prepare files to play in slideshow. Place them somewhere on your server. Make sure that files are available to view in browser.
  2. Prepare JSON file with pictures list.
    JSON is JavaScript Object Notation, so JSON file is just text file which contains text with following structure:
    { "items": [
    	{
    		"large":"web_path_to_picture1.jpg ",
    		"thumb":"web_path_to_picture1_thumbnail.jpg",
    		"title":"title for first picture"
    	},
    	{
    		"large":"web_path_to_picture2.jpg ",
    		"thumb":"web_path_to_picture2_thumbnail.jpg",
    		"title":"title for second"
    	}
    	/*, more items*/
    ]}
    

    Save this file somwhere on your server with .json extension and make sure that it is available in your browser. Remember web path to this file, you need it for step 6 of this tutorial.

  3. Include jQuery and kGallery into HTML of your page:
    <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.2.min.js"></script>
    <script type="text/javascript" src="js/kGallery-full.min.js"></script
    
  4. Add some custom styles for your gallery:
    <style>
    /* gallery wrapper dimensions */
    #gallery-wrapper{ height: 400px; width: 400px; text-align: center; }
    
    /* slide dimensions */
    .kSlideshowWrapper, .kSlideshowItemDiv{ width: 400px; height: 267px; }
    
    /* picture styles */
    .kSlideshowItemDiv img{ z-index: 400; }
    
    /* thumbnails wrapper dimensions */
    .kThumbnailsWrapper{ 	width: 324px; height: 80px; margin: 10px auto 0 auto; }
    .kThumbnailsInnerWrapper{ height: 80px; width: 324px; }
    
    /* thumbnails page dimensions */
    .kThumbnailsPage{ width: 324px; text-align: left; }
    
    /* thumbnail styles */
    .kThumbnailsPage img{ padding: 1px; border: 1px solid black; margin: 2px; }
    
    /* selected thumbnail styles */
    .kThumbnailsPage .selectedThumbnail{ border-color: #aaaaff; }
    </style>
    
  5. Put gallery wrapper into HTML of your page
    <h2>Plugin usage of kGallery</h2>
    <div id="gallery-wrapper"></div>
    
  6. Init your kGallery
    <script type="text/javascript">
    $(document).ready(function() {
        //initializing plugin with url string
        $('#gallery-wrapper').kGallery('web_path_to_your_pictures_list.json');
        
        /*
        \\initializing plugin with options object
        $('#gallery-wrapper').kGallery({
            dataSource: 'web_path_to_your_pictures_list.json',
            startItem: 2
        });
        */
    
        /*
        \\initializing plugin with options object and array data-source
        $('#gallery-wrapper').kGallery({
            dataType: 'array',
            dataSource:[{
              "large":"img1.jpg",
              "thumb":"img1_sml.jpg",
              "title":"title!"
            },
            {
              "large":"img2.jpg",
              "thumb":"img2_sml.jpg",
              "title":"title2!"
            }],
        });
        */
    
        // you can check all possible settings below
    });
    </script>
    

Notes

kGallery will destroy previous kGallery instance if you try to initialize it on the wrapper with initialized instance

If you try to initialize gallery without options it will return kGallery instance initialized on this wrapper if it is initialized otherwise FALSE.

visit demos section for live usage examples.

kGallery

Parameter Description Default value Data type
wrapper Gallery wrapper. If collection of elements is given, displays the same slideshow obeying same commands in all wrappers. Calls new kSlideshow to create independent slideshow. #gallery-wrapper string or $.object
dataSource Url with the data for gallery (JSON usually), see jQuery.ajax() or JavaScript array (should replace dataType to array) data.json string | array
dataType Data type, see jQuery.ajax() + 'array' option json string
startItem index of initial slide 0 integer
slideshowOptions Additional settings for kSlideshow object
thumbnailPickerOptions Additional settings for kThumbnailPicker object
wrapperClass CSS class, which is added to gallery wrapper kGallery string
selectedThumbnailClass CSS class, which is added to selected thumbnail selectedThumbnail string
afterInit Function, which is called after initialization function
beforeShow Function, which is called before displaying of picture function (itemIndex) function
destroy Function to destroy kGallery instance function () function

kSlideshow (for Slideshow only)

Parameter Description Default value Data type
wrapper Slideshow wrapper. If collection of elements is given, displays the same slideshow obeying same commands in all wrappers. Calls new kSlideshow to create independent slideshow #slideshow-wrapper string or $.object
dataSource Url with the data for gallery (JSON usually), see jQuery.ajax() or JavaScript array (should replace dataType to array) data.json string | array
dataType Data type, see jQuery.ajax() + 'array' option json string
autoPlay Start slideshow playback automatically true boolean
startItem index of initial slide 0 integer
preloadImagesCount Number of preloading pictures. Gallery preloads {preloadImagesCount} pictures before and after current slide. 2 integer
nextAttempts Number of attempts before flipping to the next slide (when slideshow is playing).If slide picture is not loaded yet kSlideshow prevents automatic flipping to the next slide {nextAttempts} times. if 0 or 1 is given, flipping automatically without waiting until picture is downloaded. 4 integer
interval Interval between slides flipping, milliseconds 2000 integer
fadeDelay Slides appearance speed, milliseconds 400 integer
itemDivClass CSS class for slides wrappers (adds to item div) kSlideshowItemDiv string
enableControls Create controls automatically true boolean
enableTitle Turn on displaying of titles true boolean
enableAlt Turn on adding of alt and title attributes to slideshow images true boolean
displayEmptyTitle Always display title block even if title is empty false boolean
wrapperClass CSS class for slideshow wrapper (adds to wrapper) kSlideshowWrapper string
playToggleClass CSS class for "play/pause" toggle (adds to "play/pause" button) kSlideshowPlayToggle string
playClass CSS class for "play" button (adds to "play/pause" button when slideshow is on the pause) kSlideshowPlay string
pauseClass CSS class for "pause" button (adds to "play/pause" button when slideshow is playing) kSlideshowPause string
nextClass CSS class for "next" button (adds to "next" button) kSlideshowNext string
prevClass CSS class for "prev" button (adds to "prev" button) kSlideshowPrev string
titleClass CSS class for title (adds to title block) kSlideshowTitle string
controlsInactiveClass CSS class for inactive controls buttons (adds to inactive controls) inactive string
loadedClass CSS class for downloaded pictures (adds to picture when downloading of it is finished) loaded string
afterInit Function which called after initialization of a slidewhow function
beforeShow Function which called before displaying of a slide (node of a slide can be not created yet if this slide displayed first time). @param integer indexItem - index of current item function (itemIndex) function
beforeAnimation Middleware event between beforeShow and afterShow. Function which is called before fadeIn animation when DOM node of slide is created already. @param integer indexItem - index of current item. @param object itemNode - DOM node of the slide. function (itemIndex, itemNode) function
afterShow Function which is called when fadeIn animation of the slide is finished function
onLoadingError Function which is called on parsing data error function (jqXHR, textStatus, errorThrown) function
destroy Function to destroy kSlideshow instance function () function

kThumbnailPicker (for Thumbnails only)

Parameter Description Default value Data type
wrapper thumbnails wrappers #thumbnails-wrapper string or $.object
dataSource Url with the data for gallery (JSON usually), see jQuery.ajax() or JavaScript array (should replace dataType to array) data.json string | array
dataType Data type, see jQuery.ajax() + 'array' option json string
vertical Vertical scrolling false boolean
itemsOnPage Number of previews on page. Do not forget to set correct size for the wrapper and the innerWrapper, considering the width, height and number of items on page. 3 integer
preloadPagesCount Number of preloading pages. Only thumbnails for next(and previous) {preloadPagesCount} pages are downloading, When you switching to the next page - thumbnails of next+{preloadPagesCount} page are downloading (if them are not downloaded yet) 2 integer
startItem Index of initial slide. Index of initial page will be calculated automatically. 0 integer
wrapperClass CSS class, which adds to the thumbnails wrapper kThumbnailsWrapper string
innerWrapperClass CSS class, which adds to the thumbnails inner wrapper kThumbnailsInnerWrapper string
nextPageClass CSS class, which adds to next page button kThumbnailsNextPage string
prevPageClass CSS class, which adds to previous page button kThumbnailsPrevPage string
controlsInactiveClass CSS class, which adds to inactive control elements inactive string
pageClass CSS class, which adds to all thumbnails pages kThumbnailsPage string
enableControls Enable auto creation of control elements for thumbnails true boolean
scrollingEffect Animation effect for pages scrolling: 'slide' or 'fade' slide string
scrollingSpeed Speed of scrolling, milliseconds 1000 integer
afterInit Function, which is called after initialization of thumbnails function
beforeShow Function, which is called before changing of page. @param boolean nextOrPrev - true is passed if showPage called by instance.next or instance.prev methods. function (nextOrPrev) function
afterShow Function, which is called after changing of page. @param boolean nextOrPrev - true is passed if showPage called by instance.next or instance.prev methods function (nextOrPrev) function
thumbnailClick Function, which is called on thumbnail click. @param integer itemIndex - index of clicked thumbnail. function (itemIndex) function
destroy Function to destroy kThumbnailPicker instance function () function