To get started with tiles.js, you’ll need to include jQuery and tiles.js in your HTML source as shown below:
<!DOCTYPE html>
<html lang="en">
<head>
<!-- first load jQuery -->
<script defer src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
<!-- then load tiles.js -->
<script defer type="text/javascript" src='https://hhc97.github.io/tiles-js/pub/js/tiles.js'></script>
<!-- then load a script that depends on tiles.js -->
<script defer type="text/javascript" src='js/examples.js'></script>
</head>
By default, tiles.js assigns itself to the global
Tiles
variable when loaded. If the Tiles
variable is already in use, it will not be
overwritten.
Once loaded, you can get an instance of Tiles by calling its constructor:
const tiles = new Tiles({container: 'id'})
Note that you must create a new
instance of Tiles
for each section of tiles that you want to create, or there could be unintended
behavior.
There is only one constructor required to use tiles.js, and it has one required value, with a few other optional parameters. A constructor call with every possible option is shown below:
new Tiles({
container: 'tile_container_div_id',
width: 100,
height: 100,
animate: true,
animate_factor: 5,
color_cycle: true,
nodrag: true,
tile_gap: 30,
num_horizontal: 2
})
The parameters are provided in the form of a
javascript object, so optional parameters can be left out if desired.
Required parameters
Type
: string
Default value
:
none
Description
: In order to
use tiles.js, you must provide it a <div>
element with a unique id
in which you want to display tiles. The value of the id
goes into this parameter.Optional parameters
Type
:
number (integer)
Default value
:
100
Description
: The width
you want the tiles in this section to be.Type
:
number (integer)
Default value
:
100
Description
: The height
you want the tiles in this section to be.Type
:
boolean
Default value
:
true
Description
: On hover,
you can choose to allow the tiles to slightly expand in an animation. This gives the user a visual
cue that the tile is being hovered across. The content in the tile will expand along with the tile.
Type
:
number (float)
Default value
:
1.05
Description
: If
animate
is set to true
, then you can optionally specify how much you want
your tiles to expand when they are being hovered over. The default value of 5% looks good in most
situations, but you have the option of choosing your own expansion factor.
Type
:
boolean
Default value
:
false
Description
: This option
enables the color gradient around each tile to constantly change color. The colors are generated
randomly and slowly change randomly as well. It is useful for when the theme of the website is a
little less serious!Type
:
boolean
Default value
:
false
Description
: By default,
tiles in a section can be dragged around and the user can swap the positions of tiles by dragging
and dropping. Setting this option to true
will prevent tiles from being dragged, which
is useful for when you have tiles that must display content in a certain order.Type
:
number (integer)
Default value
:
30
Description
: This option
adjusts the width of the gap between tiles.Type
:
number (integer)
Default value
:
Infinity
Description
: This option
specifies the maximum number of horizontally adjacent tiles in the current section. Note that if the
viewport width cannot accomodate so many tiles, then this value is automatically capped.Once you have created an instance of
Tiles
, these are the API methods that can be called and their available options:
addTile({options})
returns
the ID of the added tile
.
title
Type
:
string
Default value
:
''
Optional
:
yes
Description
: This
specifies the title of the newly added tile, which is the text that appears on top of each
tile. If this is not provided, no title will appear.img_src
Type
:
string
Default value
:
''
Optional
:
yes
Description
:
This specifies the source of the image that will appear in the tile. Specifying an image is
optional.hover_color
Type
:
string
Default value
:
cyan
Optional
:
yes
Description
:
This specifies the color of the outline that will appear when the tile is hovered over.clickLink
Type
:
string
Default value
:
''
Optional
:
yes
Description
:
This specifies an optional link that can be opened when the tile is clicked.alt_img
Type
:
string
Default value
:
''
Optional
:
yes
Description
:
This specifies an alternative image that can be shown when the tile is clicked. This option
cannot be used in conjuction with clickLink
.click_callback
Type
:
function
Default value
:
null
Optional
:
yes
Description
:
This specifies a function that should be called when the tile is clicked. The function must
take 1 argument. Upon being clicked, the function will be called as f(tile)
,
where tile
will represent the current state of the tile.sort()
shuffle()
flip(tileid)
tileid
Type
:
string or number (integer)
Optional
:
no
Description
:
The ID of the tile to flip.disable(tileid)
tileid
Type
:
string or number (integer)
Optional
:
no
Description
:
The ID of the tile to disable.disableAll()
enable(tileid)
disable()
. Note that if the section has been disabled by disableAll()
,
then simply calling enable will not work.
tileid
Type
:
string or number (integer)
Optional
:
no
Description
:
The ID of the tile to enable.enableAll(propagate)
propagate
Type
:
boolean
Optional
:
no
Default value
:
false
Description
:
This parameter specifies whether to propagate the effects of the enableAll()
call to all the tiles in this section. If a tile has been disabled by a call to
disable()
, calling enableAll(false)
will not enable that tile, but
calling enableAll(true)
will.