nanogallery2



nanogallery2 documentation











Some concepts


Basically, to build a gallery, you need to use some content and to define a layout.




1. Gallery content

A gallery is made of items which are composed of an image and/or a thumbnail image, and optional meta-data (title, description, location, exif data, etc.).
List all items with their meta-data in you HTML page. Or, use a data provider to automatically fetch your content to the gallery.
Full usage description is available on the content source page.

  • Self hosted images
    Items are defined in your HTML page.
    Example:
              <div id="my_nanogallery2" data-nanogallery2>
                <a href="img_01.jpg" data-ngthumb="img_01t.jpg" >Title Image1</a>
                <a href="img_02.jpg" data-ngthumb="img_02t.jpg" >Title Image2</a>
                <a href="img_03.jpg" data-ngthumb="img_03t.jpg" >Title Image3</a>
                ...
              </div>
            

  • Self hosted images with module nanoPhotosProvider2
    nanoPhotosProvider2 is a PHP application for your webserver.
    In your page, just point nanogallery2 to your webserver to automatically get all images stored there.
    Usage example:
              <div id="nanogallery2" data-nanogallery2='{
                  "kind":             "nano_photos_provider2",
                  "dataProvider":     "http://mywebsever.com/mypath/nano_photos_provider2/nano_photos_provider2.php",
                  "thumbnailHeight":  150,
                  "thumbnailWidth":   150
                }'>      
              </div>
            

  • Modules for cloud storage
    Optional modules exist to fetch images from Flickr or Google Photos.






2. Gallery layout

3 basic layouts are available: grid, justified and cascading.

  • Grid layout
    All thumbnails have the same size. Define the height and the width of the thumbnails. Images may be cropped to fit the thumbnail.

    Example:
    thumbnailWidth: 300, thumbnailHeight: 200



  • Justified layout
    The width of the thumbnail is calculated to respect the image ratio. There's no cropping and no reordering.
    Set the special value 'auto' to thumbnailWidth

    Example:
    thumbnailWidth: 'auto', thumbnailHeight: 200



  • Cascading layout
    Sometimes also called masonry layout. This layout is column based. Image aspect ratio is conserved, with no cropping.
    Set the special value 'auto' to thumbnailHeight

    Example:
    thumbnailWidth: 300, thumbnailHeight: 'auto'

    The cascading layout may be enhanced by applying a grid with the option thumbnailBaseGridHeight.

    Example:
    thumbnailWidth: 300, thumbnailHeight: 'auto',
    thumbnailBaseGridHeight: 100



  • Mosaic layout
    Enables full control of the layout. The layout is not computed but it is based on a pattern. Images may be cropped to fit the thumbnail. Thumbnails can overlap one another.
    To use it, set the base thumbnail width AND height, and define a pattern for position and real thumbnail size.
    Gallery will be scaled down to fit its container's width if necessary.

    Example:
          thumbnailHeight: '200', thumbnailWidth: '200',
          galleryMosaic : [
              { c: 1, r: 1, w: 2, h: 2 },
              { c: 3, r: 1, w: 1, h: 1 },
              { c: 3, r: 2, w: 1, h: 1 },
              { c: 1, r: 3, w: 1, h: 1 },
              { c: 3, r: 3, w: 2, h: 1 }
          ]
                

    Properties c and r define the position of the thumbnail (column number and row number).
    Properties w and h define the size of the thumbnail (width and height multiplicator).



  • More about gallery layout
    The gallery layout can be tuned with more settings:
    - Thumbnail border size: thumbnailBorderHorizontal, thumbnailBorderVertical
    - Gutter space between thumbnails: thumbnailGutterWidth, thumbnailGutterHeight
    - Thumbnail alignement is configured with the option thumbnailAlignment.







Launching the gallery


There are 2 ways for defining one gallery: HTML markup or Javascript.
Settings are passed to the library on initialization, and are CaSe sEnSiTiVe:

HTML markup method:

use the data-nanogallery2 attribute.

HTML markup example view demo on codepen
<div data-nanogallery2 = '{
    <!-- ### gallery settings ### -->
    "thumbnailHeight":  150,
    "thumbnailWidth":   150,
    "itemsBaseURL":     "http://nanogallery2.nanostudio.org/samples/"
  }'>

  <!-- ### gallery content ### -->
  <a href="img_01.jpg" data-ngthumb="img_01t.jpg">Title Image 1</a>
  <a href="img_02.jpg" data-ngthumb="img_02t.jpg">Title Image 2</a>
  <a href="img_03.jpg" data-ngthumb="img_03t.jpg">Title Image 3</a>
</div>
      
with markup, options must respect the JSON format (and not the javascript object syntax). Property names and string values must be between double-quotes ".

Javascript method:

settings are passed to the nanogallery2() function.
Javascript example view demo on codepen
$("#my_nanogallery2").nanogallery2({
  <!-- ### gallery settings ### -->
  thumbnailHeight:  150,
  thumbnailWidth:   150,
  itemsBaseURL:     'http://nanogallery2.nanostudio.org/samples/',

  <!-- ### gallery content ### -->
  items: [
      { src: 'img_01.jpg', srct: 'img_01t.jpg', title: 'Title Image 1' },
      { src: 'img_02.jpg', srct: 'img_02t.jpg', title: 'Title Image 2' },
      { src: 'img_03.jpg', srct: 'img_03t.jpg', title: 'Title Image 3' }
  ]
});
      


You may also use the visual BUILDER to quickly test some of the available options.












Gesture and touch actions


Standard gesture actions are supported to control the gallery and the lightbox.



1. Gallery touch actions


Open image in lightbox

+

Tap twice

The hover animation is fired on first tap.
Image is displayed in lightbox on second one.
This is the default behaviour.

Single tap

