nanogallery2 documentation

First things that you should know before you start:
- To install and configure nanogallery2, basic Javascript and HTML knowledge is required.
- For your gallery, you need some content and you must define a layout.

1. Gallery content

The content of a gallery consists of a list of media items.

Each item should contain at least: a path to a media (image or video) and a path to a thumbnail image.
Additional properties can be set: thumbnail image height and width, string, description, responsive thumbnail images, blurred preview images, tags, exif data, IDs, album...

<div id="my_nanogallery2" data-nanogallery2>
      <a href="img_01.jpg" data-ngthumb="img_01t.jpg">title 1</a>
      <a href="img_02.jpg" data-ngthumb="img_02t.jpg">title 2</a>
      <a href="img_03.jpg" data-ngthumb="img_03t.jpg">title 3</a>
      ...
    </div>
    

items: [
      { src: 'img_01.jpg', srct: 'img_01t.jpg', title: 'Title 1' },
      { src: 'img_02.jpg', srct: 'img_02t.jpg', title: 'Title 2' },
      { src: 'img_03.jpg', srct: 'img_03t.jpg', title: 'Title 3' }
    ]
    
     

The list of media items can also be generated automatically by an optional external data provider, like nano_photos_provider2 for example.

Check the content setup page for full documentation.

2. Gallery design

Gallery layout

4 basic layouts are available. To configure the layout of your gallery, you have to define the display height and width of one thumbnail. For mosaic layout, you need also a display pattern.

Grid layout

Justified layout

Cascading layout

Mosaic layout

Examples for grid layout

<div id="nanogallery2" data-nanogallery2='{
    ...
    "thumbnailHeight": 200,
    "thumbnailWidth":  200   
  }'>
</div>
      

$("#my_nanogallery2").nanogallery2({
  ...
  thumbnailHeight:  200,
  thumbnailWidth:   200
});

      

thumbnailHeight is the height of the thumbnails, in pixels. thumbnailWidth is the width, in pixels.

Thumbnails

You can define the alignement, the border width, the gutter between thumbnails, the content (title, description, tools...), themes, stacks, display animation, and hover/touch effects.

3. Lightbox

No setup is required for displaying medias from the gallery.
For customizing, read the lightbox setup section.

4. Global settings

In addition to content and layout, you can also configure global settings which are applied to nanogallery2.

Some examples

- set the global path to medias and thumbnail images: parameter itemsBaseURL
- set one thumbnail display animation: parameter thumbnailDisplayTransition
- define one hover effect on thumbnails: parameter thumbnailHoverEffect2

"itemsBaseURL":               "https://nanogallery2.nanostudio.org/samples",
"thumbnailDisplayTransition": "scaleDown",    
"thumbnailHoverEffect2":      "scale120"
    

itemsBaseURL:               'https://nanogallery2.nanostudio.org/samples',
thumbnailDisplayTransition: 'scaleDown',
thumbnailHoverEffect2:      'scale120'
    

5. All together

You're now ready to put everything together. Your gallery can be configured in javascript or in HTML markup.
Settings are passed to the library on initialization, and are CaSe sEnSiTiVe.

HTML markup method:

use the data-nanogallery2 attribute.

<div id="my_nanogallery2" data-nanogallery2 = '{
		<!-- ### gallery settings ### -->
			"thumbnailHeight":  150,
			"thumbnailWidth":   150,
			"itemsBaseURL":     "https://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>

Javascript method:

Settings are passed to the nanogallery2() function.

$("#my_nanogallery2").nanogallery2({
  // ### gallery settings ###
  thumbnailHeight:  150,
  thumbnailWidth:   150,
  itemsBaseURL:     'https://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' }
  ]
});

Gallery standalone

The gallery can be used without lightbox: no big image is displayed when one user clicks a thumbnail.
Set the option thumbnailOpenInLightox to false.

Lightbox standalone

The lightbox can be used to display medias in fullscreen, without having a gallery managed by nanogallery2.

For this, add the attribut data-nanogallery2-lightbox to the <html> elements, which need to be linked to the lightbox. This will bind the click/touch event to nanogallery2.

<img 
  src = "thumbnail_image_1.jpg"                                     <!-- thumbnail image -->
  data-ngsrc = "big_image_1.jpg"                                    <!-- big image -->
  data-nanogallery2-lightbox = '{ "viewerGallery ": "none" }'       <!-- lightbox configuration (optional) -->
/>
<img src="thumbnail_image_2.jpg" data-ngsrc="big_image_2.jpg" data-nanogallery2-lightbox />
<img src="thumbnail_image_3.jpg" data-ngsrc="big_image_3.jpg" data-nanogallery2-lightbox />
<a href="big_image_4.jpg"/ data-ngthumb="thumbnail_image_4.jpg" data-nanogallery2-lightbox>media title</a>
<a href="big_image_5.jpg"/ data-nanogallery2-lightbox>
  <img src="thumbnail_image_5.jpg" alt="media title"/>
