A jQuery grid system designed so that each cell can be "split" either horizontally or vertically. -
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist
spec
src
.gitignore
.travis.yml
Gruntfile.js
LICENSE
README.md
bower.json
config.js
docsConf.json
example.amd.html
example.html
favicon.ico
main.js
package.json

README.md

jQuery.gridSplit Build Status

A jQuery grid system designed so that each cell can be "split" either horizontally or vertically. Useful for creating interactive/dynamic grids from static HTML, JSON objects or user interaction.


Demo

Documentation

Installing, building and testing

  1. Download or clone this repo...

    $ git clone git@github.com:assetinfo/jquery.gridSplit.git
    
  2. Navigate to the directory containing jquery.gridSplit and run...

    $ npm install
    
  3. Followed by...

    $ bower install
    
  4. Then to build run...

    $ grunt
    
  5. And to test run...

    $ grunt test
    
  6. To use in your own project...

    • include dependencies and minified version of jquery.gridSplit.js
    <link rel="stylesheet" href="./src/css/jquery.gridsplit.css"/>
    <script src="./bower_components/jquery/dist/jquery.js"></script>
    <script src="./bower_components/jquery-ui/jquery-ui.js"></script>
    <script src="./dist/jquery.gridsplit.min.js"></script>
    • or include the optimised versions from ./dist/:
    <link rel="stylesheet" href="./dist/jquery.gridsplit.optimised.css"/>
    <script src="./dist/jquery.gridsplit.optimised.js"></script>
    • alternatively, require jquery.gridSplit in a module with the following in your config file...
    require.config({
        "deps": ["main"],
        "paths": {
            "jquery": "bower_components/jquery/dist/jquery",
            "core": "bower_components/jquery-ui/ui/core",
            "mouse": "bower_components/jquery-ui/ui/mouse",
            "widget": "bower_components/jquery-ui/ui/widget",
            "jqueryui-draggable": "bower_components/jquery-ui/ui/draggable",
            "gridsplit": "src/js/jquery.gridsplit"
        },
        "shim": {
            "jquery": { "exports": "$" },
            "jqueryui-draggable": ["jquery", "core", "mouse", "widget"]
        }
    });

Initialising a grid

  • A grid is initialised against a div that must have an id, and a class of .grid.

    • HTML
    <div id="grid1" class="grid"></div>
    • Javascript
    var grid = $('#grid1').gridSplit();
  • A grid can be defined prior to initialisation...

    • HTML
    <div id="grid2" class="grid">
        <div class="innerGrid" >
            <div class="gridColumn" gs-width="100%">
                <div class="gridCell" gs-height="50%">
                    <div class="fillCell"><a>Test1</a></div>
                </div>
                <div class="gridCell" gs-height="50%">
                    <div class="fillCell"><a>Test2</a></div>
                </div>
            </div>
        </div>
    </div>
    • Javascript
    var grid = $('#grid2').gridSplit({'useContent': true});
    
  • You can also set other options and events at initialisation...

    • disable 'resizable' functionality...
    var grid = $('#grid').gridSplit({'resizable':false});
    • split vertically by halfing column...
    var grid = $('#grid').gridSplit({'splitMethodV':'half'});
    • split vertically by evenly distributing the columns widths...
    var grid = $('#grid').gridSplit({'splitMethodV':''});
  • for more options see the documentation.

Manipulating a grid

  • A grid can be split with x/y co-ordinates, where x=column and y=cell.

    • Adding a column splits the focus cell vertically (into 2 columns).
    • Adding a cell splits the focus cell horizontally (adding 2 cells).
    grid.splitAt(0).splitAt(1,0).splitAt(0).addColumn(1).addCell(0,0).splitAt(1,0);
  • Cells can also be deleted using x/y co-ordinates:

    grid.delCell(1,0).delAt(0,0).delColumn(1).delAt(0);
  • Cells can be split into two columns by providing true as the 3rd param. This effectivaly adds a new grid with two columns into the cell, returning the new grid as the current grids context.

    var grid2 = grid.splitAt(1,0,true);
  • Nearly all functions which manipulate the grid will return 'this' (the current grids context), so in order to chain commands without breaking, use this.parent() to move the context to the grids parent grid (the top grids.parent() will === grids):

    var grid = grid.splitAt(1,0,true).parent().splitAt(1,0).splitAt(1,1,true).parent(); // grid is still #grids gridSplit instance
  • Grids can be rebuilt using JSON, the structure for which can be returned by calling:

    var meta = grid.returnMeta(); // "{"0":{"c":{"w":"20%"}},"1":{"0":{"0":{"c":{"w":"50%"}},"1":{"c":{"w":"50%"}},"h":"50%"},"1":{"h":"50%"},"c":{"w":"80%"}}}"
  • The grid can be cloned by initialising a new grid with the parsed meta object being passed in as 'data':

    var grid3 = $('#grid-clone').gridSplit({data:JSON.parse(meta)});
  • The grids $elements can be accessed using grids.gridsCells:

    var $el00 = grid3.gridsCells[0][0];
    var $el10_00 = grid3.gridsCells[1][0].data("grid").gridsCells[0][0];
  • To destroy the grid and any reference it adds:

    grid3 = grid3.destroy(); // this will not remove the element, but will empty it

License

Acknowledgements

  • Hoxton-one - Golden-layout - "The ultimate Javascript layout manager."
    • This library has similar functionality, but it's more fleshed out than jquery.gridSplit. We didn't see golden-layout until we had just about finished gridSplit, we think we have the edge on simplicity, but having not done a thorough comparison: we wouldn't want to discourage you from trying it. Examples can be found on their homepage.

Contact us


--- ---