JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Chocolat : Responsive jQuery Lightbox Plugin
    Filed under  › 

    • 🔾47%Overall
    • 1,361
    • 14.7 days
    • 🕩160
    • 👥8

    Chocolat Build Status


    Chocolat is a responsive lightbox
    What you are looking for is in the /dist/ folder.
    Demo page is here

    Image of Chocolat

    Installation

    You can install chocolat as a node module
    (css from node_modules has to be linked in your html file anyway)

    yarn add chocolat
    

    or

    npm install chocolat
    

    If you want to use chocolat as a module you'll have to import it like this :

    import $ from 'jquery'
    import Chocolat from 'chocolat'
    
    $.fn.Chocolat = Chocolat
    

    Or the old school way by linking dist/js/jquery.chocolat.js and dist/css/chocolat.css to your html file

    Markup


    <div id="example1" data-chocolat-title="Set title">
        <a class="chocolat-image" href="img/a.jpg" title="image caption a">
            A <!-- you can display a thumbnail here : <img src="thumb/a.jpg" /> -->
        </a>
        <a class="chocolat-image" href="img/b.jpg" title="image caption b">
            B <!-- you can display a thumbnail here : <img src="thumb/b.jpg" /> -->
        </a>
    </div>
    
    $(document).ready(function(){
        $('#example1').Chocolat();
    });
    

    Documentation


    Parameters

    Name Default Description
    container window Sets whether viewer will open and fill the whole page (default), or whether it should open in a particular block of the page. For example #container2, in this case the height and width of the block must be defined.values can be : window, selector, jQuery element, or a node
    imageSelector '.chocolat-image' Selector to find images in the parent element (on which chocolat is called)
    linkImages true Sets whether we can switch from one image to another, within the same call, without closing the viewer (true) , or if the images remain independent (false).
    Warning: if LinkImage: is false then displayAsALink must be worth false too.
    Otherwise we can only view the first image in the set.
    setTitle '' Title of the set. Can also be defined from the html, with the data-chocolat-title attribute
    className '' Add a custom css class to the parent of the lightbox
    imageSize 'default' Can be 'default', 'contain', 'native', or 'cover'.
    default : if the image is bigger than the window it's resized to fit, else if the image is smaller than the window it's not streched, only displayed at native dimensions.
    'contain' : if the image is bigger than the window it's resized to fit, else if the image is smaller than the window it's streched, to fit the window.
    'cover' : the image cover the window, no white space are displayed. More informations & exemple about contain/cover here.
    'native' : the image is never streched nor shrinked, always displayed at native dimensions
    fullScreen false Allow fullscreen browsing (hides the browser window)
    loop false Last image + 1 leads to first image & first image - 1 leads to last image.
    duration 300 Animations duration
    firstImage 0 Index of the image that you want to start the series.
    lastImage 0 Index of the image that you want to end the series.
    separator2 '/' Text between the number of the image and the number of images in the set, does not matter.
    images [] Array of object representing the set images [{src:'img1.jpg'}, {src:'img1.jpg'}, ...]
    You can also specify image title [{src:'img1.jpg', title: 'title'}, ..]
    enableZoom true Disable or enable the zooming feature
    setIndex 0 Set index. yes.
    afterInitialize null Function (hook) called just after chocolat gets initialized
    afterMarkup null Function (hook) called just after markup is created.
    You can use it to alter the default markup: to move the caption at the top of the image for example.
    $('#example').Chocolat({
    afterMarkup: function () {
    this.elems.description.appendTo(this.elems.top)
    }
    });
    afterImageLoad null Function (hook) called just after the image is loaded.
    zoomedPaddingX 0 Function returning the horizontal padding to add around the image when it's zoomed.
    It takes 2 arguments canvasWidth and imgWidth
    $('#example').Chocolat({
    zoomedPaddingX: function (canvasWidth, imgWidth) {
    return canvasWidth / 2
    }
    });
    zoomedPaddingY 0 Function returning the vertical padding to add around the image when it's zoomed.
    It takes 2 arguments canvasHeight and imgHeight
    $('#example').Chocolat({
    zoomedPaddingY: function (canvasHeight, imgHeight) {
    return canvasHeight / 2
    }
    });

    API

    Syntax

    Call chocolat like this :

    $(document).ready(function(){
        var instance = $('#example1').Chocolat().data('chocolat');
    });
    

    Then API calls can be made like this (open for exemple):

    instance.api().open();
    
    Methods

    open : param (optionnal) : i Open the lightbox on the image whose index is i. By default on the first image (i=0). Returns a $.Deferred object.

    close : Close the lightbox. Returns a $.Deferred object.

    prev : Change image backward. Returns a $.Deferred object.

    next : Change image forward. Returns a $.Deferred object.

    goto : param : i (Alias of open) go to image whose index is i on an already opened ligthbox. Returns a $.Deferred object.

    place : Center the image in its parent. Returns a $.Deferred object.

    destroy : Destroy the current instance. Remove elements, unbind events, clear data.

    set : params : property, value Classic setter

    get : param : property Classic getter

    getElem : param : name Returns a jQuery object composing the lightbox. Ex: for the next arrow : instance.api().getElem('right')

    current : Returns the index of the current image.

    CSS Classes

    .chocolat-open : Set to the container when the lightbox is open.

    .chocolat-in-container : Set to the container when chocolat is open in a block (container != window)

    .chocolat-cover : Set to the container when chocolat imageSize is set to 'cover'

    .chocolat-zoomable : Set to the container when chocolat is zoomable

    .chocolat-zoomed : Set to the container when chocolat is zoomed

    License


    Open source license

    If you are creating an open source application under a license compatible with the GNU GPL license v3, you may use this project under the terms of the GPLv3.

    Contributing


    Feel free to contribute by forking then making a pull request.
    Edit files in the /src/ folder, run gulp to copy/minify into the /dist/ folder and to watch for changes.
    Before creating a pull request please run the test suite : yarn test or npm run test
    And yarn prettier or npm run prettier to correct code style errors.

    Testing

    To test, run gulp test, open the file test/index.html to write new tests
    The main test file is : test/src/test.chocolat.js
    To run the tests in command line use : yarn test or npm run test
    To run prettier use : yarn prettier or npm run prettier

    Angular (ng-chocolat)

    An angular directive of Chocolat.js exists thanks to @beuted: https://github.com/beuted/ng-chocolat

    Show All