</a>

Attribute data-nanogallery2-lgroup can be used to group medias to be displayed in the same lightbox instance. For the list of supported attributes, read the HMTL markup content definition chapter.

Layouts

Let's see the details of the 4 basic layouts: grid, justified, cascading and mosaic.

Grid layout

All thumbnails have the same size. The display height and the width of the thumbnails must be defined. Thumbnail's image may be cropped to fit the defined size.

HTML markup example    

  "thumbnailWidth":   300,
  "thumbnailHeight":  200
        

Grid layout

Justified layout

All thumbnails in one row are scaled down to the same height. The width of the thumbnail is calculated to respect the thumbnail's image ratio. Row height may vary but will not exceed the defined height. There's no cropping and no reordering.
To use this layout, set the special value auto to the thumbnailWidth property.

HTML markup example    

  "thumbnailWidth":   "auto",
  "thumbnailHeight":  200
        

It is highly recommended to set the size of each thumbnail image, for justified layout.

Justified layout

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 the thumbnailHeight property.

HTML markup example    

  "thumbnailWidth":   200,
  "thumbnailHeight":  "auto"
        

Cascading layout

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

HTML markup example    

  "thumbnailWidth":           200,
  "thumbnailHeight":          "auto",
  "thumbnailBaseGridHeight" : 100
        

It is highly recommended to set the size of each thumbnail image, for cascading layout.

Enhanced cascading layout

Mosaic layout

Enables full control of the layout. The layout is not computed but is based on a pattern. Images may be cropped to fit the thumbnail's size. 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.

HTML markup 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).

Mosaic layout

Gesture and touch actions

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

Gallery touch actions

Display media 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'

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 or up

Animations

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

Gallery display animation

Use the option galleryDisplayTransition to define the animation for displaying the whole gallery.
Possible values: none, slideUp, rotateX.
The duration of the animation is defined in ms with galleryDisplayTransitionDuration.

Example

      "galleryDisplayTransition":         "slideUp",
      "galleryDisplayTransitionDuration":  500   
      

      galleryDisplayTransition:         'slideUp',
      galleryDisplayTransitionDuration:  500   
      

Demonstration

Thumbnail display animation

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 in ms with thumbnailDisplayInterval.

Example

  "thumbnailDisplayTransition":          "scaleUp",
  "thumbnailDisplayTransitionDuration":  500,  
  "thumbnailDisplayInterval":            30   
        

  thumbnailDisplayTransition:          'scaleUp',
  thumbnailDisplayTransitionDuration:  500,
  thumbnailDisplayInterval:            30   
        

Demonstration

Combining thumbnail and gallery display animation

Booth thumbnail display animation and gallery display animation can be combined to produce nice effects.

Example

  "thumbnailDisplayTransition":          "slideUp2",
  "thumbnailDisplayTransitionDuration":  500,  
  "thumbnailDisplayInterval":            30,   
  "galleryDisplayTransition":            "rotateX",
  "galleryDisplayTransitionDuration":    500   
        

  thumbnailDisplayTransition:          'slideUp2',
  thumbnailDisplayTransitionDuration:  500,
  thumbnailDisplayInterval:            30,   
  galleryDisplayTransition:            'rotateX',
  galleryDisplayTransitionDuration:    500   
        

Demonstration

Thumbnail touch and hover effects

These animations are fired on mouse hover or when the user touches 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.

GALLERY SETTINGS

Configuration of the general behaviour of the gallery.

THUMBNAILS

Configure layout and display animations of the thumbnails.

