Gridzy.js 2 – API

Although Gridzy has its own API, most things can be done without it, simply by manipulating the DOM. Gridzy will notice it and adjust the grid. But there is also a very powerful API …

Manipulating the DOM

For all Document Object Model (DOM) manipulations we first need the container element:

// get the container element
var gridzyElement = document.querySelector('.gridzy');

Add Images

It’s important to fully build and fill the new child element before you add it to the container element. Otherwise Gridzy can’t detect the correct dimensions. 

// create a new img element
var newImage = document.createElement('img');

// add src attribute (!! before you add it to the container element !!)
newImage.src = 'https://placeimg.com/640/480/any';

// add it as last element to the container element
gridzyElement.appendChild(newImage);

// or as first element (or anywhere in between)
gridzyElement.insertBefore(newImage, gridzyElement.firstChild);

Remove Images

// remove the first image
gridzyElement.removeChild(gridzyElement.firstElementChild);

Change Options

// change the spaceBetween option to a specific value
gridzyElement.setAttribute('data-gridzy-spaceBetween', '10');

// change the layout option to a specific value
gridzyElement.setAttribute('data-gridzy-layout', 'waterfall');

// reset the spaceBetween option to its default value
gridzyElement.removeAttribute('data-gridzy-spaceBetween');

More about manipulating the DOM you can find at MDN web docs. There is also an Introduction to the DOM available.

Proprietary API

To use the API, we first need the Gridzy instance, which is bind to the Gridzy container element:

// get the Gridzy instance
var gridzyInstance = document.querySelector('.gridzy').gridzy;

Get Option

// get the value of a single option
var currentLayout = gridzyInstance.getOption('layout');

Get All Options

// get all option values as an object
var currentOptions = gridzyInstance.getOptions();

Set Options

// set specific option values
gridzyInstance.setOptions({
  spaceBetween: 10,
  layout: 'waterfall'
});

// or reset options to their default values
gridzyInstance.setOptions({
  spaceBetween: null,
  layout: null
});

Apply Filter

Applying a filter is just setting the option filter that can be any valid CSS selector:

// set the filter to match items with class "animals"
gridzyInstance.setOptions({
  filter: '.animals'
});

// reset the filter to match all items again
gridzyInstance.setOptions({
  filter: '*'
});

// set the filter to match items without class "animals"
gridzyInstance.setOptions({
  filter: ':not(.animals)'
});

// set the filter to match items with class "animals" or "people"
gridzyInstance.setOptions({
  filter: '.animals, .people'
});

// set the filter to match items that have both classes, "animals" and "people"
gridzyInstance.setOptions({
  filter: '.animals.people'
});

Add Callback Functions

Gridzy.js 2 supports some options for callback functions. They can be set only via the proprietary API, but just like other options:

// same as set other options
gridzyInstance.setOptions({
  onOptionsChanged: function() {
    // will be executed each time the options have changed.
  },
  onBeforeOptionsChanged: function() {
    // will be executed, before new options take effect.
  }
});

Description
onBeforeOptionsChangedCallback function that is invoked directly before setting options.
onOptionsChangedCallback function that is invoked directly after setting options.
onBeforeRenderCallback function that is invoked directly before rendering.
onRenderCallback function that is invoked directly after rendering.

API – Global

There are some functions that are independent of Gridzy instances. So we don’t need to get an instance before.

Get Default Option

// get the default value of a single option
var defaultLayout = Gridzy.getDefaultOption('layout');

Get All Default Options

// get all default option values as an object, including the default layout options of the default layout
var defaultOptions = Gridzy.getDefaultOptions();

// or get all default option values, including the default layout options of a specific layout
var defaultOptions = Gridzy.getDefaultOptions('waterfall');

Set Default Options

This doesn’t set the options of all already initialized Gridzy instances, but defines the basis for new instances. However, if an option of an existing instance would be reset via the value null, it would uses the new default value.

// set default option values
Gridzy.setDefaultOptions({
  spaceBetween: 10,
  layout: 'waterfall'
});

You can use this to set options globally, if you call it before DOM is ready. So you wouldn’t need to set options as attributes anymore.

Automatisms

As long as all automatisms of Gridzy.js 2 are active, there is no need for the below methods. But the automatisms can be switched off to use Gridzy in a more traditional way:

// disable automatic initializations
Gridzy.setDefaultOptions({
  autoInitOnDomReady: false,
  autoInitOnDomMutation: false
});

// or switch off all mutation observers
Gridzy.setDefaultOptions({
  autoInitOnDomMutation: false,
  autoSyncChildListMutation: false,
  autoSyncAttributesMutation: false,
  autoSyncChildClassMutation: false
});

Some of these options can’t be set via data-gridzy- attributes or via setOptions(), because of logical reasons:


Default ValueDescription
autoInitOnDomReadytrueDetects elements with class gridzy on page loading and initializes them.

Settable via Gridzy.setDefaultOptions()
autoInitOnDomMutation
MutationObserver		trueDetects new elements with class gridzy as soon as they appear in the DOM and initializes them. (e.g. on using page transitions)

Settable via Gridzy.setDefaultOptions()
autoSyncChildListMutation
MutationObserver		trueDetects whether child elements (images) are added or removed, and updates the grid automatically.

Settable via data-grizy-, new Gridzy(), setOptions(), Gridzy.setDefaultOptions()
useOptionAttributestrueDefines whether the data-gridzy- attributes are generally used or not. If this is false options can be set only via the proprietary API.

Settable via new Gridzy(), setOptions(), Gridzy.setDefaultOptions()
autoSyncAttributesMutation
MutationObserver		trueDetects changes of data-gridzy- attributes, and updates the grid automatically. Also detects if the gridzyAnimated class is added or removed and if style attribute changes occur. If useOptionAttributes is false, it detects only style attribute changes.

Settable via data-grizy-, new Gridzy(), setOptions(), Gridzy.setDefaultOptions()
autoSyncChildClassMutation
MutationObserver		trueDetects changes of class attributes of all child elements (images). Relevant regarding filters.

Settable via data-grizy-, new Gridzy(), setOptions(), Gridzy.setDefaultOptions()

Initialize Manually

// initialize a new Gridzy instance
var gridzyInstance = new Gridzy(document.querySelector('.gridzy'), {
  spaceBetween: 10,
  layout: 'waterfall'
});

Destroy the Instance

Roughly said, the opposite of initializing Gridzy.

gridzyInstance.destroy();
gridzyInstance = null;

Sync Child List Manually

// after child elements (images) are added to or removed from the DOM.
gridzyInstance.syncChildList();

Sync a Single Child Manually

Usually not needed, except in very rare cases.

// after child elements (images) are added to the DOM and only one of them should be synced to Gridzy.
gridzyInstance.syncChild(childElement);

Sync Attributes Manually

Note that useOptionAttributes option must be true for this.

// after data-gridzy- attributes have changed
gridzyInstance.syncAttributes();

Force Rendering

Usually not needed, even if all automatisms are turned off

gridzyInstance.render();

You reached the end of the documentation! ?

Gridzy.js 2 is so powerful, I can’t portray in the documentation all the things that are possible. But I’m going to publish tips and tricks from time to time. Stay in touch via Twitter or subscribe to my mailing list, where you would receive 30 more Gridzy.js skins as a welcome gift 🎁. If you tell me your name too, that would pleases me. I’m Helmut ✌
I don’t have time to send junk, so be relaxed 😏

made by @eHtmlu