jQuery Grid Widget

August 11, 2011 by Acatl Pacheco

Widget that will render a table using a dataProvider as its source, all cells and headers of the grid can be customized.

Features:

  • 100% Customizable Header Cells (td)
  • 100% Customizable Cells (td)
  • CSS free, you may customize your widget as how ever you want.
  • Cross browser. Supports for IE 6.0+, FireFox 2.0+, Safari 3.0+, Opera 9.2+ and Google Chrome.


What makes it special

The main difference between this grid and most of the other grids out there on the web is that this widget does not do any fancy sorting, column dragging or any other user interaction. This is a clean no-css, no-multi-feature widget. You may customize it to your needs, and make an amazing app with it!

Options:

dataProvider : null : Array
Array, is the data source of the widget.

Example:

      var dataProvider = [/* data */];
      $( ".selector" ).grid( "option", "dataProvider", dataProvider );

columns : [] : Array
Array, Represents the column definition of the grid, you must set this option accordingly for the widget to work.

Example:

      var columns = [
      { field: "name" },
      { field: "e-mail" }
      ];
      $( ".selector" ).grid( "option", "columns", columns );

For a complete description of the column options please Read the section bellow called “Defining your Columns”.

rowFunction : null : function
This function will be executed every time a row is created on the rendering process. You can use this option to make any final adjustments to you rows at their moment of creation.
Usage:

      var gridOptions = [
      { field: "name" },
      { field: "e-mail" },
      /**
      * tr: instance of the current tr being created
      * rowIndex: index of the current row
      * rowData: Object with information of the current row
      **/
      rowFunction: function (tr, rowIndex, rowData) {
        if(rowIndex == 0) {
          tr.css("background", "red");
        }
      }
      ];
      $( ".selector" ).grid( gridOptions );

Basic Usage

The most basic example of implementing the ir.grid widget is:

  // Define a data source
  var gridData = [
  { name: "Polo", email: "polo@email.com", phone: "22-22-34"},
  { name: "Rafael", email: "rafa@email.com", phone: "22-34-56"},
  { name: "Edgar",  email: "edgar@email.com", phone: "22-67-45"},
  { name: "Luis", email: "luis@email.com", phone: "22-95-45"}
  ];

  // Define the grid's options
  var gridOptions = {
    columns: [
    { label: "Name", field: "name" },
    { label: "E-mail", field: "email" },
    { label: "Phone", field: "phone" }
    ]
  };

  $(".selector").grid( gridOptions );
  $(".selector").grid("option", "dataProvider", gridData);

Defining your Columns

The best part about ir.grid is how you can configure each cell/column on the grid.

The columns option is an array with a collection of column objects. Each object defines how a field should be rendered when created.

These are the options you can configure on each column Object:

label: String
Defines the column’s title.

field: String
Defines the name of the filed the column will use as its data source.

style: String/Object
If a String is passed it will be used the CSS class or classes (separated by a space) to attach to the current td cell.

Example:

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // list of CSS classes separated by a space
          style: "class-name-1 class-name-2 class-name-3"
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

If an Object is passed it will be a key/value pair of CSS attributes to be applied to the current td cell.

Example: 

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // list of key/value css attributes
          style: {
            "color": "#a4b1c5",
            "font-style": "italic"
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

headerStyle: String/Object
If a String is passed it will be used the CSS class or classes (separated by a space) to attach to the current th cell.

Example:

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // list of CSS classes separated by a space
          headerStyle: "class-name-1 class-name-2 class-name-3"
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

If an Object is passed it will be a key/value pair of CSS attributes to be applied to the current th cell.

Example: 

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // list of key/value css attributes
          headerStyle: {
            "color": "#a4b1c5",
            "font-style": "italic"
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

customAttributes: Object
Object with key/value pairs of custom attributes you wish to add to the tr cell when rendered.

Example:

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // object with key/value attributes
          customAttributes: {
            "align" : "right"
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

customHeaderAttributes: Object
Object with key/value pairs of custom attributes you wish to add to the th cell when rendered.

Example:

      // Define a data source
      var gridData = [/* data */];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Name",
          field: "name",

          // object with key/value attributes
          customHeaderAttributes: {
            "valign":"bottom"
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

labelFunction: function (rowData, columnDefinition)
This function lets you process the text that will be rendered into your cells, you may use this function to do any specific processing of the data before it is passed to the cell renderer.

For further reading on this option check out the description at theBasic itemrenderer widget post.

Example:

      // Define a data source
      var gridData = [{price:"123.56"}, {price:"2453.99"}];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Price",
          field: "price",

          // apply formatting of your text passed to each cell
          labelFunction: function (rowData, columnDefinition)) {
            return "$" + rowData.price;
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);

rendererFunction: function(cell, listData)
Function that will be executed on each iteration of the column. For more information on the parameters passed to this function checkout the description given on Basic itemrenderer widget about this function.

Example:

      // Define a data source
      var gridData = [{email:"some1@email.com"}, {email:"some2@email.com"}];

      // Define the grid's options
      var gridOptions = {
        columns: [
        {
          label: "Email",
          field: "email",

          // execute on each iteration of the cell when being rendered
          rendererFunction: function(cell, listData) {
            $('<a href="mailto:' + listData.data + '">' +  listData.data + '</a>').appendTo(cell);
          }
        }
        ]
      };

      $(".selector").grid( gridOptions );
      $(".selector").grid("option", "dataProvider", gridData);


itemRenderer: string
For information on how to use this option please read the section Example 6: itemRenderer at theBasic itemrenderer widget post.

Tags:
Categories: jQuery•Widget
Permalink