nanogallery2



nanogallery2 API - reference guide







Examples of API / callbacks / events usage


Add items dynamically to an existing gallery: view demo on codepen
Shopping cart: view demo on codepen
Thumbnail selection handling: view demo on codepen
Thumbnails: add custom tool and custom button: view demo on codepen
Integrate Youtube videos with fancyBox3: view demo on codepen






Events


Events (also available in your browser debug console):

Example:

// Attach an event handler function for some events to the gallery
$("#nanogallery2").on( 'pageChanged.nanogallery2 galleryRenderStart.nanogallery2 galleryRenderEnd.nanogallery2 galleryObjectModelBuilt.nanogallery2 galleryLayoutApplied.nanogallery2 galleryDisplayed.nanogallery2 lightboxNextImage.nanogallery2 lightboxPreviousImage.nanogallery2 lightboxImageDisplayed.nanogallery2 shoppingCartUpdated.nanogallery2 itemSelected.nanogallery2 itemUnSelected.nanogallery2', my_listener );

// Event handler function
function my_listener(e) {
  console.log(e.type);
}
      


event description
pageChanged.nanogallery2
v1.0
Fired on gallery pagination.
galleryRenderStart.nanogallery2
v1.0
The rendering of the gallery is started.
galleryRenderEnd.nanogallery2
v1.0
The galery has been rendered.
galleryObjectModelBuilt.nanogallery2
v1.0
The Gallery Object Model(GOM) has been populated with all the items.
galleryLayoutApplied.nanogallery2
v1.0
The layout has been applied to the gallery/thumbnails.
This can be called several times, for example when thumbnails image sizes are not defined.
galleryDisplayed.nanogallery2
v1.0
The thumbnails have been displayed.
lightboxNextImage.nanogallery2
v1.0
Lightbox - display next image.
lightboxPreviousImage.nanogallery2
v1.0
Lightbox - display previous image.
lightboxImageDisplayed.nanogallery2
v1.0
Lightbox - image displayed.
shoppingCartUpdated.nanogallery2
v1.0 v2.4.0
Called when the shopping cart is updated (new item or item updated).
itemSelected.nanogallery2
v1.1
One thumbnail has been selected. Not fired when itemsSetSelectedValue is called.
itemUnSelected.nanogallery2
v1.1
One thumbnail has been un-selecetd. Not fired when itemsSetSelectedValue is called.



Callbacks


Callbacks provide a simple mechanism to extend the capabilities of nanogallery2 with your own javascript functions.
Since v1.3, callbacks are supported in HTML markup mode.

Example:

// Build the gallery
jQuery("#nanogallery2").nanogallery2({

  fnShoppingCartUpdated: mylistener,            // set the callback function

  thumbnailHeight: 100, thumbnailWidth: 100,
  ...
});

// Callback function
function mylistener( cart, item ) {
  alert("Shopping cart updated. More details in your browser's console.");
  console.log("### item:");
  console.dir(item);
  console.log("### shopping cart:");
  console.dir(cart);
}

      


callback description
fnShoppingCartUpdated
v1.0v2.4.1v3.0.0
Called when the shopping cart is updated (new item or item updated). view demo
Parameters: shoopingCart, item, source
fnGalleryRenderStart
v1.0v3.0
Called before rendering the gallery.
Parameter: albumIndex album object
fnGalleryRenderEnd
v1.0v3.0
Called after the gallery has been rendered.
Parameter: albumIndex album object
fnGalleryObjectModelBuilt
v1.0
Called after the GOM has been built.
fnGalleryLayoutApplied
v1.0
Called after the layout has been applied to the gallery/thumbnails.
This can be called several times, for example when thumbnails image sizes are not defined.
fnThumbnailInit
v1.0
Called once after one thumbnail's build. Called for each thumbnail.
Parameters: $thumbnail, item, GOMidx
fnThumbnailHoverInit
v1.0
Called once to initialize the thumbnail hover effect. Called for each thumbnail.
Parameters: $thumbnail, item, GOMidx
fnThumbnailHover
v1.0
Called on thumbnail hover.
Parameters: $thumbnail, item, GOMidx
fnThumbnailHoverOut
v1.0
Called on thumbnail hover out.
Parameters: $thumbnail, item, GOMidx
fnThumbnailDisplayEffect
v1.0
Called to display one thumbnail, after it was built.
Parameters: $thumbnail, item, GOMidx, delay
fnThumbnailL1DisplayEffect
v1.3
Called to display one thumbnail, after it was built. Only on first album level
Parameters: $thumbnail, item, GOMidx, delay
fnThumbnailOpen
v1.0
Called when a thumbnail is clicked/touched to display the image.
Can be used to replace the standard viewer/lightbox with an external lightbox.
Parameter: items, array containing the list of items to display, the first one is the first to display.
fnImgDisplayed
v1.1
Called when an image has been displayed in the lightbox/viewer.
Parameter: item
fnImgToolbarCustInit
v1.0
Lightbox toolbar custom element.
To customize the toolbar (custom icons and elements) on image display.
Called once when the toolbar is build to define the specified custom elements.
The called function should return the HTML content to display.
Parameter: customElemntName
fnImgToolbarCustDisplay
v1.0
Lightbox toolbar custom element.
Called each time after an image has been displayed.
Called once for all toolbar custom icons and elements.
Parameters: $customToolbarElements, item
fnImgToolbarCustClick
v1.0
Lightbox toolbar custom element.
Fired on click event on image toolbar custom element.
Parameters: customElementName, $customIcon, item
fnProcessData
v1.0
Used to extend data associated to thumbnails/images.
Called each time a new element (image/video or album) is added.
Parameters: item, kind, sourceData
fnPopupMediaInfo
v3.0
Customize the info popup.
Called before the popup for media info is displayed.
Parameters: item, title, content
title: is the default title
content: is the default content of the popup
To change the popup, return an object with the new title and the new content: return {title: my_title, content: my_content};



