Overview

The ThumbsGrid is a reusable UI component for presenting data in the form of a thumbs. It's main function is to display thumbnails with image plus caption, but in fact ThumbsGrid can be easily extended further and adjusted with another UI elements, like Buttons, etc. Thumbs' appearance can be easily controlled with CSS.

 

Include resource files

  • /Shared/Scripts/lazy_loader.js
    • <script type="text/javascript" src="/Shared/Scripts/lazy_loader.js"></script>
  • /Shared/UIComponents/Internal/ThumbsGrid

    • css/thumbs_grid.css

      <link rel="stylesheet" type="text/css" href="/Shared/UIComponents/Internal/ThumbsGrid/css/thumbs_grid.css">

    • Scripts/thumbs_grid.js

      <script type="text/javascript" src="/Shared/UIComponents/Internal/ThumbsGrid/Scripts/thumbs_grid.js"></script>

 

Default Options

Name Description Type Default Value
data Default data to render Array []
show_icon Whether to display image or not Boolean true
show_label Whether to display label or not Boolean true
top_html HTML to be displayed on top of each thumb String ""
bottom_html HTML to be displayed below each thumb String ""
columns Number of columns to split the grid to. 0 (zero) means no columns (grid takes all available estate (a.k.a. "auto")) Number 0
key_imagesrc Data key name of image source file (if any). See possible values String "icon"
key_label Data key name of label (if any). See possible values String "label"
selected Key-value pair; selects the first matched thumb which has the same key-value pair Object null
lazy_load Whether to load images on demand (a.k.a. lazy loading) or not Boolean true
enable_queue Whether to start queue immediately or wait for a call outside Boolean true
filters Filters to be applied over the thumbs. (see Filters) Array []
sort Sort option to be applied over the thumbs by a key-value pair Object null

 

Possible key_* values

All key_* options define the paths to values in the data structure (see example).

Possible values are "src", "image.src", '["cells"]["123.123456"]', etc.

 

Methods

Name Description Parameters Returns
setData Sets data to the instance and renders it data: Object -
getData Returns current data - data: Object
empty Clears current data. Removes all thumbs from view - -
destroy Destroys the whole UI - -
selectThumbByKeyValue Selects the first matched thumb by key name and value key: String (See possible values),
value: Mixed		 success: Boolean
selectPrev Selects the previous thumb relative to the currently selected one, and taking into account filters & sorting. If no currently selected thumb, or currently selected is the first one, will select the last one - -
selectNext Selects the next thumb relative to the currently selected one, and taking into account filters & sorting. If no currently selected thumb, or currently selected is the last one, will select the first one - -
applyFilters Applies filtering over the thumbs. Each thumb that does not match any filter will be removed from the grid filters: Array (see Filters) num_filtered: Number
applySorting Applies sorting over the thumbs by a data key. Can accept a custom sorting function key: String (See possible values),
sort_fn: Function (optional)		 -

 

Filters

The Filters Array contains Filter Groups, which are also Arrays, which contain Filter Objects:

 

{
   key_name    : 'key.anotherkey["anotherkey"]',   // path to the key name in the data object
   expression  : /regexp pattern/                  // RegExp pattern or function
}

 

The key_name is the path to the key in data object See possible values. The expression could be a RegExp or a Function.

 

All Filter Objects in a Group are OR-ed (disjunction). All Groups are AND-ed (conjunction).

 

Example of a Filters Array:

 

[
   [
      // these will be OR-ed
      {
         'key_name'  : 'label',
         expression  : /test/i
      },
      {
         'key_name'  : 'id',
         expression  : /1234/
      }
   ],
   // All groups will be AND-ed
   [
      {
         'key_name'  : 'label',
         expression  : /test/
      }
   ]
];

 

Events

Name Description Arguments
onSelect Fires when the user has selected a thumb thumb_data: Object
onReady Fires when the UI is ready -

 

Examples

 

Configurations for different Data Structures

  • Let's say we have the following data structure:

 

var data = [
   {
      icon  : 'http://0101.nccdn.net/1_5/040/37c/258/121433889430310.png',
      label : 'Sample Image'
   },
   {
      icon  : 'http://0101.nccdn.net/1_5/040/37c/258/121433889430310.png',
      label : 'Sample Image'
   }
];

 

  • For this data structure, we will have the following configuration:

 

new SK.UI.ThumbsGrid( 'placeholder-id', {
   data           : data,
   key_imagesrc   : 'icon',
   key_label      : 'label'
});

 

  • Now let's say our data comes from the database:

 

var data = [
   {
      cells    : {
         '123.123456'   : 'http://0101.nccdn.net/1_5/040/37c/258/121433889430310.png',
         '123.654321'   : 'Sample Image'
      },
      row_id   : '123.1'
   },
   {
      cells    : {
         '123.123456'   : 'http://0101.nccdn.net/1_5/040/37c/258/121433889430310.png',
         '123.654321'   : 'Sample Image'
      },
      row_id   : '123.2'
   }
];

 

  • In this case the configuration will look lie this:

 

new SK.UI.ThumbsGrid( 'placeholder-id', {
   data           : data,
   key_imagesrc   : 'cells["123.123456"]',
   key_label      : 'cells["123.654321"]'
});

 

Primary usage of Filters as with custom sort function

  • Let's use the following data:

 

var data = [
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 04',
      filter: 'even',
      style : ['first']
   },
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 07',
      filter: 'odd'
   },
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 02',
      filter: 'even'
   },
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 03',
      filter: 'odd'
   },
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 06',
      filter: 'even'
   },
   {
      icon  : 'http://revistawindows.com.br/wp-content/uploads/2014/04/xp.jpg',
      label : 'Sample Image 05',
      filter: 'odd'
   }
];

 

  • Filtering the data to the value of the "filter" property:

 

new SK.UI.ThumbsGrid( 'placeholder-id', {
   data        : data,
   filters     : [
      [{
         key_name    : 'filter',
         expression  : /^even$/
      }]
   ]
});

 

Implement a Button to each Thumb

 

  • For this example we will create a class extending ThumbsGrid:

 

var MyThumbsGrid = new Class({
   
   Extends     : SK.UI.ThumbsGrid,
   
   initialize  : function () {
      this.parent.apply( this, arguments );
      // attach onReady event and add the callback which will create the Button
      this.addEvent('ready', this.addButtons);
   },
   
   addButtons  : function () {
      // loop all thumbs and create a Button
      this.getThumbs().each( this.addButton, this );
   },
   
   addButton   : function ( thumb ) {
      // add event listener to the thumb
      thumb.addEvent('buttonClick', this.onButtonClick.bind(this, [thumb]));
      // create the Button
      var button = new SK.UI.Properties.Button( thumb, {
         event    : 'buttonClick'
      });
      // inject it in the bottom of the thumb
      button.inject( this.getThumbBottomElement( thumb ) );
   },
   
   onButtonClick  : function ( thumb ) {
      // do something here with the thumb...
   }
      
});