Merge pull request #155 from feimosi/new-api-methods

(feat) Add 'show' and 'hide' methods to the API

README.md

@@ -130,12 +130,48 @@ The following options are available:
 
 ## API
 
-* `run` - initialize baguetteBox.js
-* `showNext` - switch to the next image
-* `showPrevious` - switch to the previous image
-* `destroy` - remove the plugin with any event bindings
+### `run(selector, userOptions)`
 
-`showNext` and `showPrevious` return true on success or false if there are no more images to be loaded.
+Initialize baguetteBox.js
+
+- @param `selector` {string} - valid CSS selector used by `querySelectorAll`
+- @param `userOptions` {object} - custom options (see [#Customization](#customization))
+- @return {array} - an array of gallery objects (reflects elements found by the selector)
+
+### `show(index, gallery)`
+
+Show (if hidden) and move the gallery to a specific index
+
+- @param `index` {number} - the position of the image
+- @param `gallery` {array} - gallery which should be opened, if omitted assumes the currently opened one
+- @return {boolean} - true on success or false if the index is invalid
+
+Usage:
+
+```js
+const gallery = baguetteBox.run('.gallery');
+baguetteBox.show(index, gallery[0]);
+```
+
+### `showNext`
+
+Switch to the next image
+
+- @return {boolean} - true on success or false if there are no more images to be loaded
+
+### `showPrevious`
+
+Switch to the previous image
+
+- @return {boolean} - true on success or false if there are no more images to be loaded
+
+### `hide`
+
+Hide the gallery
+
+### `destroy`
+
+Remove the plugin with any event bindings
 
 ## Responsive images
 

src/baguetteBox.js

@@ -58,6 +58,8 @@
     var currentGallery = [];
     // Current image index inside the slider
     var currentIndex = 0;
+    // Visibility of the overlay
+    var isOverlayVisible = false;
     // Touch event start position (for slide gesture)
     var touch = {};
     // If set to true ignore touch events because animation was already fired
@@ -167,7 +169,7 @@
 
         buildOverlay();
         removeFromCache(selector);
-        bindImageClickListeners(selector, userOptions);
+        return bindImageClickListeners(selector, userOptions);
     }
 
     function bindImageClickListeners(selector, userOptions) {
@@ -218,6 +220,8 @@
             });
             selectorData.galleries.push(gallery);
         });
+
+        return selectorData.galleries;
     }
 
     function clearCachedData() {
@@ -433,6 +437,7 @@
         }
         documentLastFocus = document.activeElement;
         initFocus();
+        isOverlayVisible = true;
     }
 
     function initFocus() {
@@ -485,6 +490,7 @@
                 options.afterHide();
             }
             documentLastFocus && documentLastFocus.focus();
+            isOverlayVisible = false;
         }, 500);
     }
 
@@ -584,46 +590,62 @@
 
     // Return false at the right end of the gallery
     function showNextImage() {
-        var returnValue;
-        // Check if next image exists
-        if (currentIndex <= imagesElements.length - 2) {
-            currentIndex++;
-            updateOffset();
-            preloadNext(currentIndex);
-            returnValue = true;
-        } else if (options.animation) {
-            slider.className = 'bounce-from-right';
-            setTimeout(function() {
-                slider.className = '';
-            }, 400);
-            returnValue = false;
-        }
-        if (options.onChange) {
-            options.onChange(currentIndex, imagesElements.length);
-        }
-        return returnValue;
+        return show(currentIndex + 1);
     }
 
     // Return false at the left end of the gallery
     function showPreviousImage() {
-        var returnValue;
-        // Check if previous image exists
-        if (currentIndex >= 1) {
-            currentIndex--;
-            updateOffset();
-            preloadPrev(currentIndex);
-            returnValue = true;
-        } else if (options.animation) {
-            slider.className = 'bounce-from-left';
-            setTimeout(function() {
-                slider.className = '';
-            }, 400);
-            returnValue = false;
+        return show(currentIndex - 1);
+    }
+
+    /**
+     * Move the gallery to a specific index
+     * @param `index` {number} - the position of the image
+     * @param `gallery` {array} - gallery which should be opened, if omitted assumes the currently opened one
+     * @return {boolean} - true on success or false if the index is invalid
+     */
+    function show(index, gallery) {
+        if (!isOverlayVisible && index >= 0 && index < gallery.length) {
+            prepareOverlay(gallery, options);
+            showOverlay(index);
+            return true;
+        }
+        if (index < 0) {
+            if (options.animation) {
+                bounceAnimation('left');
+            }
+            return false;
         }
+        if (index >= imagesElements.length) {
+            if (options.animation) {
+                bounceAnimation('right');
+            }
+            return false;
+        }
+
+        currentIndex = index;
+        loadImage(currentIndex, function() {
+            preloadNext(currentIndex);
+            preloadPrev(currentIndex);
+        });
+        updateOffset();
+
         if (options.onChange) {
             options.onChange(currentIndex, imagesElements.length);
         }
-        return returnValue;
+
+        return true;
+    }
+
+    /**
+     * Triggers the bounce animation
+     * @param {('left'|'right')} direction - Direction of the movement
+     */
+    function bounceAnimation(direction) {
+        slider.className = 'bounce-from-' + direction;
+        setTimeout(function() {
+            slider.className = '';
+        }, 400);
     }
 
     function updateOffset() {
@@ -732,8 +754,10 @@
 
     return {
         run: run,
+        show: show,
         showNext: showNextImage,
         showPrevious: showPreviousImage,
+        hide: hideOverlay,
         destroy: destroyPlugin
     };
 }));