A jQuery - Bootstrap plugin

This is a jQuery plugin that works alongside with Bootstrap and helps you create beautiful tiles.

Fork on GitHub

Documentation

Start Here! README

Templates

Choose one or more from the available templates or create a custom one!

Templates

Events

Listen to custom events!

Events

Paging

Organize your tiles in pages and navigate through them!

Paging

This is 'tempA' template!

Options

Customize the appearance and behaviour by setting your own options..

Options

And this is 'tempB' template!

Initialization

As a jQuery - Bootstrap plugin, in order to use jsTiles you have to include both jQuery and Bootstrap into your project. You also have to include jQuery easing in order to let animations get smoothly executed.

Include the following resources to your head section as shown below.

HTML - Head <head>
 <link href="../bootstrap-x.x.x/css/bootstrap.min.css" rel="stylesheet" />
 <link href="../jstiles/css/tl-style.css" rel="stylesheet" />
 <script src="../jQuery.js"></script>
 <script src="../jstiles/jstiles.js"></script>
</head>

But where are you going to initialize jsTiles plugin? All you have to provide is a simple set of divs (the tiles) wrapped in a page container and an outer div that holds the page and the containing tiles.

Below you can see the most simple form of html markup that jsTile require in order to create your tiles.

HTML - Body <!-- The outer container: initialize here -->
<div id="tiles-container">
 <!-- The page section -->
 <div class="tl-page" data-tl-template="tempA">
   <!-- Place the tiles here -->
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
 </div>
</div>

It is very important to provide a "tl-page" class to the page section. jsTiles will take care of the rest and create your tiles inside each page section.

You can place more than one page sections and provide a different template for each one of them!

You can set the page template via the "data-tl-template" attribute to the page section div. If you do not provide a specific template, jsTiles will set a default one.

You can initialize jsTiles in one line of code as shown below.

jQuery - Initialization $('#tiles-container').jstiles();

And you have your tiles!

Options

There is a number of options you can use in order to customize the appearance and behaviour of the plugin. Check them below or go to README file!

loader [number]

Provide a number (greater that zero) that indicates the duration (in milliseconds) of the loader appearance, if you want to display the loader before the tiles load.

If you want to display the tiles immediately on load, set this option to zero.

  • Possible values:[number] (any number greater than zero)
  • Default value:500

loaderHtml [string]

If you want to display a custom loader you can set it right here! Just pass your loader HTML markup through loaderHtml option as shown in the example below.

Custom loader var opt = {
 loaderHtml: '<div id="my_custom_loader">Loading!!!</div>'
}
$('#tiles-container').jstiles(opt);

If this option is set to false and the loader option is not zero, jsTiles will display the default loader (refresh this page and you will see it!).

  • Possible values:[string] (any valid HTML)
  • Default value:false

templateObj [object]

With this option you can tell the plugin to include your custom templates too, so that you can apply them to any page you want!

Check the TEMPLATES TUTORIAL to learn how you can create your custom template.

Custom template var myCustomTemplate = {
 //Create your template object here
}
var opt = {
 templateObj: myCustomTemplate
}
$('#tiles-container').jstiles(opt);
  • Possible values:[object] (a template object - check the tutorial)
  • Default value:false

pageHome [number]

Set the page that is going to be visible on load by providing a zero based index. For example, if you want the second page to be visible on load, you must set this option equal to 1.

Note This option will take no effect if you have only one page to display. Also, you must provide a number that is not greater than the pages number minus one (eg if you have 3 pages, you can set this option up to the value of 2).

  • Possible values:[number] (zero based index)
  • Default value:0

tilePadding [string]

Set the padding of the tiles. By default, this option is set to false, so that the tiles can take the default padding (5px) from the css file.

Note This option applies the same padding to all tiles. However, you can provide specific padding value to a specific tile through the template object.

  • Possible values:[string] (any valid padding value)
  • Default value:false

tileRatio [number]

Set the height to width ratio of the tiles. By default, this option is set to false, so that the tiles can take the default ratio (0.57) from the css file.

Note This option applies the same ratio to all tiles. However, you can provide specific ratio value to a specific tile through the template object.

  • Possible values:[number] (any number greater that zero)
  • Default value:false

sliderEasing [string]

