search

cavis / gridheist

A jQuery plugin to hijack an image gallery, making it great.
MIT License
1 stars 0 forks source link

readme

GridHeist

A jQuery plugin to hijack an image gallery, making it great.

Check out the dynamic test page. Or the image preloading test page.

Alt text

Requirements

jQuery

Requires jQuery version >= 1.7.0

Compiling

If you so choose to compile/test/develop yourself, you'll need to install the grunt-cli using the Node Package Manager...

npm install -g grunt-cli

Then install the dependencies from package.json (if you haven't already)...

npm install <module-name-here>

Then you can run grunt tasks!

grunt build
grunt watch
grunt dev

Getting Started

Include build/gridheist.js and build/gridheist.css, or some version of them. (See example/index.html for an example).

In your <head> section (next to other CSS):

<link href="https://github.com/cavis/gridheist/blob/master/path/to/gridheist.css" rel="stylesheet">

At the bottom of the <body> section (next to other JS)

<script src="https://github.com/cavis/gridheist/raw/master/path/to/jquery-1.10.2.min.js"></script>
<script src="https://github.com/cavis/gridheist/raw/master/path/to/gridheist.js"></script>

Usage

GridHeist is a jQuery plugin, so just call the function on a selector to create a gallery.

$(document).ready(function() {
    var options = {};
    $('#gallery').gridHeist(options);
});

Galleries should have semi-standardized markup. You should apply whatever layout-css you want to the outer container (#gallery in this example). The following is pretty standard:

<div id="gallery" style="margin:0 100px; width:auto;">
  <a href="https://github.com/cavis/gridheist/blob/master/img/something1_big.png">
    <img src="https://github.com/cavis/gridheist/raw/master/img/something1_thumb.png"/>
  </a>
  <a href="https://github.com/cavis/gridheist/blob/master/img/something2_big.png">
    <img src="https://github.com/cavis/gridheist/raw/master/img/something2_thumb.png"/>
  </a>
</div>

Be aware that, for performance reasons, gridheist will wrap all the thumbnails a in a container <div class="gridheist-wrap"></div>. So make sure your styling is scoped correctly!

If you want things to load snappier, I'd recommend pre-populating the data-width and data-height of the thumbnail images, so we don't have to wait for the <img> to load before we can get the native dimensions. Note that this is the height/width of the THUMBNAIL, not of the full-sized image.

<div id="gallery">
  <a href="https://github.com/cavis/gridheist/blob/master/img/something1_big.png">
    <img src="https://github.com/cavis/gridheist/raw/master/img/something1_thumb.png" data-width="300" data-height="200"/>
  </a>
</div>

Options

These options can be passed in when you create the gridheist. Numbers are probably something in px, unless otherwise noted.

thumbSelector - A jQuery selector to get the thumbnail objects within the element - (default: > *)

thumbBorder - Border width between thumbnails - (default: 10)

thumbMinHeight - Minimum height of a row of thumbnails - (default: 200)

thumbMaxHeight - Maximum height of a row of thumbnails - (default: null)

expander - Enable the image expander - (default: true)

expandRatio - The percentage of viewport height for the expander-row - (default: 0.60)

expandMaxHeight - Maximum height of the expander-row - (default: 500)

expandMinHeight - Minimum height of the expander-row - (default: 100)

expandSideRender - Function to return markup for the expander sidebar; passed the jQuery $thumb object - (default: false)

expandSideWidth - Width of the expander sidebar (if expandSideRender is passed) - (default: 200)

scroller - Selector for the element within which the gallery will be scrolling - (default: window)

preload - Agressively preload full-size images when rows are expanded - (default: false)

preloadBefore - The number of images before the expanded row to preload - (default: 2)

preloadAfter - The number of images after the expanded row to preload - (default: 6)

Methods

update() - Force a re-layout of the gallery

update(options) - Alter any config options, and force a re-layout of the gallery. Options must be an object containing only the option keys you want to change.

Changes

Times they are a-changin'. Check out the changelog.

Issues and Contributing

Report any bugs or feature-requests via the issue tracker. Or send me a fax. And if you'd like to contribute, send me a note! Thanks.

License

GridHeist is free software, and may be redistributed under the MIT-LICENSE.

Thanks for listening!