Basic Usage
1. Upload Gridzy Files
Upload the Gridzy files to your server and add them to your website (usually in the head section).
<!-- Gridzy css file -->
<link rel="stylesheet" href="gridzy/gridzy-1.3.css" />
<!-- Gridzy js file -->
<script src="gridzy/gridzy-1.3.min.js"></script>2. Add HTML Code
Add the HTML code to the body section. Every child element will be treated as its own sizing box. You can use any tag names for your code. The img-tag is not exchangeable and the main structure is important for predefined skins only. Be careful with elements that are already styled (such as the p-tag). You might have to adjust them for your specific use. Learn more about how to style Gridzy.
<!--
Any tag name can be used for the containing element.
The CSS class "gridzy" is used for initializing Gridzy.
The CSS class "gridzyClassic" means that the default skin is used.
The CSS class "gridzyLightProgressIndicator" effects a white progress indicator instead of the default black one.
The CSS class "gridzyAnimated" results in a transition when the sizes and positions of boxes change. (only modern browsers)
-->
<div class="gridzy gridzyClassic gridzyLightProgressIndicator gridzyAnimated">
<div>
<img src="images/450x300.png" alt="450x300 dummy image" />
<span>A nice caption for a 450x300 image</span>
</div>
<div>
<img src="images/200x300.png" alt="200x300 dummy image" />
<span>A nice caption for a 200x300 image</span>
</div>
<div>
<img src="images/1150x400.png" alt="1150x400 dummy image" />
<span>A nice caption for a 1150x400 image</span>
</div>
<div>
<img src="images/533x300.png" alt="533x300 dummy image" />
<span>A nice caption for a 533x300 image</span>
</div>
<!-- Any tag name can be used for the item. -->
<a href="images/600x400.png">
<img src="images/600x400.png" alt="600x400 dummy image" />
<span>A nice caption for a 600x400 image</span>
</a>
<!--
If an image cannot be loaded, the container item will be hidden automatically.
Use Gridzy option hideBoxOnMissingImage to disable this feature.
-->
<div>
<img src="images/missingImage.png" alt="missing dummy image" />
<span>A nice caption for a missing image</span>
</div>
<!-- You can also just use an image tag, without any caption or something else. -->
<img src="images/300x533.png" alt="300x533 dummy image" />
<div>
<img src="images/1150x400.png" alt="1150x400 dummy image" />
<!--
Any tag name can be used for the caption element.
Be careful because of predefined styles.
-->
<figcaption>A nice caption for a 1150x400 image</figcaption>
</div>
<div>
<img src="images/400x400.png" alt="400x400 dummy image" />
<div>
<!-- any structure can be used inside the caption element -->
A nice caption for a <a href="images/400x400.png">400x400 image</a>
</div>
</div>
</div>3. Initialize Gridzy
Initialize Gridzy using one of the following code snippets. You can paste your choice at the end of the body tag for example (or at any other place where DOM is ready).
Initialization using jQuery
If your website uses jQuery you can initialize Gridzy with the following code snippet. Otherwise use one of the other code snippets below.
<!-- using jQuery -->
<script>
$('.gridzy').gridzy({
// options go here
// as an example, space between elements is set to 5 pixel.
spaceBetweenElements: 5
});
</script>Initialization without any other javascript library
You can initialize multiple instances by using the following code
<!-- standalone - multiple instances -->
<script>
(function(){
var elements = document.querySelectorAll('.gridzy'),
a = 0,
options = {
// options go here
// as an example, space between elements is set to 5 pixel.
spaceBetweenElements: 5
};
for (; a < elements.length; a++) {
new Gridzy(elements[a], options);
}
})();
</script>Or you can initialize a single instance by providing an element id. You have to set “gridzy” as the id of your containing element for the following example.
<!-- standalone - single instance -->
<script>
new Gridzy(document.getElementById('gridzy'), {
// options go here
// as an example, space between elements is set to 5 pixel.
spaceBetweenElements: 5
});
</script>Optimize Loading
Prevent initial Animation
If you are using the css class “gridzyAnimated”, the elements will be animated always if they change there positions (if you resize the window for example). During the loading process the elements also get there new positions. To prevent this first animation, just set the option “preventInitialAnimation” on true.
<!-- using jQuery -->
<script>
$('.gridzy').gridzy({
preventInitialAnimation: true
});
</script><!-- standalone - single instance -->
<script>
new Gridzy(document.getElementById('gridzy'), {
preventInitialAnimation: true
});
</script>Prevent jumping Images
Gridzy absolutely needs the aspect ratio of all images to calculate the grid. These fact results in jumping elements if some pictures are ready and others are not. The more images there are, the more annoying can be this effect.
To prevent such a behaviour set width and height attributes for all img-elements with the natural image dimensions:
...
<div>
<img src="images/200x300.png" alt="200x300 dummy image" width="200" height="300" />
<span>A nice caption for a 200x300 image</span>
</div>
<div>
<img src="images/1150x400.png" alt="1150x400 dummy image" width="1150" height="400" />
<span>A nice caption for a 1150x400 image</span>
</div>
<div>
<img src="images/533x300.png" alt="533x300 dummy image" width="533" height="300" />
<span>A nice caption for a 533x300 image</span>
</div>
...Lazy Loading
To load only images which are in the visible viewport, just follow these steps:
- Set the option “preventInitialAnimation” on true like already described above. (yes, this is required)
- Insert width and height Attributes like also described above.
- Replace all src Attributes like following …
Replace the “src” attributes of all img-tags with “data-gridzylazysrc” like you can see here:
...
<div>
<img data-gridzylazysrc="images/200x300.png" alt="200x300 dummy image" width="200" height="300" />
<span>A nice caption for a 200x300 image</span>
</div>
<div>
<img data-gridzylazysrc="images/1150x400.png" alt="1150x400 dummy image" width="1150" height="400" />
<span>A nice caption for a 1150x400 image</span>
</div>
<div>
<img data-gridzylazysrc="images/533x300.png" alt="533x300 dummy image" width="533" height="300" />
<span>A nice caption for a 533x300 image</span>
</div>
...After these three steps the images will load a little bit before they appear in the viewport.
Options
The following properties are supported on the options object that you can pass to Gridzy.
Smart Options
You can specify a custom javascript function to dynamically calculate the values of the desiredElementHeight and spaceBetweenElements properties. Gridzy will then use the value returned by the function when it renders the grid. For example, the following function could calculate the desired height based on the available width:
function computeDesiredElementHeight(){
var resultValue,
viewportWidth = document.documentElement.clientWidth;
if (viewportWidth > 1000) {
resultValue = 200;
} else if (viewportWidth > 500) {
resultValue = 150;
} else {
resultValue = 100;
}
return resultValue;
};You can use the function instead of a constant value in the options object that you pass to Gridzy:
// using jQuery
$('#gridzy').gridzy({
desiredElementHeight: computeDesiredElementHeight
});// standalone
new Gridzy(document.getElementById('gridzy'), {
desiredElementHeight: computeDesiredElementHeight
});API
First you need to get the instance of Gridzy.
// using jQuery
// initialize Gridzy
$('.gridzy').gridzy();
// get the Gridzy instance of the first element in the jQuery collection
var gridzyInstance = $('.gridzy').data('gridzy');// standalone
// initialize Gridzy and get the Gridzy instance
var gridzyInstance = new Gridzy(document.getElementById('gridzy'));You can use the API thereafter.
Public Methods
gridzyInstance.getOption('spaceBetweenElements'); // returns an option value
gridzyInstance.setOptions({ // updates one or more option values (the changes are rendered immediately)
spaceBetweenElements: 5
});
gridzyInstance.render(); // forces rerendering (usually not needed)
gridzyInstance.append(document.createElement('div')); // appends an additional item (the changes are rendered immediately)
// you can also pass an array of DOM nodes ..
gridzyInstance.append(document.getElementById('newItems').children);
// or a jQuery collection
gridzyInstance.append($('#newItems > *'));Style Gridzy
You can change predefined styles or create your own. You just need to know a few things beforehand.
Study the HTML Structure
During initialization, Gridzy changes the structure of the HTML document. The following fragment
<div class="gridzy gridzyClassic">
<section>
<img src="images/img-1.jpg" alt="" />
<span>caption 1</span>
</section>
<section>
<img src="images/img-2.jpg" alt="" />
<span>caption 2</span>
</section>
<section>
<img src="images/img-3.jpg" alt="" />
<span>caption 3</span>
</section>
</div>will change to
<div class="gridzy gridzyClassic">
<div class="gridzyContainer">
<div class="gridzyItem">
<section class="gridzyItemContent">
<img src="images/img-1.jpg" alt="" />
<span>caption 1</span>
</section>
</div>
<div class="gridzyItem">
<section class="gridzyItemContent">
<img src="images/img-2.jpg" alt="" />
<span>caption 2</span>
</section>
</div>
<div class="gridzyItem">
<section class="gridzyItemContent">
<img src="images/img-3.jpg" alt="" />
<span>caption 3</span>
</section>
</div>
</div>
</div>- There is a new div element with the class “gridzyContainer” which is inside the root element and contains all the content.
- Each item is wrapped in a new div element with the class “gridzyItem”.
- Each of the original item elements has an additional class “gridzyItemContent”.
An item’s structure is slightly different during the loading process.
<div class="gridzy gridzyClassic">
<div class="gridzyContainer">
<!-- additional class "gridzyItemLoading" -->
<div class="gridzyItem gridzyItemLoading">
<section class="gridzyItemContent">
<img src="images/img-1.jpg" alt="" />
<span>caption 1</span>
</section>
<!-- additional element with class "gridzyItemProgressIndicator" -->
<div class="gridzyItemProgressIndicator"></div>
</div>
<div class="gridzyItem">
<section class="gridzyItemContent">
<img src="images/img-2.jpg" alt="" />
<span>caption 2</span>
</section>
</div>
<div class="gridzyItem">
<section class="gridzyItemContent">
<img src="images/img-3.jpg" alt="" />
<span>caption 3</span>
</section>
</div>
</div>
</div>- The item has an additional class “gridzyItemLoading”.
- A new div element with the class “gridzyItemProgressIndicator” will be inserted behind the origin item element.
Your style definitions should match these modified HTML structure. Otherwise the definitions might have undesired effects.
See a Few Styling Examples
/* sets round corners for all boxes */
.gridzyItem {
border-radius: 5px;
}
/* sets round corners for all boxes with a custom skin named "gridzyCustomSkin" */
.gridzyCustomSkin .gridzyItem {
border-radius: 5px;
}
/* hides the box content while loading */
.gridzyItemContent {
visibility: visible;
}
.gridzyItemLoading .gridzyItemContent {
visibility: hidden;
}
/* sets a shadow on the caption box if it's a span element */
.gridzyItemContent > span {
box-shadow: 0 0 5px 0 #000;
}
/* displays a box with the text "loading ..." instead of the progress indicator icon */
.gridzyItemProgressIndicator {
display: none;
}
.gridzyItemLoading:after {
content: "loading ...";
position: absolute;
left: 0;
bottom: 0;
color: #fff;
background: #000;
padding: 5px;
border-radius: 0 5px 0 0;
}Dare a look into Gridzy CSS File
Just open the file in your text editor. You will find a well-structured style sheet. Feel free to change, extend or reduce the definitions. To avoid the additional server request, you can paste the needed styles into your main css file of your website and omit the inclusion of Gridzy css file.
Mind Important Things
If you want to style the item contents, keep the following two things in mind:
- The item contents should be fully responsive. Consider that the element size will definitely change. Use percentage values instead of pixel values. And take a look at Gridzy option “autoFontSize” which binds the font-size onto the item box size.
- Every item should have a well-defined aspect ratio. The item’s aspect ratio will never change and is needed to calculate the grid. So if an item doesn’t automatically have a well-defined aspect ratio, predefine it manually (e.g. via css).
In some cases it could be easier to style the item contents before integrating Gridzy into your website.