Set the easing function for the sliding animation of the pages.

  • Possible values:[string] (any valid easing function)
  • Default value:'easeInOutExpo'

slideDuration [number]

Set the duration of the pages sliding animation in milliseconds.

  • Possible values:[number] (any positive number)
  • Default value:450

Methods

destroy

This method removes any data attached to the selector as any element that was appended in order to display the tiles.

How to call it? Check the following example.

Destroy the plugin $('#tiles-container').jstiles('destroy');

Templates

In this section you are going to learn how to create your own custom template and how to use it in your project.

Let's assume that we have the following HTML markup with one page and four tiles.

HTML <div id="tiles-container">
 <div class="tl-page" data-tl-template="myTemplate">
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
   <div>Content</div>
 </div>
</div>

Let's create a basic template like the one below.

In order to create a custom template we have to set at least two things:

  • tilesNum [number]
  • tiles [object]
Template object var myTemplateObject = {
 myTemplate: {
  tilesNum: 4,
  tiles: {
   0: 'col-xs-12 col-md-6',
   1: 'col-xs-12 col-md-6',
   2: 'col-xs-12 col-md-6',
   3: 'col-xs-12 col-md-6'
  }
 }
}

And let's explain it's parts.

First of all we have to indicate how many tiles the template has to process. We must provide the exact number of available elements inside the page that we are going to apply the specific template.

Note The plugin will not work if we provide a different number than the one of the actual tiles.

Tiles number //We have four divs inside the page element
tilesNum: 4

The second step is to set the tiles object, within which we can use all of the available Bootstrap classes (grid layout).

So, let's set the tiles to occupy half of the available width for medium width screens and above, and the 100% of the available width for small screens.

Tiles number tiles: {
 0: 'col-xs-12 col-md-6',
 1: 'col-xs-12 col-md-6',
 2: 'col-xs-12 col-md-6',
 3: 'col-xs-12 col-md-6'
}

Now that we have created our first custom template, we have to implement it. You can check the options section at the templateObj part to see how you can provide a custom template to the plugin.

Here is the jQuery that inserts the new template:

Initialization var opt = {
 //Set the custom template
 templateObj: myTemplateObject
}
$('#tiles-container').jstiles(opt);

And here is your first custom template!

Example#1 - Basic template

Columns

There are times you might want to place some tiles inside a column and place that column wherever you want inside the tiles page.

You can achieve that by setting the optional columns object.

Let's edit our example and place one column that will contain the first three tiles and occupy the 9/12 of the available width.

All you have to do, is edit the template we created and add the columns object.

Columns object columns: {
 0: {
  //Set the column classes
  colClass: 'tl-col col-xs-12 col-md-9',
  //Indicate the first tile inside the column (zero based index)
  start: '0',
  //Indicate the last tile inside the column (zero based index)
  end: '2'
 }
}

However, the tiles that are going to be wrapped by the column will try to occupy the available width of this column, which is the 9/12 of the page column.

So, we have to slightly change some classes form the tiles object and adapt them to our new structure.

Tiles object tiles: {
 0: 'col-xs-12 col-md-7',
 1: 'col-xs-12 col-md-2',
 2: 'col-xs-12 col-md-5',
 3: 'col-xs-12 col-md-3'
}

This is the result of our changes.

Example#2 - Columns

Rows

Let's add four more tiles in the page and change our template as follows!

Template object var myTemplateObject = {
 myTemplate: {
  tilesNum: 8,
  columns: {
   0: {
    colClass: 'tl-col col-xs-12 col-md-9',
    start: '0',
    end: '2'
   }
  },
  tiles: {
   0: 'col-xs-12 col-md-7',
   1: 'col-xs-12 col-md-2',
   2: 'col-xs-12 col-md-5',
   3: 'col-xs-12 col-md-3',
   4: 'col-xs-12 col-md-3',
   5: 'col-xs-12 col-md-3',
   6: 'col-xs-12 col-md-3',
   7: 'col-xs-12 col-md-3'
  }
 }
}
Example#3.1 - Rows

But we wanted all the new tiles to be places under the first four! Instead, the fifth tile goes under the fourth tile.

To overcome this obstacle we can place all the last four tiles inside a row. Let's create the rows object.

Rows object rows: {
 0: {
  rowClass: 'tl-row col-xs-12',
  start: '4',
  end: '7'
 }
}