property	default	description
Thumbnail layout
thumbnailWidth thumbnailL1Width v1.0integerstring	300	Thumbnails image width in pixels, or 'auto'. Responsive sizes are supported (format 'default XSn SMn MEn LAn XLn') Use 'auto' for a gallery with justified layout.
thumbnailHeight thumbnailL1Height v1.0integerstring	200	Thumbnails image height in pixels, or 'auto'. Responsive sizes are supported (format 'default XSn SMn MEn LAn XLn') Use 'auto' for a gallery with cascading/masonry layout.
thumbnailAlignment v1.0string	'fillWidth'	Horizontal thumbnail alignement in the available width. This option is ignored for the justified layout. Possible values: 'left' 'right' 'center' 'justified' (property thumbnailGutterWidth ignored) 'fillWidth' v2.0 Thumbnails are downscaled to use the full available width.
thumbnailGutterWidth thumbnailL1GutterWidth thumbnailGutterHeight thumbnailL1GutterHeight v1.0integerv3.0string	2	Sets the horizontal and vertical gutter space between thumbnails. Since v3: responsive sizes are also supported (format 'default XSn SMn MEn LAn XLn')
thumbnailBorderHorizontalv1.0 thumbnailL1BorderHorizontalv3.0 thumbnailBorderVerticalv1.0 thumbnailL1BorderVerticalv3.0 integer	2	Set the horizontal (left and right) / vertical (top and bottom) thumbnail border size.
thumbnailStacks thumbnailL1Stacks v1.2integer	0	Adds N stacks behind each thumbnail. Usefull for thumbnails hover effects
thumbnailSliderDelay v2.0integer	2000	Image slider on last displayed thumbnail. Set the delay in ms between the display of 2 images (value 0: disabled). Supported when galleryDisplayMode set to 'rows' or to 'fullContent' with galleryLastRowFull enabled.
Thumbnail display animation
thumbnailDisplayInterval thumbnailL1DisplayInterval v1.0integer	15	Interval in ms between the display of 2 thumbnails (in ms).
thumbnailDisplayOrder thumbnailL1DisplayOrder v3.0string	''	Thumbnail's display order. Possible values: '', 'random'
thumbnailDisplayTransition thumbnailL1DisplayTransition v1.0v1.3string	'fadeIn'	Transition used to display each individual thumbnail. Possible values: 'slideUp', 'slideDown', 'scaleUp', 'scaleDown', 'fadeIn', 'randomScale', 'flipDown', 'flipUp', 'slideDown2', 'slideUp2', 'slideRight', 'slideLeft', 'imageSlideUp', 'custom'
thumbnailDisplayTransitionDuration thumbnailL1DisplayTransitionDuration v1.0integer	240	Duration of the display transition (in ms).
thumbnailDisplayTransitionEasing thumbnailL1DisplayTransitionEasing v3.0string	'easeOutQuart'	Easing for the thumbnail display animation. More about easing on this page.
Miscellaneous
thumbnailOpenInLightox v3.0boolean thumbnailOpenImage v1.0boolean	true	Display media in lightbox. true: lightbox is enabled false: lightbox is disabled. No image will be displayed when a thumbnail is clicked/touched.
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.
thumbnailWaitImageLoaded v1.4boolean	true	When enabled, each thumbnail image is fully downloaded and is then displayed smoothly.
thumbnailCrop thumbnailL1Crop v1.0boolean	true	If needed, thumbnail image will be cropped to avoid black borders (only for grid layout).

RESPONSIVE GALLERY

For a fully responsive gallery, you can define multiple thumbnail sizes, and gutter spaces.

Sizes can be defined 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 one responsive option 'defaultSize XSs1 SMs2 MEs3 LAs4 XLs5'
where s1 to s5 are the sizes for resolutions XS to XL. All values are not mandatory: default value will be used if one is missing.
Responsive options:
- thumbnail size:
thumbnailWidth thumbnailHeight thumbnailL1Width thumbnailL1Height
The value auto is supported.
- thumbnail gutter space:
thumbnailGutterWidth thumbnailGutterHeight thumbnailGutterL1Width thumbnailGutterL1Height

Mosaic layout:
A specific layout can be defined for each screen width:
galleryMosaicXS galleryMosaicSM galleryMosaicME galleryMosaicLA galleryMosaicXL
galleryL1MosaicXS galleryL1MosaicSM galleryL1MosaicME galleryL1MosaicLA galleryL1MosaicXL
Responsive thumbnail sizes are also supported.

Examples:

- Grid layout

  "thumbnailWidth":   "300 XS100 LA400 XL500",
  "thumbnailHeight":  "200 XS80 LA250 XL350"
      

  thumbnailWidth:     '300 XS100 LA400 XL500',
  thumbnailHeight:    '200 XS80 LA250 XL350'
      

- Grid and justified layout depending on the resolution:

  "thumbnailWidth":   "auto XS80 SM120",
  "thumbnailHeight":  "200 XS80 SM120"
      

  thumbnailWidth:     'auto XS80 SM120',
  thumbnailHeight:    '200 XS80 SM120'
      

- Justified and cascading layout depending on the resolution:

  "thumbnailWidth":   "auto XS80 SM120",
  "thumbnailHeight":  "200 XSauto SMauto"
      

  thumbnailWidth:     'auto XS80 SM120',
  thumbnailHeight:    '200 XSauto SMauto'
      

THUMBNAIL LABELS

The label is composed by a title and a description. Set these settings with the thumbnailLabel property.

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

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