The hover animation is fired on tap, and after a defined delay, the image is automatically displayed in the lightbox.
Use the option touchAutoOpenDelay to enable this behaviour.

Switch to next/previous page

Horizontal swipe

Switch to next/previous gallery page, when option galleryDisplayMode: 'pagination'





2. Lightbox touch actions


Switch to another image

Horizontal swipe

Tap left/right image side

Zoom

Pinch-in/out

Double tap

Pan image

Close lightbox

Swipe down











UI interactions


nanogallery2 includes UI interactions and animations to capture the attention of your visitors.



1. Gallery display animations

Use the option galleryDisplayTransition to define the animation for displaying the gallery.

Possible values: none, slideUp, rotateX.
The duration of the animation is defined with galleryDisplayTransitionDuration.







2. Thumbnail display animations

The display of each individual thumbnail can be animated with the option thumbnailDisplayTransition.

Possible values: none, slideUp, slideDown, scaleUp, scaleDown, fadeIn, randomScale, flipDown, flipUp, slideDown2, slideUp2, slideRight, slideLeft, custom.
Duration is defined in ms, with the option thumbnailDisplayTransitionDuration, and delay between the display of 2 thumbnails is configured with thumbnailDisplayInterval.







3. Thumbnail touch and hover effects

These animations are fired on mouse hover or when the user touch the thumbnail. Multiple animations can be combined.



They are configured with the option thumbnailHoverEffect2: 'effect1|effect2|...'
Where effect is :

  • A predefined preset, like:
    - 'imageGrayOn': to animate image from color to black&white
    - 'scale120': to upscale the thumbnail by 20%
    - 'borderLighter': to make the border color lighter

    Example: thumbnailHoverEffect2: 'imageGrayOn|scale120'

    See here for the list of available presets.

  • Or a customized animation:
    In this case, the syntax of the effect is [element]_[property]_[fromValue]_[toValue]
    Examples:
    - Rotate the image from 0 to 15 degre: 'image_rotateZ_0deg_15deg'
    - Upscale the image: 'image_scale_1.00_1.20'

    To combine both effects: 'image_rotateZ_0deg_15deg|image_scale_1.00_1.20'

    See here for more details.

Additional effect tuning is also available for controling duration, easing, hover out effect, sequential animation, etc.
See the tuning section.




















Reference guide








GALLERY SETTINGS


Configure the behaviour of the gallery.

property default description
thumbnailOpenImage
boolean
v1.0
true Gallery with or without lightbox.
  • true: lightbox is enabled
  • false: lightbox is disabled. No image will be displayed when a thumbnail is clicked/touched.
galleryDisplayMode
string
v1.0
'fullContent' Define the elements to display.

Possible values:
  • 'fullContent': display all thumbnails at once
  • 'moreButton': display N rows and a button to show N more rows (see galleryDisplayMoreStep)
  • 'pagination': display N rows and numbers/dots to paginate the gallery (see galleryMaxRows)
  • 'rows': display maximum N rows (see galleryMaxRows). The number of remaining images is displayed over the last thumbnail.
galleryDisplayMoreStep
integer
v1.0
2 Set the number of rows to display each time the "more button" is hit.

only for galleryDisplayMode: 'moreButton'
galleryPaginationMode
string
v1.0
'rectangles' Display type in pagination mode (galleryDisplayMode: 'pagination').
Possible values:
  • 'rectangles'
  • 'dots'
  • 'numbers'
galleryMaxRows
integer
v1.0
2 Maximum number of rows to display

Only for galleryDisplayMode: 'rows' or galleryDisplayMode: 'pagination'.

Not supported if thumbnailHeight: 'auto'
paginationVisiblePages
integer
v1.0
10 Maximum number of pagination items displayed

only for galleryDisplayMode: 'pagination' and galleryPaginationMode: 'numbers'
paginationSwipe
boolean
v1.0
true Enables swipe gesture to display next/previous gallery page.
galleryLastRowFull
boolean
v1.0
false When enabled, the last thumbnail's row will not be displayed if it doesn't fill the full width.

Only for grid and justified layouts.
gallerySorting
string
v1.0
'' Sort order. No sorting by default.
Possible values: 'titleAsc', 'titleDesc', 'reversed', 'random' (=shuffle).
galleryMaxItems
integer
v1.0
0 Maximum number of items per album. 0 = display all.
galleryResizeAnimation
boolean
v1.0
true Animates the thumbnails to their new position when the gallery/display is resized.
galleryTheme
colorScheme
stringobject
v1.0
'dark' Gallery theme (thumbnails, navigation...).
Possible values: 'dark', 'light'
Custom themes are supported.

since v1.5, properties 'colorScheme' and 'galleryTheme' are synonymous
openOnStart
string
v1.0
Opens the specified album or display the specified image on library start.
Syntax: 'albumID' or 'albumID/imageID'
thumbnailSelectable
boolean
v1.0
false Enable/disable the selection mode. A checkbox is displayed over each thumbnail to allow the user to select multiple thumbnails.
galleryRenderDelay
integer
v1.3
60 Delay in ms before starting the gallery rendering.
thumbnailDisplayOutsideScreen
boolean
v1.2
true Thumbnails are displayed (true) or hidden (false) when they are positioned outside of the screen / viewport.
For better performances with large galleries, use false.
galleryDisplayTransition
string
v1.4
'none' Transition for displaing the gallery. Applied on the whole gallery.
Possible values: 'none', 'rotateX', 'slideUp'
galleryDisplayTransitionDuration
integer
v1.4
1000 Duration of the gallery display transition, in milliseconds.







THUMBNAILS


Configure the layout and the content of the thumbnails.

