Settings

Settings object

Gridifier constructor accepts settings object as second parameter, which consist of key-values setting pairs. Most of values represents simple strings or numbers(Core settings), however some values can represent more complex data structure, like function or object with function names/functions pairs.(Api settings)

var asyncGrid = new Gridifier(grid, {
    // Wide used core settings
    "class": "grid-item", // default - class: "grid-item"
    data: "data-myitem", // default - class: "grid-item"
    query: "> a", // default - class: "grid-item"

    grid: "vertical|horizontal", // default = "vertical"

    prepend: "mirrored|default|reversed", // default = "mirrored"
    append: "default|reversed", // default = "default"

    intersections: true|false, // default = true
    align: "top|bottom|left|right|center", // default = "top(Vertical grid)|left(Horizontal grid)"

    sortDispersion: true|false, // default = false
    loadImages: true|false, // default = false

    toggleTime: 800, // default = 500
    coordsChangeTime: 500, // default = 300

    toggleTiming: "cubic-bezier(0.550, 0.055, 0.675, 0.190)", // default = "ease"
    coordsChangeTiming: "cubic-bezier(0.550, 0.055, 0.675, 0.190)", // default = "ease"

    rotatePerspective: "500px", // default = "200px"
    rotateBackface: true|false, // default = true
    rotateAngles: [-180, -360, 180, 0], // default = [0, -180, 180, 0]

    gridResize: "fit|expand|disabled", // default = "fit"
    gridResizeDelay: 0, // default = 100

    dragifier: true|false|".dragHandler", // default = false
    dragifierMode: "i|d", // default = "i"

    widthPtAs: 0.1, // default = 0
    heightPtAs: 0.1, // default = 0
    widthPxAs: 1, // default = 0
    heightPxAs: 1, // default = 0

    repackSize: 20, // default = gridItems.length

    // Less used core settings
    insertRange: 10000, // default = 3000
    vpResizeDelay: 100, // default = null

    queueSize: 100, // default = 12
    queueDelay: 0, // default = 25
    disableQueueOnDrags: true|false // default = true(dm=i), false(dm=d)
});
        

Let's describe the purpose of each Gridifier core setting and it's available values:

Available values:

• "vertical" - Creates grid in fixed width container.
• "horizontal" - Creates grid in fixed height container.

Available values with grid = "vertical":

• "mirrored" - Insert items in the beginning(top) of the grid accordingly to selected append mode with full relayout of all other items.
• "default" - Insert items in the beginning(top) of the grid from left to right side with shifting down all other items.
• "reversed" - Insert items in the beginning(top) of the grid from right to left side with shifting down all other items.

Available values with grid = "horizontal":

• "mirrored" - Insert items in the beginning(left) of the grid accordingly to selected append mode with full relayout of all other items.
• "default" - Insert items in the beginning(left) of the grid from bottom to top side with shifting right all other items.
• "reversed" - Insert items in the beginning(left) of the grid from top to bottom side with shifting right all other items.

Available values with grid = "vertical":

• "default" - Insert items in the end(bottom) of the grid from left to right side.
• "reversed" - Insert items in the end(bottom) of the grid from right to left side.

Available values with grid = "horizontal":

• "default" - Insert items in the end(right) of the grid from top to bottom side.
• "reversed" - Insert items in the end(right) of the grid from bottom to top side.

Available values with grid = "vertical":

• true - Several items can intersect any other item horizontally.
• false - Only one item can intersect any other item horizontally.

Available values with grid = "horizontal":

• true - Several items can intersect any other item vertically.
• false - Only one item can intersect any other item vertically.

Available values with grid = "vertical":

• "top" - All items in 'row' are aligned at top.
• "center" - All items in 'row' are vertically aligned at the center of the most tall item.
• "bottom" - All items in 'row' are vertically aligned at the bottom of the most tall item.

Available values with grid = "horizontal":

• "left" - All items in 'col' are aligned at left.
• "center" - All items in 'col' are horizontally aligned at the center of the most wide item.
• "right" - All items in 'col' are horizontally aligned at the right of the most wide item.