property	default	description
position v1.0string	'overImageOnBottom'	Position of the label on the thumbnail. Possible values: 'overImage', 'onBottom' Depreciated values (v3+): 'overImageOnBottom', 'overImageOnTop', 'overImageOnMiddle'
align v1.0string	'center'	Horizontal text alignment. Possible values: 'right', 'center', 'left'
valign v3.0string	'bottom'	Vertical text alignment. Possible values: 'top', 'middle', 'bottom'
display v1.0boolean	true	Displays or hides the label (title and description).
hideIcons v1.0boolean	true	Hides or displays the icons beside the title.
titleMaxLength v1.0integer	0	Title maximum length to display.
titleMultiLine v1.0boolean	false	Title can be multiline (not supported with position:'onBottom').
title v1.0string		Variable to set the image title (undescores are replaced by spaces). Possible values: - '%filename': use the filename without path - '%filenameNoExt': use the filename without path and without extension
titleFontSize v1.0string		Set the title font size. Example: titleFontSize: '2em'
displayDescription v1.0boolean	false	Displays or hides the description.
descriptionMaxLength v1.0integer	0	Description maximum length to display.
descriptionMultiLine v1.0boolean	false	Description can be multiline (not supported with position:'onBottom').
descriptionFontSize v1.0string		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: 'toolsAppear'
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

Some examples:

• Single 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 combined hover effects:
• Apply a grayscale filter and an image rotation: 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)
• Supported 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.

NAVIGATION / FILTERING

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

GALLERY - FIRST ALBUM LEVEL SPECIFIC OPTIONS

Gallery and thumbnails 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).
Property names with L1 are specific to the first level.

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

      <div id="my_nanogallery2" data-nanogallery2 = '{ >
        "thumbnailHeight":    200,          // heigth for all gallery levels
        "thumbnailWidth":     "auto",       // width for all gallery levels
        
        "thumbnailL1Height":  300,          // height for first gallery level -> overwrites the thumbnailHeight value
        "thumbnailL1Width":   300,          // width for first gallery level -> overwrites the thumbnailWidth value
        ...
      </div>
      

      $("#myNanoGallery").nanogallery2({
        ...
        thumbnailHeight:    200,              // heigth for all gallery levels
        thumbnailWidth:     'auto',           // width for all gallery levels
        
        thumbnailL1Height:  300,              // height for first gallery level -> overwrites the thumbnailHeight value
        thumbnailL1Width:   300,              // width for first gallery level -> overwrites the thumbnailWidth value
        ...
      });
      

LIGHTBOX: MEDIA DISPLAY

The lightbox is used to display medias (images and videos) 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 it's own configuration.

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

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

viewerToolbar:    {
        display:    true,
        standard:   'minimizeButton, label',
        minimized:  'minimizeButton, label, fullscreenButton, downloadButton, infoButton'
      },
 viewerTools:    {
        topLeft:    'pageCounter',
        topRight:   'playPauseButton, zoomButton, fullscreenButton, closeButton'
      }   
      

CUSTOM ICONS

All icons used in nanogallery2 can be customized. By default, the icon font included in the nanogallery2's package is used.

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

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

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

// 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

// PAGNIATION/SLIDER:
navigationPaginationNext:     '<i class="nGY2Icon-ngy2_chevron-right"></i>',
navigationPaginationPrevious: '<i class="nGY2Icon-ngy2_chevron-left"></i>',
navigationBtnOverlayNext:     '<i style="margin-right:0;" class="nGY2Icon-ngy2_chevron-right"></i>',
navigationBtnOverlayPrevious: '<i class="nGY2Icon-ngy2_chevron-left"></i>',

// THUMBNAILS:
thumbnailAlbum:               '<i class="nGY2Icon-folder-empty"></i>'        // album icon 
thumbnailImage:               '<i class="nGY2Icon-picture"></i>'             // image icon
thumbnailSelected:            '<i style="color:#bff;" class="nGY2Icon-ok-circled"></i>'          // selected icon
thumbnailUnselected:          '<i style="color:#bff;" class="nGY2Icon-circle-empty"></i>'        // unselected icon
thumbnailFeatured:            '<i style="color:#dd5;" 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
thumbnailShoppingcart:        '<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, set the background and the border color of the thumbnails, set the toolbar content color:

    $("#my_nanogallery2").nanogallery2({
      ...
      galleryTheme: {
        thumbnail : { background: '#F00', borderColor: '#F00' }
      },
      viewerTheme : { barColor: #F00 },
      ...
    });
  

Gallery theme format (with default values):

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

Lightbox theme format (with default values):

{
background:             '#000',
barBackground:          'rgba(4, 4, 4, 0.2)',
barBorder:              '0px solid #111',
barColor:               '#fff',
barDescriptionColor:    '#ccc'
}

UPGRADING FROM nanoGALLERY

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

TIPS AND TRICKS

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

BROWSER SUPPORT

Firefox 6+ - Chrome 16+ - Edge 13+ - IE 11+ - 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 BrowserStack- many Thanks for this great service!