property default description
thumbnailWidth
integerstring
v1.0
300 MANDATORY
Thumbnails image width in pixels, or 'auto'.
Use 'auto' for justified layout.
thumbnailHeight
integerstring
v1.0
200 MANDATORY
Thumbnails image height in pixels, or 'auto'.
Use 'auto' for cascading/masonry layout.
thumbnailAlignment
string
v1.0
'fillWidth' Horizontal thumbnail alignement in the available space width.
This option is ignored for the justified layout.

Possible values:
  • 'left'


  • 'right'


  • 'center'


  • 'justified'

    Note: the parameter thumbnailGutterWidth is ignored.

  • 'fillWidth' (v2.0+)

    The thumbnails are downscaled to use all the available width.
thumbnailGutterWidth
integer
v1.0
2 Sets the horizontal gutter space between thumbnails.
thumbnailGutterHeight
integer
v1.0
2 Sets the vertical gutter space between thumbnails.
thumbnailBorderHorizontal
integer
v1.0
2 Set the left and right thumbnail border size.
thumbnailBorderVertical
integer
v1.0
2 Set the top and bottom thumbnail border size.
thumbnailFeaturedKeyword
string
v1.0
'*featured' Keyword to set the feature status of a thumbnail. The keyword is searched in the title and the description.
If the keyword is found, the featured icon will be displayed over the thumbnail.
thumbnailDisplayInterval
integer
v1.0
15 Interval in ms between the display of 2 thumbnails (in ms).
thumbnailDisplayTransition
string
v1.0v1.3
'fadeIn' Transition used to display each thumbnail.

Possible values: 'slideUp', 'slideDown', 'scaleUp', 'scaleDown', 'fadeIn', 'randomScale', 'flipDown', 'flipUp', 'slideDown2', 'slideUp2', 'slideRight', 'slideLeft', 'custom'

Note: some values support the syntax TRANISITION_VAL_EASING
where:
- TRANISITION: the name of the display transition
- VAL: a start value for the animation
- EASING: transition easing formula name (optional)

Example: scaleDown_2_bounce

List of values supporting the extended syntax:
- scaleDown: VAL is the start scale factor (default is 1.3)
- scaleUp: VAL is the start scale factor (default is 0.6)
- flipDown: VAL is the start distance in pixel (default is -100)
- flipUp: VAL is the start distance in pixel (default is 100)
- slideDown: VAL is the start distance in pixel (default is -50)
- slideUp: VAL is the start distance in pixel (default is 50)
- slideDown2: VAL is the start distance in pixel (default is -100)
- slideUp2: VAL is the start distance in pixel (default is 100)
- slideRight: VAL is the start distance in pixel (default is -150)
- slideLeft: VAL is the start distance in pixel (default is 150)
thumbnailDisplayTransitionDuration
integer
v1.0
240 Duration of the display transition (in ms).
thumbnailStacks
integer
v1.2
0 Adds N stacks behind each thumbnail. Usefull for thumbnails hover effects
thumbnailWaitImageLoaded
boolean
v1.4
true Waits until thumbails images are fully downloaded before displaying them smoothly.
thumbnailCrop
boolean
v1.0
true If needed, thumbnail image will be cropped to avoid black borders (only for grid layout).
thumbnailSliderDelay
integer
v2.0
2000 Image slider on last displayed thumbnail.
Delay in ms between the display of 2 images.
Set it to 0 to disable it.

Supported when galleryDisplayMode set to 'rows' or to 'fullContent' with galleryLastRowFull enabled.







THUMBNAIL RESPONSIVE SIZES


For a fully responsive gallery, you can define multiple thumbnail sizes for each image.
The used sized is dependant of the screen resolution.
5 screen resolutions are supported: XS (extra-small), SM (small), ME (medium), LA (large), XL (extra-large)
 
  • Use the following syntax to assign multiple values to thumbnailWidth:
    'defaultWidth XSw1 SMw2 MEw3 LAw4 XLw5' where w1 to w5 are the thumbnails widths for resolutions XS to XL.
     
  • and for thumbnailHeight
    'defaultHeight XSh1 SMh2 MEh3 LAh4 XLh5' where h1 to h5 are the heights for resolutions XS to XL.
     
  • Not all values are mandatory. The default value will be used if a value is missing.
  • The value auto is supported.


Examples:

  • Grid layout:
    HTML markup example
      "thumbnailWidth":   "300 XS100 LA400 XL500",
      "thumbnailHeight":  "200 XS80 LA250 XL350"
    Javascript example
      thumbnailWidth:     '300 XS100 LA400 XL500',
      thumbnailHeight:    '200 XS80 LA250 XL350'

  • Grid and justified layout depending on the resolution:
    HTML markup example
      "thumbnailWidth":   "auto XS80 SM120",
      "thumbnailHeight":  "200 XS80 SM120"
    Javascript example
      thumbnailWidth:     'auto XS80 SM120',
      thumbnailHeight:    '200 XS80 SM120'

  • Justified and cascading layout depending on the resolution:
    HTML markup example
      "thumbnailWidth":   "auto XS80 SM120",
      "thumbnailHeight":  "200 XSauto SMauto"
    Javascript example
      thumbnailWidth:     'auto XS80 SM120',
      thumbnailHeight:    '200 XSauto SMauto'








THUMBNAIL LABEL


The label is composed by a title and a description. Set these settings to the thumbnailLabel parameter.

HTML markup example

      <div id="my_nanogallery2" data-nanogallery2 = '{ >
        "thumbnailHeight":    200,
        "thumbnailWidth":     300,
        "thumbnailAlignment": "center",
        "thumbnailLabel":     { "position": "overImageOnBottom", "hideIcons": true },
        ...
      </div>
      


Javascript example
      $("#myNanoGallery").nanogallery2({
        ...
        thumbnailHeight:    200,
        thumbnailWidth:     300,
        thumbnailAlignment: 'center',
        thumbnailLabel:     { position: 'overImageOnBottom', hideIcons: true },
        ...
      });
      




