SN GRID

NAME

sngrid - A grid editor for Bootstrap.

DESCRIPTION

A grid manager for Bootstrap 3 written in TypeScript (js) and SASS (css).

For now, it can be mounted on any Bootstrap-powered layout that follows this hierarchy:

#grid > .container > .row > .col-md-x > .row > .col-md-x
/* You can name your wrapper the way your want, as long as you have one */

FEATURES

• Toggle on/off
• Create element
• Clone element
• Remove element
• Move element
• Swap two elements
• Toggle element css class
• Toggle container mode (fluid vs regular)
• Auto-resize other columns to fit all available space
• Resize columns with handle
• Hide/show element for different device breakpoints
• Resize columns for each device breakpoint
• Apply offset to columns
• Support for nested rows in columns
• Add widget programmatically
• Export layout to JSON
• Event-driven design for easy integration with other tools
• Support for multiple grids in the same page

USAGE

ASSETS TO INCLUDE

• jquery-2.2.4.min.js
• bootstrap.min.js
• bootstrap.min.css
• font-awesome.min.css
• sngrid.js
• sngrid.css

HTML

<div id="grid">
    <div class="container">
        <div class="row">
            <div class="col-md-6">
            </div>
            <div class="col-md-6">
            </div>
        </div>
    </div>
    <div class="container-fluid">
        <div class="row">
            <div class="col-md-12">
            </div>
        </div>
    </div>
</div>

BASIC USAGE

// Initialize the grid
var grid = sn.grid.Grid(document.getElementById("grid"), {
   
    // row size (in columns)
    size: 12,

    // events prefix
    eventPrefix: "sn:",

    // swap animation speed (in miliseconds)
    swapSpeed: 750,

    // move animation speed (in miliseconds)
    moveSpeed: 750,

    // language
    language: "en",

    // restrict edition to these types only (null = all)
    // ex.: 
    // allowedTypes: ["widgetarea", "widget"]
    allowedTypes: null

});

// Enable edition
grid.setEnabled(true);

// Disable edition
grid.setEnabled(false);

// change device mode (xs, sm, md, lg) 
grid.setBreakpoint("sm"); 

// export grid to json (for serialization purpose) 
var grid_json = grid.toJSON();

// listen to an event
grid.on("elementActivated", function(event, element) {
    console.log(event, element);
});

API OF THE INSTANCE OF A GRID

/*
    create an element
    
    @type: "column", "row", "container", "widget", etc...
    @locationElement: the container or sibling of the new element
    @locationFn: name of the JQuery function to use (appendTo, insertBefore, prependTo, insertAfter, etc...)
    @content: boolean (do we clone children) or string (arbitrary html)
*/
createElement: function(locationElement: JQuery, type: string, locationFn: string, content: boolean | string)

// execute custom action
executeAction(actionName: string, element: JQuery, args?: any)

// if the grid is currently enabled or not
isEnabled: function(): boolean

// return currently selected element
getActiveElement: function(): JQuery

// return element by sn id
getElementById: function(id: string): JQuery

// get an element's css classes (excluding internal ones)
getElementClasses: function(element: JQuery): Object

// return position of element in its parent
getElementPosition: function(element: JQuery) : number

// get an element's type
getElementType: function(element: JQuery): string

// return uuid of element
getElementId: function(element: JQuery): string

// remove a listener
off: function(eventName: string, callback: any)

// register a listener to a specific internal custom event
on: function(eventName: string, callback: any)

// remove an element
removeElement: function(element: JQuery)

// toggle selected element
setActiveElement: function(element: JQuery)

// set css property
setElementStyle: function(element: JQuery, propertyName: string, value: any)

// set active device breakpoint
setBreakpoint: function(breakpoint: string)

// toggle enabled state
setEnabled: function(enabled: boolean)

// toggle currently hovered element
setHoveredElement: function(element: JQuery) 

// export grid to json
toJSON(): Object

// toggle css class for a specific element
toggleElementClass: function(element: JQuery, className: string)

EVENTS

EXTEND THE EDITOR

API OF THE CONFIGURATOR

// register a new editable element type
sn.grid.registerType(name: string, options?: any)

// return the definition of an editable element type
sn.grid.getType(type: string)

// define a new device breakpoint
sn.grid.registerBreakpoint(id: string, options?: any)

// get definition for a specific device breakpoint
sn.grid.getBreakpoint(id: string)

// get breakpoints sorted by device size 
sn.grid.getSortedBreakpoints()

// register a new bindable action
sn.grid.registerAction(id: string, options: any)

// generate a unique UUID
sn.grid.uuid()

Exemples

// add support for large screens
sn.grid.registerBreakpoint("lg", {

    // is it the default device
    default: true,
    
    // for sorting purpose
    priority: 1,

    // do we try to adjust siblings when adding/removing/resizing a column
    autoResizeColumns: true
});

// add support for containers
sn.grid.registerType("container", {

    // how elements of this type are stacked
    orientation: Orientation.VERTICAL,

    // jquery/sizzle selector
    selector: "[class^='container']",

    // which CSS class to apply to new elements
    className: "container",

    // which CSS class to apply to new elements that are fluid 
    classNameFluid: "container-fluid", 

    // which types can be contained in these elements 
    contains: ["row"], 

    // action buttons 
    buttons: { right: ["moveBefore", "moveAfter", "toggleFluid"] }, 

    // action buttons to put in the dropdown menu
    menu: [],

    // label
    label: name,
    
    // dom tag 
    tagName: "div",
 
    // do we copy these elements when parent is cloned 
    cloneable: true, 

    // can we move these elements freely with the mouse 
    movable: true, 

    // can be selected 
    selectable: true, 

    // custom creation function 
    create: null, 

    // custom removal function 
    remove: null, 

    // extra html elements to add after toolbar 
    extraElements: "",
   
    // default children to add when creating a new element
    defaultChildren: []

}); 

// register an action to move element before another one (up or left) 
sn.grid.registerAction("moveBefore", {
 
    // tooltip text
    tooltip: "Swap with previous element",

    // class name generator (or value)
    className: function(element: JQuery, type: string, config): string {
        let value = "sn-btn-move-before "
        value += (config.orientation === Orientation.VERTICAL) ? "fa fa-arrow-up" : "fa fa-arrow-left"
        return value
    },

    // main function
    callback: function(element: JQuery, event: JQueryEventObject, api, args?: any)
    {
        let otherElement = element.prev(".sn-mounted")
        if(otherElement.length > 0)
            api.swapElements(element, otherElement)
    },

    // update function
    update: function(element: JQuery)
    {
        let otherElement = element.prev(".sn-mounted")
        if(otherElement.length > 0)
            element.children(".sn-toolbar").find(".sn-btn-move-before").removeClass("hidden")
        else
            element.children(".sn-toolbar").find(".sn-btn-move-before").addClass("hidden")
    },

    // dom event that trigger action
    on: "click",
})

AUTHOR

Jean-Georges Guénard, <jg@sednove.com>