Usage

Usage notices

Before starting using Gridifier, you must include gridifier.js file, as shown at the install page. We must notice a few global conventions, that will be used across all documentation:

• Most of the functions are returning self-reference of the Gridifier object instance.
• So, you can chain function calls like this: 'grid.functionA().functionB() ... .functionN()'.
• DomCollection argument in all functions calls can be raw DOM object or array/jQuery collection of DOM objects.
• DomCollection can contain any HTML DOM objects, which calculated sizes can be readen from browser(Display = block || inline-block || table).

TouchClickEvent notice.
In some examples we will use TouchClickEvent to handle fast clicks both on desktops and touch devices. Basically, it's preventing emulated click events from firing on touch devices and allows to start scrolling from touched elements. In examples you can view it as regular click event.

Maybe later we will write about our implementation on some outer resource and place link here, because we think it's implementation isn't related directly to Gridifier docs.

Initialization

Syntax: new Gridifier(grid, settings)

To create new Grid you must pass grid DOM object and optionally settings object:

// If grid parameter is array, first array item will be used
var grid = document.body.querySelectorAll(".grid-selector");
var settings = {firstSettingName: "firstSettingValue", nthSettingName: "nthSettingValue"};

var asyncGrid = new Gridifier(grid, settings);
        

What changes will be applied to grid on initialization step?

• If grid has position relative or absolute set, no changes will be applied.
• Otherwise, grid position will be changed to relative.
• Gridifier will not change grid overflow settings.

Notice.
If you will use paddings per grid, percentage margins and paddings on grid items won't work. (Our unit tests shows that chrome calculates them according to raw grid width/height, Firefox uses width/height + padding)

So, because of this and few more bugs with resolving item sizes, we decided to ignore paddings on grids. If you need to add additional spacing around grid, use margins + calcs or wrapper with border-box box sizing + paddings. (for top-bottom you also can use :before/:after on grid parent)

Collecting items

We are forcing to pass to the Gridifier the way to determine grid items. It will be used in process of collecting and filtering items.

Notice.
Of course, we could use only items that were passed into insert functions. But with this method, we can't use Gridifier somehow like this: 'After each 100ms check if grid has new items, that should be processed by Gridifier, and if such items exists, insert them through one of insert functions.'

So, you have to pass a setting, which determines the way of collecting grid items. For this purpose, you can choose 1 from 3 settings:

class: "classname"

data: "data-attr-name"

query: "> .someQuery"

If none of 3 settings will be passed, Gridifier will assume that grid items are marked with 'grid-item' class:

default = class: "grid-item"

Examples of setting collection type:

var demoGrid = document.getElementById("#demo-grid");

var grid = new Gridifier(demoGrid, {class: "grid-item-class"}); // items 1 and 2
var grid = new Gridifier(demoGrid, {data: "data-griditem"}); // items 3 and 4
// query param supports '>' selector(only at top level - "div > img" will not work)
var grid = new Gridifier(demoGrid, {query: "> a"}); // items 5 and 6
// By default, items with 'grid-item' class will be collected
var grid = new Gridifier(demoGrid); // items 7 and 8
        

<div id="demo-grid">
    <div class="grid-item-class">1</div>
    <div class="grid-item-class">2</div>

    <div data-griditem="first-gridifier-item">3</div>
    <div data-griditem="nth-gridifier-item">4</div>

    <a href="#">5</a>
    <a href="#">6</a>

    <div class="grid-item">7</div>
    <div class="grid-item">8</div>
</div>
        

Collector helpers

Gridifier provides a few helpers to work with grid items:

var demoGrid = document.getElementById("#demo-grid");
var grid = new Gridifier(demoGrid, {class: "grid-item"});

grid.collectNew();
// Returns ['<div class="grid-item">1</div>', '<div class="grid-item">2</div>']

grid.append(demoGrid.querySelectorAll(".grid-item")[0]);
grid.collectNew();
// Returns ['<div class="grid-item">2</div>']

grid.append(demoGrid.querySelectorAll(".grid-item")[1]);
grid.collectNew();
// Returns []
        

<div id="demo-grid">
    <div class="grid-item">1</div>
    <div class="grid-item">2</div>
</div>
        

This function can be especially useful, if you want to implement some kind of 'watch' method, as shown in next example:

var demoGrid = document.getElementById("#demo-grid");
var grid = new Gridifier(demoGrid, {class: "grid-item"});

var simulateDelayedAppends = function() {
    for(var i = 1; i <= 6; i++) {
        var gridItem = document.createElement("div");

        gridItem.setAttribute("class", "grid-item");
        gridItem.innerHTML = i;

        (function(gridItem) {
            setTimeout(function() { demoGrid.appendChild(gridItem); }, i * 200);
        })(gridItem);
    }
}

var watchDemoGrid = function() {
    setTimeout(function() {
        // Alternatively, you can use a shorthand - grid.appendNew()
        grid.append(grid.collectNew());
        watchDemoGrid();
    }, 100);
}

simulateDelayedAppends();
watchDemoGrid();
         

<div id="demo-grid">
</div>
        

A few additional helpers:

Notice.
All collector helpers returns items sorted by they DOM order.

Notice.
Items, that were disconnected through 'disconnect' function, will not appear in collector helper functions. That happens because in most cases, if you are disconnecting some item manually, you probably will delete it from DOM after that. Otherwise, you can reinsert item manually when it is required.

Notice.
Filtered out items will be returned by collector helpers together with visible items. That is valid, because filtered out items will be dropped on any of insert methods filtering step. Just don't use it to show new items count.

Iterators

Gridifier ships with a set of helper functions, that allows to get items in the order, in which they were inserted in context of current positioning/sorting mode:

Notice.
All iterators are returning null, if grid is empty or next/prev item don't exists.

var gridControls = document.getElementById("#grid-controls");
var demoGrid = document.getElementById("#demo-grid");

var grid = new Gridifier(demoGrid);

TouchClickEvent.listen(gridControls.querySelectorAll(".first")[0], function() {
    var firstGridItem = grid.first();
    // Format result here and insert into grid results
});

// Similar code for last and all

TouchClickEvent.listen(demoGrid, ".grid-item > .top", function(event) {
    // with jQuery you can use $(event.target).closest(".gridItem");
    var gridItem = getClosest(event.target, ".grid-item");
    var nextGridItem = grid.next(gridItem);
    // Format result here and insert into grid results
});

// Similar code for prev
        

<section id="grid-controls">
    <div class="control first">first</div>
    <div class="control last">last</div>
    <div class="control all">all</div>
</section>

<div id="demo-grid">
    <div class="grid-item">
        <div class="top">next</div><div class="bottom">prev</div>
        <span class="item-number">1</span>
    </div>
    // ... 5 More items
</div>