property default description
position
string
v1.0
'overImageOnBottom' Position of the label on the thumbnail.
Possible values: 'overImageOnBottom', 'overImageOnTop', 'overImageOnMiddle', 'onBottom'

align
string
v1.0
'center' Horizontal text alignment.
Possible values: 'right', 'center', 'left'
display
boolean
v1.0
true Displays or hides the label (title and description).
displayDescription
boolean
v1.0
false Displays or hides the description.
hideIcons
boolean
v1.0
true Hides or displays the icons beside the title.
titleMaxLength
integer
v1.0
0 Title maximum length to display.
titleMultiLine
boolean
v1.0
false Title can be multiline (not supported with position:'onBottom').
title
string
v1.0
Variable to set the image title (undescores are replaced by spaces).
Possible values:
- '%filename': use the filemanme without path
- '%filenameNoExt': use the filemanme without path and without extension
titleFontSize
string
v1.0
Set the title font size.
Example: titleFontSize: '2em'
descriptionMaxLength
integer
v1.0
0 Description maximum length to display.
descriptionMultiLine
boolean
v1.0
false Description can be multiline (not supported with position:'onBottom').
descriptionFontSize
string
v1.0
Set the description font size.
Example: descriptionFontSize: '0.8em'







THUMBNAIL - TOUCH AND HOVER EFFECTS


Hover effects are triggered on mouse over or on touch-tap. They are confugured with the thumbnailHoverEffect2 parameter.



Presets

You can set one or multiple presets to the thumbnailHoverEffect2 with the syntax thumbnailHoverEffect2: 'preset1|preset2|...'

Possible presets:

  • Effect on image: 'imageBlurOn', 'imageBlurOff', 'imageGrayOn', 'imageGrayOff', imageSepiaOn', 'imageSepiaOff', 'imageScale150', 'imageScaleIn80', 'imageScale150Outside', 'imageSlideUp', 'imageSlideDown', 'imageSlideRight', 'imageSlideLeft'
  • Effect on tools: 'toolsAppear', 'toolsSlideDown', 'toolsSlideUp'
  • Effect on label: 'labelAppear', 'labelAppear75', 'labelOpacity50', 'scaleLabelOverImage', 'descriptionAppear', 'labelSlideUpTop', 'labelSlideUp', 'labelSlideDown', 'descriptionSlideUp'
  • Effect on whole thumbnail: 'scale120'
  • Effect on thumbnail border: 'borderLighter', 'borderDarker'
  • Misc: 'overScale', 'overScaleOutside', 'slideUp', 'slideDown', 'slideRight', 'slideLeft'

Usage example: thumbnailHoverEffect2: 'borderDarker|labelAppear75'




Advanced usage

For a full control of the effects, use the syntax thumbnailHoverEffect2: 'effect1|effect2|...'

where effectN has the syntax [element]_[property]_[fromValue]_[toValue]

  • [element]: element to apply the transformation.
    Possible values: thumbnail, image, label, description, title, tools, customlayer
  • [property]:
    • any CSS property to apply the animation value
      Example: label_backgroundColor_rgba(255,255,255,0.80)_rgba(255,255,255,0.01)
    • for CSS transform property, just use the transform-function.
      Limited to: translateX, translateY, rotateX, rotateY, rotateZ, scale
      Example: image_rotateZ_0deg_15deg
    • for CSS filters, just use the visual effect.
      Limited to: blur, brightness, grayscale, sepia, contrast, opacity, saturate
      Example: 'image_grayscale_0%_100%
  • [fromValue]: initial value
  • [toValue]: value at the end of the transformation


Live example on codepen: demo - advanced thumbnail hover effect

Some examples:

  • One hover effect:
    • Remove the sepia filter on the image: thumbnailHoverEffect2: 'image_sepia_100%_1%'
    • Apply a blur filter on the image: 'image_blur_0.00px_2.00px'
    • Rotate the image from 0degre to 15degre: 'image_rotateZ_0deg_15deg'
    • Apply a grayscale filter the image: 'image_grayscale_0%_100%'
    • Zoom the image in: image_scale_1.00_1.20
    • Zoom the image out: image_scale_1.20_1.00
    • Change the transparency of label background: 'label_backgroundColor_rgba(255,255,255,0.80)_rgba(255,255,255,0.01)'
    • Apply a red colorization on the image: customlayer_backgroundColor_rgba(160,0,0,0.0)_rgba(160,0,0,0.5)
    • Change the transparency of the icons: tools_opacity_1_0.5
    • Change the image contrast: image_contrast_1_4
    • Change the image brightness: image_brightness_1_2
  • Two hover effects:
    • Apply a grayscale filter and rotate the image: thumbnailHoverEffect2:'image_grayscale_0%_100%|image_rotateZ_0deg_15deg'


Initialization In some case, it's interesting to set CSS properties but without any animation.
For this, use the option thumbnailBuildInit2: : 'init1|init2|...' where initN has the syntax: [element]_[property]_[Value].
Example : thumbnailBuildInit2: 'image_scale_1.20'




Additional tuning

Fine tuning settings: duration, delay, easing, back duration, back delay, beack easing, hoverin, hoverout, first keyframe
syntax:

    thumbnailHoverEffect2: { 
      name:           '[effectName]',
      delay:          0,
      duration:       400,
      easing:         'easeOutQuart',
      delayBack:      0,
      durationBack:   300,
      easingBack:     'easeOutQuart',
      hoverin:        true,
      hoverout:       true,
      firstKeyframe:  true
    }

