Tiler.JS
Library for creating of endless tile-based grid. Initially written for the Minefield.
Dependencies
Documentation
Constructor
new Tiler(element, options);
element
A jQuery
or DOM
element will be used as a viewport for a tiles grid.
options
-
fetch(tofetch, removed)
This method is called each time the grid is ready to be refreshed or reloaded.
Arguments:
tofetch
- array of tiles coordinates to show on the grid[[x1, y1], [x2, y2], [x3, y3], ...]
removed
- array of tiles coordinates that were removed from the grid[[x1, y1], [x2, y2], [x3, y3], ...]
-
tileSize
Tile size in pixels, considering that tile is a square.
-
margin
Count of extra rows of tiles to be shown behind the viewport perimeter.
Default:
2
-
x,y
Initial coordinates of the top left visible tile which coordinates are also current coordinates of the grid. Tiler fetches tiles that do fall within the grid area depending on this coordinates.
Default:
0
Properties
-
element
A viewport element. Automatically wrapped in a
jQuery
object if you pass it as aDOM
element. -
grid
A grid element used as a tiles container. Wrapped in a
jQuery
object and appended to the viewport element.
Methods
-
refresh()
Removes tiles that don't fall within the current grid area and fetches absent tiles. Call this method if the grid was dragged/moved or viewport size is changed, also in case unless all tiles are present after the fetch and you have to fetch absent tiles only.
-
reload()
Refetches all tiles that fall within the grid area.
-
show()
show(x, y, elem|[elem1, elem2, ...])
Shows a tile (some content) in passed coordinates. The tile can be both
jQuery
orDOM
element, or anarray
ofjQuery
orDOM
elements. The tile want be shown if passed coordinates don't fall within the current grid area. If there is already a tile in passed coordinates on a grid it will be removed.show(tiles)
As the same behavior as in previous but for array of tiles. Array structure:
[ [x1, y1, elem|[elem1,elem2,...]] , [x2, y2, elem|[elem1,elem2,...]] , [x3, y3, elem|[elem1,elem2,...]] , ... ]
-
remove()
remove(x, y)
Removes tile in passed coordinates. Does nothing if there is no tile in passed coordinates.
remove(coords)
As the same behavior as in previous but for array of coordinates. Array structure:
[[x1, y1], [x2, y2], [x3, y3], ...]
-
coords([x, y])
If arguments are passed - changes current grid coordinates (top left visible tile) and fetches/removes tiles as in the same way as
refresh
method does. If method is called without arguments - returns current grid coordinates:{x: {Number}, y: {Number}}
-
inGrid(x, y)
Returns
true
if the coordinates fall within the current square of the grid, otherwise returnsfalse
.
Using Tiler
-
Include main dependencies on your page.
<script src="http://code.jquery.com/jquery.min.js"></script> <script src="https://raw.github.com/borbit/row.js/master/row.js"></script> <script src="https://raw.github.com/borbit/grid.js/master/grid.js"></script>
-
Include Tiler after main dependencies.
<script src="tiler.js"></script>
-
Include some library to make grid draggable. I use
draggable
from jQuery UI.<script src="http://code.jquery.com/ui/1.8.19/jquery-ui.min.js"></script>
-
Create an instance of
Tiler
passing the element you have to make as a viewport by first argument and options by second. Don't forget to pass required optionstileSize
andfetch
. Like this:var tiler = new Tiler($('#viewport'), { tileSize: 200, fetch: function(tofetch) { tofetch.forEach(function(tile) { var img = new Image(); var x = tile[0]; var y = tile[1]; img.onload = function() { tiler.show(x, y, $('<img/>').attr('src', img.src)); }; img.src = 'image_' + x + '_' + y + '.png'; }); } }); tiler.refresh();
-
To make grid draggable just:
tiler.grid.draggable();
-
Refresh grid during the dragging:
tiler.grid.bind('drag', function() { tiler.refresh(); });
Tests
Tiler is fully covered by QUnit tests. To run tests
just open the tests/index.html
in a browser.
Contributors
I will be very appreciated for any contribution.
License
Tiler may be freely distributed under the MIT license.
Copyright (c) 2011 Serge Borbit <[email protected]>