Notice.
You can pass only 'align' setting to Gridifier.(This will automatically set 'intersections' option to false value)

Normal order rules on vertical grid appends:

• New item cannot be inserted above any of already inserted items.
• So, new item Y2 should be >= Y1 of all already inserted items.

Normal order rules on vertical grid prepends:

• New item cannot be inserted below any of already inserted items.
• So, new item Y1 should be <= Y2 of all already inserted items.

Normal order rules on horizontal grid appends:

• New item cannot be inserted before any of already inserted items.
• So, new item X2 should be >= X1 of all already inserted items.

Normal order rules on horizontal grid prepends:

• New item cannot be inserted behind any of already inserted items.
• So, new item X1 should be <= X2 of all already inserted items.

Notice.
Mirrored prepends internally are using appends, so append order rules will be applied.

Available values:

• false - All items are inserted in normal order.
• true - New item can be inserted anywhere in empty grid space.

Angles array values:

• [0] - Front frame init angle, default = 0.
• [1] - Back frame init angle, default = -180.
• [2] - Front frame target angle, default = 180.
• [3] - Back frame target angle, default = 0.

Available values with grid = "vertical":

• "fit" - Grid height is always set up according to max grid item Y2.
• "expand" - Grid height updates only to higher values.
• "disabled" - Grid height updates are disabled.

Available values with grid = "horizontal":

• "fit" - Grid width is always set up according to max grid item X2.
• "expand" - Grid width updates only to higher values.
• "disabled" - Grid width updates are disabled.

Notice.
Gridifier is applying grid sizes changes after timeout, which is being fired after specified ms count. If multiple items are inserted/disconnected, this timeout will be rescheduled.

This is required because it is too expensive to update grid sizes after each insert/disconnect on grids with large items count. (Browser reflow operations will slow down performance on touch devices)

On small grids you can set this value to 20 or 0, if delay between inserts and grid sizes changes is noticeable.

Available values:

• false - Dragifier is disabled.
• true - Dragifier is enabled. Item selector is used as drag handler.
• "selector" - Dragifier is enabled. Selector relative to grid item selector is used as drag handler.

Available values:

• "i" - dragged and intersected item are exchanging their positions.
• "d" - dragged item can be placed in any grid 'cell'.

Notice.
Per most grids 3000px is enough insertion range per Gridifier. This setting could be used with enabled sort dispersion, when small items are inserted after large count of big items.

Notice.
With this setting you can control items count in one batch, processed by reposition queue. This can be especially useful with disabled intersections, when custom aligns(center, right, bottom) are used.

Because of dynamical aligns used with NIS mode, you can encounter situation, when some items are 'jumping' on grid repositions. This happens when not biggest item is reinserted first in row/col and next row/col items are reinserted in next batch.

So, item gets to the render queue before other row/col items are reinserted in next batch. This is the moment when jump occurs. If you will see this behaviour, you can set this setting to bigger value.

Api settings

var asyncGrid = new Gridifier(grid, {
    // Sort can be passed as object with function name/function pairs
    // ('default' sort(by array order) will be enabled by default)
    sort: {
        // You can set initial used function with 'selected' param
        selected: "firstSort",

        // Sort(third param) is a special object with sort helpers
        firstSort: function(first, second, sort) { /* Return sort comparator result */ },
        // ... More functions
    }
});

var asyncGrid = new Gridifier(grid, {
    // Sort also can be passed as single function
    // (Will be enabled by default and available with name "userfn")
    sort: function(first, second, sort) { /* Return sort comparator result */ }
});

var asyncGrid = new Gridifier(grid, {
    // sort param also can be used to set initial sort(string)
    sort: "sortName"
});