API methods


Call nanogallery2 function directly in your javascript functions.
Usage: $('#your_nanogallery2').nanogallery2('method', options);

Example:

// Enable selection mode
$('#my_nanogallery2').nanogallery2('option', 'thumbnailSelectable', true);

// Disable selection mode
$('#my_nanogallery2').nanogallery2('option', 'thumbnailSelectable', false);

      


method option(s) description
refresh
v1.0
Force a re-desplay the thumbnails of the displayed gallery.
Usage: $('#your_nanogallery2').nanogallery2('refresh');
resize
v3.0
Force a resize of the displayed gallery.
Usage: $('#your_nanogallery2').nanogallery2('resize');
search
v1.0
search_string Filter the displayed thumbnails based on a search string. Search is done in titles.
Usage: var cnt = $('#your_nanogallery2').nanogallery2('search', search_string);
Returns the number of found items.
view demo on codepen
search2
v1.4
search_title, search_tags Set the filter values to search in titles and tags.
Returns the number of found items.
Usage:
var cnt = $('#your_nanogallery2').nanogallery2('search2', search_in_title, search_in_tags);
view demo on codepen
search2Execute
v1.4
Execute the search on title and tags and filters the displayed thumbnails.
Set the filter value to search in tags.
Returns the number of items to display.
Usage: var cnt = $('#your_nanogallery2').nanogallery2('search2Execute');
view demo on codepen
instance
v1.0
Returns a pointer to the data of the gallery instance.
Usage: $('#your_nanogallery2').nanogallery2('instance');
view demo on codepen
data
v1.0
Returns an object pointing to:
  - items (array): with all the gallery items (albums and medias)
  - gallery (object): the GOM - Gallery Object Model of the current gallery
  - viewer (object): the VOM - Viewer Object Model of the current lightbox

Usage: $('#your_nanogallery2').nanogallery2('data');

Example: get all the items (images and albums)
items=$('#your_nanogallery2').nanogallery2('data').items

Example: retrieve the selected thumbnails
var items=$('#your_nanogallery2').nanogallery2('data').gallery.items;
items.forEach( function(curr) {
  if( curr.selected === true ) {
    console.dir(curr);
  }
});
  
destroy
v1.0
Removes the gallery.
Usage: $('#your_nanogallery2').nanogallery2('destroy');
displayItem
v1.0
item ID Displays an item (album or media).
Usage: $('#your_nanogallery2').nanogallery2('displayItem', 'itemID');
- to display an album: $('#your_nanogallery2').nanogallery2('displayItem', 'albumID');
- to display an image: $('#your_nanogallery2').nanogallery2('displayItem', 'albumID/imageID');
reload
v1.0
Reloads the current album (not for self hosted data).
Usage: $('#your_nanogallery2').nanogallery2('reload');
option
v1.0
option_name Returns the value of an option.
Usage: var optionValue=$('#your_nanogallery2').nanogallery2('option', option_name);
option
v1.0
option_name,
new_value
Sets the value of an option (note: only some options may be changed after gallery initialization).
Usage: $('#your_nanogallery2').nanogallery2('option', option_name, new_value);
itemsSelectedGet
v1.0
Returns an array with all the selected items (array of objects).
Usage: var lstItems=$('#your_nanogallery2').nanogallery2('itemsSelectedGet');
itemsSetSelectedValue
v1.0
[item1, item2, ...] Sets/unsets selection value (true/false) of an array of items.
Usage:
$('#your_nanogallery2').nanogallery2('itemsSetSelectedValue', [item1, item2, ...], new_value);
closeViewer
v1.0
Close the image viewer.
Usage: $('#your_nanogallery2').nanogallery2('closeViewer');
minimizeToolbar
v1.0
Minimize image viewer toolbar.
Usage: $('#your_nanogallery2').nanogallery2('minimizeToolbar');
maximizeToolbar
v1.0
Maximize image viewer toolbar.
Usage: $('#your_nanogallery2').nanogallery2('maximizeToolbar');
shoppingCartGet
v1.0
Returns an array containing all the items in the shopping cart.
One item content: idx=internal index, ID=your image ID, cnt=quantity
Usage: var basket=$('#your_nanogallery2').nanogallery2('shoppingCartGet');
shoppingCartUpdate
v1.0v3.0
media ID, quantity Update the quantity of one media in the shopping cart. Returns the updated shopping cart.
Usage: $('#your_nanogallery2').nanogallery2('shoppingCartUpdate', mediaID, newQuantity);
shoppingCartRemove
v1.0v3.0
media ID Removes one media from the shopping cart. Returns the updated shopping cart.
Usage: $('#your_nanogallery2').nanogallery2('shoppingCartRemove', mediaID);