where:
  • duration: the duration of the effect in ms
  • delay: the delay in ms before the transformation is started
  • easing: specify the rate of change of the transformation over time (see easings.net)
    • Possible values:
      easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint, easeInSine, easeOutSine, easeInOutSine, easeInExpo, easeOutExpo, easeInOutExpo, easeInCirc, easeOutCirc, easeInOutCirc, easeOutBounce, easeInBack, easeOutBack, easeInOutBack, elastic, bounce
  • durationBack: duration of the effect to initial state, in ms
  • delayBack: start delay back transformation in ms
  • easingBack: easing used for the back transformation
  • hoverin: used on hover in
  • hoverout: used on hover out
  • firstKeyframe: used for chained animations
Note: name is the only mandatory proprety.
Some examples:
  • thumbnailHoverEffect2: { name: 'imageBlurOn', duration: 800, easing: 'easeInCubic', delayBack: 0, durationBack: 300, easingBack: 'easeOutQuart' }
  • thumbnailHoverEffect2: { name: 'image_rotateZ_0deg_15deg', duration: 800, durationBack: 500}
  • combination of 2 effects:
    thumbnailHoverEffect2: [{ name: 'image_scale_1.00_1.20', duration: 500}, { name: 'image_rotateZ_0deg_15deg', delay: 500}]





Stacks

Stacks can be added behind thumbnails to create nice hover effects. Their color is defined in the galleryTheme.
Use thumbnailStacks and thumbnailL1Stacks to define then number of stacks.

The thumbnail animation is applied to the stack, but with a percent value.
For example, if thumbnailStacksRotateX is set to 0.4, then the 1st stack will have a percent of 0.6 applied to the rotationX value of the thumbnail.

For the second stack, the percent will be 0.2, for the third one it will be -0,2, and so on.

Possible parameters to set these percents: 'thumbnailStacksTranslateX', 'thumbnailStacksTranslateY', 'thumbnailStacksTranslateZ', 'thumbnailStacksRotateX', 'thumbnailStacksRotateY', 'thumbnailStacksRotateZ', 'thumbnailStacksScale'








THUMBNAIL - TOOLS


Each corner of one thumbnail has a toolbar. You can customize each of these toolbars. Customization is specific for albums and for images.

property default description
thumbnailToolbarImage
object
v1.0
Image toolbars
Syntax: thumbnailToolbarImage: { topLeft:'', topRight: '', bottomLeft: '', bottomRight: ''}
Possible tools: 'select', 'share', 'featured', 'download', 'cart', 'info'

Default:
thumbnailToolbarImage : { topLeft: 'select', topRight : 'featured' }
thumbnailToolbarAlbum
object
v1.0
Album toolbars
Syntax: thumbnailToolbarAlbum: { topLeft:'', topRight: '', bottomLeft: '', bottomRight: ''}
Possible tools: 'select', 'share', 'counter', 'counter2', 'cart'

Default:
thumbnailToolbarAlbum : { topLeft: 'select', topRight : 'counter' }







NAVIGATION


Configure how the user can navigate in albums, filter the thumbnails based on tags, and the touch/tap handling.