// Available functions in sort helper(3-rd parameter)
var sort = {
    "byOriginalPos": function(first, second) { ... },

    "byData": function(first, second, dataAttr, reverseOrder, replacers) { ... },
    "byDataInt": function(first, second, dataAttr, reverseOrder, replacers) { ... },
    "byDataFloat": function(first, second, dataAttr, reverseOrder, replacers) { ... },

    "byContent": function(first, second, reverseOrder, replacers) { ... },
    "byContentInt": function(first, second, reverseOrder, replacers) { ... },
    "byContentFloat": function(first, second, reverseOrder, replacers) { ... },

    "byQuery": function(first, second, selector, reverseOrder, replacers) { ... },
    "byQueryInt": function(first, second, selector, reverseOrder, replacers) { ... },
    "byQueryFloat": function(first, second, selector, reverseOrder, replacers) { ... }
}
        

var asyncGrid = new Gridifier(grid, {
    // Filter can be passed as object with function name/function pairs
    // ('all' filter(all items) will be enabled by default)
    filter: {
        // You can set initial used function with 'selected' param
        selected: "firstFilter", // or selected: ["filter1", "filter2"] for multiple

        firstFilter: function(item) { /* Return true(collect item) or false(don't collect item) */ },
        // ... More functions
    }
});

var asyncGrid = new Gridifier(grid, {
    // Filter also can be passed as single function
    // (Will be enabled by default and available with name "userfn")
    filter: function(item) { /* Return true(collect item) or false(don't collect item) */ }
});

var asyncGrid = new Gridifier(grid, {
    // filter param also can be used to set initial filter(string|array)
    filter: "filterName" // or filter: ["firstFilter", "secondFilter"]
});
        

var asyncGrid = new Gridifier(grid, {
    // Draggable item styler can be passed as object with function name/function pairs
    // ('cloneCSS' styler(clones all styles) will be enabled by default)
    drag: {
        // You can set initial used function with 'selected' param
        selected: "firstStyler",

        firstStyler: function(clone) {
            // Style clone here
            // (draggable item will be cloned and appended to document body)
        },

        // ... More functions
    }
});

var asyncGrid = new Gridifier(grid, {
    // Draggable item styler also can be passed as single function
    // (Will be enabled by default and available with name "userfn")
    drag: function(clone) {
        // Style clone here
        // (draggable item will be cloned and appended to document body)
    }
});

var asyncGrid = new Gridifier(grid, {
    // draggable item styler param also can be used to set initial styler(string)
    drag: "stylerName"
});
        

var asyncGrid = new Gridifier(grid, {
    // Toggler can be passed as object with toggle subobjects
    // ('scale' toggler will be enabled by default)
    toggle: {
        // You can set initial used toggler with 'selected' param
        selected: "customToggler",

        customToggler: {
            // We will write chapter 'how to write custom toggler' later
            show: function(item, grid, other params) { /* Show code */ },
            hide: function(item, grid, other params) { /* Hide code */ }
        },

        // ... More togglers
    }
});

var asyncGrid = new Gridifier(grid, {
    // toggle param also can be used to set initial toggler
    toggle: "togglerName"
});
        

var asyncGrid = new Gridifier(grid, {
    // Reposition sort can be passed as object with function name/function pairs
    // ('default' reposition sort(disabled) will be enabled by default)
    rsort: {
        // You can set initial used sorter with 'selected' param
        selected: "firstRsort",

        firstRsort: function(connections) {
            // Sort connections array here
            // You can calculate item width and height from connection x1, x2, y1, y2 values
            return connections;
        },

        // ... More functions
    }
});

var asyncGrid = new Gridifier(grid, {
    // Reposition sort also can be passed as single function
    // (Will be enabled by default and available with name "userfn")
    rsort: function(connections) {
        // Sort connections array here
        return connections;
    }
});

var asyncGrid = new Gridifier(grid, {
    // reposition sort param also can be used to set initial sort(string)
    rsort: "rsortName"
});
        

How to change settings?

var grid = new Gridifier(...);
grid.get("toggleTime"); // Returns current toggleTime - by def 500
grid.set("toggleTime", 1000); // Updates core setting with new val
grid.set([["toggleTime", 1000], ["toggleTiming", "ease"]]); // Set fn can accept array of settings
grid.set("toggleTime", 1000).set("toggleTiming", "ease"); // You can also use chaining to change multiple params

grid.addApi("sort", "newSort", function() { /* Sort here */ });
grid.setApi("sort", "newSort"); // Selects api fn