See how the last four tiles are aligned into a single row under the first four tiles.

Example#3.2 - Rows

Animations

Now let's make our tiles more attractive by adding an animation on load. You can do this by creating an animations object.

The animations object is a set of objects that apply to each tile separately.

  • tlClass [string]: The class that the specific tile will get.
  • tlClassF [string]: The class that the specific tile will get and trigger the css animation.
  • tlDelay [number]: The time in milliseconds that the animation will wait until it starts getting executed.

At the moment, there are six animations ready to be used but more are coming! You can create your self your own animation type by adding a new set of css rules that will perform a different animation!

These are the available animation types:

  1. tl-scale
  2. tl-fade
  3. tl-slide-up
  4. tl-slide-down
  5. tl-slide-left
  6. tl-slide-right

tl-scale

Animations object (tl-scale) animations: {
 0: { tlClass:'tl-scale', tlClassF:'tl-scale-up', tlDelay:150 },
 //...
}
Example#4.1 - Animations (tl-scale)

tl-fade

Animations object (tl-fade) animations: {
 0: { tlClass:'tl-fade', tlClassF:'tl-fade-in', tlDelay:150 },
 //...
}
Example#4.2 - Animations (tl-fade)

tl-slide-up

Animations object (tl-slide-up) animations: {
 0: { tlClass:'tl-slide-up', tlClassF:'tl-slide-up-f', tlDelay:150 },
 //...
}
Example#4.3 - Animations (tl-slide-up)

tl-slide-down

Animations object (tl-slide-down) animations: {
 0: { tlClass:'tl-slide-down', tlClassF:'tl-slide-down-f', tlDelay:150 },
 //...
}
Example#4.4 - Animations (tl-slide-down)

tl-slide-left

Animations object (tl-slide-left) animations: {
 0: { tlClass:'tl-slide-left', tlClassF:'tl-slide-left-in', tlDelay:150 },
 //...
}
Example#4.5 - Animations (tl-slide-left)

tl-slide-right

Animations object (tl-slide-right) animations: {
 0: { tlClass:'tl-slide-right', tlClassF:'tl-slide-right-in', tlDelay:150 },
 //...
}
Example#4.6 - Animations (tl-slide-right)

Feel free to mix up those animation into the same template object to achieve your custom animation!

Configuration

We've seen in options section that we can set another padding or ratio for the tiles by just passing the right values to the appropriate options (tilePadding - tileRatio).

These options get applied to all tiles. But, what if you would like to set specific padding or/and ratio for a specific tile?

config object is what you need!

Let's add a config object to our custom template in order to give a specific padding and ratio to the first tile.

Config object config: {
 0: {
  //Set the padding with a valid string
  padding: '30px',
  //Set the ration with a positive number
  ratio: 1,
 }
}

Check the followng example. The first tile has a padding of 30px and it's height/width ratio is equal to 1 (a perfect square!).

Example#5 - Configuration

Paging

In many occasions you might want to split your tiles in pages and implement a smooth navigation.

jsTiles gives you the ability to implement this feature simply by wrapping the desired tiles into a page section and apply an appropriate template for each page.

Let's add another page to our previous example and set our custom template and the default 'tempA' template to the first and second page respectively.

HTML <div id="tiles-container">
 <div class="tl-page" data-tl-template="myTemplate">
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
 </div>
 <div class="tl-page" data-tl-template="tempA">
   <!-- tempA needs 10 tiles to work, so we add a page with 10 divs -->
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
   <div></div>
 </div>
</div>

Now just initialize the plugin just like you have done it so far. jsTiles will recognize that there are more than one pages and will implement the paging feature automatically.

Example#6 - Paging

Events

jsTiles triggers various events on different parts of the plugin's execution life cycle.

Every event returns the selector on which the plugin has been initialized, so that you can distinguish the element that each event refers to.

Here's how you can call a function on an event execution:

Event //Replace event.name with the actual event's name
$(document).on('event.name', function(e, data) {
 if (data == '#selector') {
  //Do your stuff...
 }
});

tl.tilecontent.appended

This event is triggered as soon as the inner content of all tiles has been appended.

tl.template.built

This event is triggered as soon as the templates have been built.

Now you are ready to experiment and create beautiful tiles taking advantage of the many options that are available form Bootstrap!