property default description
displayBreadcrumb
boolean
v1.0
true Display the breadcrumb for navigation in albums.
breadcrumbOnlyCurrentLevel
boolean
v1.0
true Display only the name of the current album.
breadcrumbAutoHideTopLevel
boolean
v1.0
true No breadcrumb on albums first navigation level.
breadcrumbHideIcons
boolean
v1.0
Hide or display breadcrumb's icons.
galleryFilterTags
booleanstring
v1.0
false Display tags to filter the thumbnails.
Possible values:
- false: disabled
- true: enabled
- 'title': extract the tags from the title (string starting with #)
- 'description': extract the tags from the description (string starting with #)
thumbnailLevelUp
boolean
v1.0
false Display one thumbnail to navigate in the parent album.
locationHash
boolean
v1.0
true Enables hash tracking.
This will activate browser Back/Forward navigation (browser history support) and Deep Linking of images and photo albums.
Must be enabled to allow sharing of images/albums.
Note: only one gallery per HTML page should use this feature.
touchAnimation
boolean
v1.0
true Enables thumbnail hover animation on touch event.
The user must tap a thumbnail twice to show the image or open a album.
touchAutoOpenDelay
integer
v1.0
0 When a user touch a thumbnail, delay in ms before opening the touched thumbnail.
Particular values:
-1 = disabled (user needs to tap twice to open the thumbnail),
 0 = automatic (the library will calculate automatically the delay).
Note: the parameter is ignored when touchAnimation=false.
navigationFontSize
string
v1.0
Define the font size for the navigation (breadcrumb and filters).
Example: navigationFontSize: '1.2em'







GALLERY - FIRST ALBUM LEVEL SPECIFIC OPTIONS


Settings can be defined specificaly for the first album level (root level) and for the other ones.
Default settings are used for all album levels (including the first one).

Example: define a grid layout for the first level, and a justified layout for all other levels

HTML markup example

      <div id="my_nanogallery2" data-nanogallery2 = '{ >
        "thumbnailHeight":    200,
        "thumbnailWidth":     "auto",
        "thumbnailL1Height":  300,
        "thumbnailL1Width":   300,
        ...
      </div>
      

Javascript example
      $("#myNanoGallery").nanogallery2({
        ...
        thumbnailHeight:    200,
        thumbnailWidth:     "auto",
        thumbnailL1Height:  300,
        thumbnailL1Width:   300,
        ...
      });
      



Availables options for level 1:

  • Global

    v1.0 touchAnimationL1

  • Gallery

    v1.0 galleryL1DisplayMode, galleryL1MaxRows, galleryL1LastRowFull, galleryL1FilterTags, galleryL1MaxItems, galleryL1Sorting
    v1.4 galleryL1DisplayTransition, galleryL1DisplayTransitionDuration
    v2.0 galleryL1Mosaic

  • Thumbnails

    v1.0 thumbnailL1Height, thumbnailL1Width, thumbnailL1Crop, thumbnailL1Label, thumbnailL1HoverEffect2
    v1.2 thumbnailL1GutterWidth, thumbnailL1GutterHeight,
    thumbnailL1Stacks, thumbnailL1StacksScale, thumbnailL1StacksTranslateX, thumbnailL1StacksTranslateY, thumbnailL1StacksTranslateZ, thumbnailL1StacksRotateX, thumbnailL1StacksRotateY, thumbnailL1StacksRotateZ
    v1.3 thumbnailL1DisplayTransition, thumbnailL1DisplayTransitionDuration, thumbnailL1DisplayInterval
    v2.0 thumbnailL1BaseGridHeight








IMAGE DISPLAY - LIGHTBOX


The lightbox is used to display images in full size.

The available tools can be displayed in each of the 3 toolbars (standard, top-left and top-right). The standard toolbar has 2 states which are toggled with the 'minimizeButton' tool. Each state has is own configuration.

Possible tools: 'previousButton', 'pageCounter', 'nextButton', 'playPauseButton', 'fullscreenButton', 'infoButton', 'linkOriginalButton', 'closeButton', 'downloadButton', 'zoomButton', 'shareButton', 'label' (image title and description), 'customN'
To add custom elements in a toolbar, use the label customN, where N is an integer (e.g. custom1, custom2...).


HTML markup example view demo on codepen

<div id="my_nanogallery2" data-nanogallery2 = '{ >
  "viewerToolbar":   {
       "standard":   "minimizeButton, label, shareButton, fullscreenButton",
       "minimized":  "minimizeButton, label, fullscreenButton, downloadButton, infoButton" },
   "viewerTools":    {
        "topLeft":   "label",
        "topRight":  "playPauseButton, zoomButton, fullscreenButton, closeButton" }   
  ...
</div>
      


Javascript example view demo on codepen
viewerToolbar:    {
         standard:  'minimizeButton, label, shareButton, fullscreenButton',
         minimized: 'minimizeButton, label, fullscreenButton, downloadButton, infoButton' },
 viewerTools:    {
         topLeft:   'label',
         topRight:  'playPauseButton, zoomButton, fullscreenButton, closeButton' }   
      




property default description
imageTransition
string
v1.0v2.3.0
'swipe2' Tranistion from one media to the next one.
Possible values: 'slideAppear', 'swipe', 'swipe2'.
slideshowAutoStart
boolean
v1.0
false Starts automatically the slideshow when an image is displayed.
slideshowDelay
integer
v1.0
3000 Duration of the photo display in slideshow mode (in ms).
viewerHideToolsDelay
integer
v1.3
3000 Delay of inactivity before hidding the tools and labels.
viewerFullscreen
boolean
v1.0
false Displays images in fullscreen (on supported browser).
viewerToolbar
object
v1.0
Display options for the lightbox main toolbar.
display
boolean
v1.0
true Displays/hides the main toolbar.
position
string
v1.0
'bottomOverImage' Vertical position.
Possible values: 'top', 'topOverImage', 'bottom', 'bottomOverImage'
align
string
v1.0
'center' Horizontal alignement.
Possible values: 'left', 'right', 'center'
fullWidth
boolean
v1.0
false Toolbar is as width as the screen.
autoMinimize
integer
v1.0
800 Breakpoint for switching between minimized and standard toolbar.
If the width is lower than this value, the toolbar is switched to minimized.
standard
string
v1.0
List of items to display in the standard toolbar (comma separated).
For this toolbar, 'minimizeButton' is additionally available.
Default value:
viewerToolbar: { standard :'minimizeButton, label'}
minimized
string
v1.0
List of items to display in the minimized toolbar (comma separated).
For this toolbar, 'minimizeButton' is additionally available.
Default value:
viewerToolbar: { standard :'minimizeButton, label, infoButton, shareButton, downloadButton, linkOriginalButton, fullscreenButton'}
viewerTools
object
v1.0
Tools positionned in the corners.
topLeft
string
v1.0
Toolbar positioned in the top left corner.
Default value:
viewerTools : { topLeft: 'pageCounter, playPauseButton'}
topRight
string
v1.0
Toolbar positioned in the top right corner.
Default value:
viewerTools : { topRight: 'zoomButton, closeButton'}
viewerTheme
colorSchemeViewer
stringobject
v1.0v1.5
'dark' Image display theme.
Possible values: 'dark', 'light', 'border'.
Custom themes are supported.

since v1.5, properties 'colorSchemeViewer' and 'viewerTheme' are synonymous
viewerDisplayLogo
boolean
v1.0
false To display a logo over the image.
viewerImageDisplay
string
v1.5
Manage the image display zoom factor.

Possible values:
  - '': no not apply any zoom factor
  - 'bestImageQuality': display images smaller for a better quality (on high DPI screens like Retina, etc.)
  - 'upscale': upscale image to screen size
viewerTransitionMediaKind
string
v2.0
'img' Enables or disables the display transition for each media kind.
Supported values: 'img', 'iframe'
Example: viewerTransitionMediaKind: 'img,iframe'







GLOBAL SETTINGS





property default description
eventsDebounceDelay
integer
v2.2
50 Thumbnail's lazy display fine tuning
Response delay in ms after resizing, rotation and scroll events.







CUSTOM ICONS


All icons used in nanogallery2 can be customized. By default, a custom icon font is used.

Example: replace the default album icon with a red one from Font Awesome:

HTML markup example

      <div id="my_nanogallery2" data-nanogallery2 = '{ >
        ...
        "icons":    {
          "thumbnailAlbum": "<i style='color:#e00;' class='fa fa-search-plus'></i>"
        }
        ...
      </div>
      

Javascript example view demo on codepen
      $("#myNanoGallery").nanogallery2({
        ...
        icons: {
          thumbnailAlbum: '<i style="color:#e00;" class="fa fa-search-plus"></i>'
        }
        ...
      });
      


List of default icons:
// BREADCRUMB:
breadcrumbAlbum:              '<i class="nGY2Icon-folder-empty"></i>'        // album icon
breadcrumbHome:               '<i class="nGY2Icon-home"></i>'                // home icon
breadcrumbSeparator:          '<i class="nGY2Icon-left-open"></i>'           // separator icon
breadcrumbSeparatorRtl:       '<i class="nGY2Icon-right-open"></i>'          // separator RTL icon

// FILTERS:
navigationFilterSelected:     '<i style="color:#bff;" class="nGY2Icon-toggle-on"></i>' // selected icon
navigationFilterUnselected:   '<i class="nGY2Icon-toggle-off"></i>'          // unselected icon
navigationFilterSelectedAll:  '<i class="nGY2Icon-toggle-off"></i>'          // unselect all icon

// THUMBNAILS:
thumbnailAlbum:               '<i class="nGY2Icon-folder-empty"></i>'        // album icon 
thumbnailImage:               '<i class="nGY2Icon-picture"></i>'             // image icon
thumbnailSelected:            '<i class="nGY2Icon-ok-circled"></i>'          // selected icon
thumbnailUnselected:          '<i class="nGY2Icon-circle-empty"></i>'        // unselected icon
thumbnailFeatured:            '<i style="color:#ffa;" class="nGY2Icon-star"></i>'  // featured icon
thumbnailCounter:             '<i class="nGY2Icon-picture"></i>'             // image icon
thumbnailShare:               '<i class="nGY2Icon-share"></i>'               // share icon
thumbnailDownload:            '<i class="nGY2Icon-download"></i>'            // download icon
thumbnailInfo:                '<i class="nGY2Icon-ngy2_info2"></i>'          // info icon
thumbnailCart:                '<i class="nGY2Icon-basket"></i>'              // add to shopping cart icon
thumbnailDisplay:             '<i class="nGY2Icon-ngy2_zoom_in2"></i>'       // display image icon
thumbnailCustomTool[1..10]:   'T1..T10'                                                       // custom tool 1 to 10
thumbnailAlbumUp:             '<i style="font-size: 3em;" class="nGY2Icon-level-up"></i>'  // album up icon

// GALLERY:
paginationNext:               '<i class="nGY2Icon-right-open"></i>'          // pagination - next page icon
paginationPrevious:           '<i class="nGY2Icon-left-open"></i>'           // pagination - previous page icon
galleryMoreButton:            '<i class="nGY2Icon-picture"></i>   <i class="nGY2Icon-right-open"></i>' // close button icon

// LIGHTBOX:
buttonClose:                  '<i class="nGY2Icon-ngy2_close2"></i>'         // close button icon
viewerPrevious:               '<i class="nGY2Icon-ngy2_chevron-left"></i>'   // icon for previous image (toolbar)
viewerNext:                   '<i class="nGY2Icon-ngy2_chevron-right"></i>'  // icon for next image (toolbar)
viewerImgPrevious:            '<i class="nGY2Icon-ngy2_chevron_left3"></i>'  // icon for previous image (on the left side of the image)
viewerImgNext:                '<i class="nGY2Icon-ngy2_chevron_right3"></i>' // icon for next image (on the right side of the image)
viewerDownload:               '<i class="nGY2Icon-ngy2_download2"></i>'      // icon image download (toolbar)
viewerToolbarMin:             '<i class="nGY2Icon-ellipsis-vert"></i>'       // icon for minimized toolbar
viewerToolbarStd:             '<i class="nGY2Icon-menu"></i>'                // icon for maximized toolbar
viewerPlay:                   '<i class="nGY2Icon-play"></i>'                // icon play - to start the slideshow (toolbar)
viewerPause:                  '<i class="nGY2Icon-pause"></i>'               // icon pause - to stop the slideshow (toolbar)
viewerFullscreenOn:           '<i class="nGY2Icon-resize-full"></i>'         // icon to switch on fullscreen (toolbar)
viewerFullscreenOff:          '<i class="nGY2Icon-resize-small"></i>'        // icon to switch off fullscreen (toolbar)
viewerZoomIn:                 '<i class="nGY2Icon-ngy2_zoom_in2"></i>'       // icon zoom in (toolbar)
viewerZoomOut:                '<i class="nGY2Icon-ngy2_zoom_out2"></i>'      // icon zoom out (toolbar)
viewerLinkOriginal:           '<i class="nGY2Icon-ngy2_external2"></i>'      // icon link to original image (toolbar)
viewerInfo:                   '<i class="nGY2Icon-ngy2_info2"></i>'          // icon infobox (toolbar)
viewerShare:                  '<i class="nGY2Icon-ngy2_share2"></i>'         // icon share link (toolbar)
user:                         '<i class="nGY2Icon-user"></i>'                // icon author (infobox)
location:                     '<i class="nGY2Icon-location"></i>'            // icon location on Google Maps (infobox)
config:                       '<i class="nGY2Icon-wrench"></i>'              // icon config for EXIF (infobox)
viewerCustomTool[1..10]:      'T1..T10'                                           // custom tool 1 to 10

// SHARE:
shareFacebook:                '<i style="color:#3b5998;" class="nGY2Icon-facebook-squared"></i>'   // icon Facebook
shareTwitter:                 '<i style="color:#00aced;" class="nGY2Icon-twitter-squared"></i>'    // icon Twitter
shareGooglePlus:              '<i style="color:#dd4b39;" class="nGY2Icon-gplus-squared"></i>'      // icon Google plus
shareTumblr:                  '<i style="color:#32506d;" class="nGY2Icon-tumblr-squared"></i>'     // icon Tumblr
sharePinterest:               '<i style="color:#cb2027;" class="nGY2Icon-pinterest-squared"></i>'  // icon Pinterest
shareVK:                      '<i style="color:#3b5998;" class="nGY2Icon-vkontakte"></i>'          // icon Pinterest
shareMail:                    '<i  style="color:#555;" class="nGY2Icon-mail-alt"></i>'             // icon mail-to
      








THEMES


Themes allow you to customize some elements without changing the CSS file.
Two separated themes can be set: one for the gallery (galleryTheme), and one for the lightbox (viewerTheme).
For each one, 2 templates can be used: dark (default valude) and light. You can define your own customized theme.

Example:
To change the background and the boder color of the thumbnails
1. define one theme: var myCS= { thumbnail : { background: '#F00', borderColor: '#F00' } };
2. assign it to the gallery: galleryTheme: myCS

Gallery theme format (with default values):

{
  navigationBar:        { background: 'none', borderTop: '', borderBottom: '', borderRight: '', borderLeft: '' },
  navigationBreadcrumb: { background: '#111', color: '#fff', colorHover: '#ccc', borderRadius: '6px' },
  navigationFilter :    { color: '#ddd', background: '#111', colorSelected: '#fff', backgroundSelected: '#111', borderRadius: '6px' },
  thumbnail:            { background: '#444', backgroundImage: 'linear-gradient(315deg, #111 0%, #557 90%)', borderColor: '#000', labelOpacity : 1, labelBackground: 'rgba(34, 34, 34, 0)', titleColor: '#eee', titleBgColor: 'transparent', titleShadow: '', descriptionColor: '#ccc', descriptionBgColor: 'transparent', descriptionShadow: '', stackBackground: '#aaa' },
  thumbnailIcon:        { padding: '5px', color: '#fff' },
  pagination:           { background: '#111', backgroundSelected: '#666', color: '#fff', borderRadius: '2px', shapeBorder: '3px solid #666', shapeColor: '#444', shapeSelectedColor: '#aaa'}
}
    

Lightbox theme format (with default values):

{
  background:     '#000', imageBorder: 'none', imageBoxShadow: 'none',
  barBackground:  'rgba(4, 4, 4, 0.7)', barBorder: '0px solid #111', barColor: '#eee', barDescriptionColor: '#aaa'
}
    







UPGRADING FROM nanoGALLERY


nanogallery2 comes with an interesting set of new features that should streamline your development experience.

Due to many enhancements, nanogallery2 is not 100% compatible with nanoGALLERY.
In particular, the thumbnail hover effects engine has been rewritten: the option thumbnailHoverEffect is now replaced by thumbnailHoverEffect2.
Here's the list of depreciated and no more supported options.
property comment
thumbnailHoverEffect replaced by thumbnailHoverEffect2
picasaUseUrlCrossDomain no more needed
albumList replaced by albumList2
galleryToolbarWidthAligned
galleryToolbarHideIcons Replaced by breadcrumbHideIcons. Each icon can now be customized with the icons option.
galleryFullpageButton
galleryFullpageBgColor
galleryRenderStep
itemsSelectable
keepSelection
showCheckboxes
checkboxStyle
selectMode
thumbnail selection is now managed by the thumbnailSelectable option.
paginationMaxLinesPerPage replaced by galleryMaxRows and galleryL1MaxRows
paginationDots replaced by galleryPaginationMode
albumMax replaced by galleryMaxItems and galleryL1MaxItems - ignored for self hosted images.
photoSorting
albumSorting
dataSorting
replaced by gallerySorting and galleryL1Sorting
thumbnailLazyLoad
thumbnailLazyLoadTreshold
lazyBuild
lazyBuildTreshold
managed automatically
maxWidth
thumbnailAdjustLastRowHeight is now the standard behaviour
fnChangeSelectMode use fnThumbnailSelection instead.
fnThumbnailHoverResize
setUnselectedItems
setSelectedItems
use itemsSetSelectedValue instead.
getSelectedItems use itemsSelectedGet instead.
paginationPreviousPage
paginationNextPage
paginationCountPages
paginationGotoPage
galleryCountImages
moveToNextAlbum
moveToPreviousAlbum
viewerToolbar.style
callbacks comment
fnViewerInfo No more used. Please replace with toolbar custom buttons (fnImgToolbarCustInit, fnImgToolbarCustClick)
fnInitGallery replaced and enhanced by fnGalleryRenderStart and fnGalleryRenderEnd
API methods comment
getItems Instead, use data to get a pointer to an array containing all the items.
Example: $('#your_nanogallery2').nanogallery2('data').items;
getItem replaced by: $('#your_nanogallery2').nanogallery2('data').items[item_index];
getItemsIndex no more needed
refreshSize refresh







TIPS AND TRICKS


Recommandations / Performances / FAQ

Thumbnails hover effects:

  • do not combine too much effects (smooth animation on a computer may be slow on a mobile device).

Self hosted images:

  • define each thumbnail's size.

  • define each image's size.

Social sharing:

  • Assign an ID to the DIV containing the gallery.

  • Each album and image must have an ID defined.

  • IDs should never been changed.








SECURITY



By default, HTML tags cannot be used in titles and descriptions of images.
To enable HTML tags, set the option allowHTMLinData: true.
Be aware that this could lead to XSS (cross site scripting) vulnerability.








BROWSER SUPPORT


Firefox 6+ - Chrome 16+ - Edge 13+ - IE 10+ - Opera 12.1+ - Yandex 14.12+ - iPhone 5+ / iOS 6+ - Safari 6.2+
(some features may not be available on every platform).

Testing services provided by BrowserStackbrowserstack