kGallery Documentation
- Documentation
- Page on GitHub
- Report bug
- Download
kGallery demos
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
- Prepare files to play in slideshow. Place them somewhere on your server. Make sure that files are available to view in browser.
- 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.
- 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
- 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>
- Put gallery wrapper into HTML of your page
<h2>Plugin usage of kGallery</h2> <div id="gallery-wrapper"></div>
- 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 |