Powerful Data Grid Plugin For Bootstrap - jQuery Bootgrid

Powerful Data Grid Plugin For Bootstrap - jQuery Bootgrid
File Size: 130 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

Bootgrid is a lightweight yet flexible, powerful jQuery plugin used to render a dynamic, AJAX enabled, highly customizable data grid for Bootstrap pages.

More features:

  • Header/footer navigation.
  • Row selections with multiple select support.
  • Table sorting.
  • Searchable & live filtering.
  • Built-in data converters and formatters.
  • Useful API methods and events.
  • Supports both client-side and server-side population.
  • And much more...

Basic usage:

1. Insert the necessary jQuery library and Bootstrap framework into the web page.

<link rel="stylesheet" href="/path/to/bootstrap.min.css">
<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/bootstrap.min.js"></script>

2. Download and insert the jQuery Bootgrid's files into the page.

<link href="/dist/jquery.bootgrid.css" rel="stylesheet">
<script src="/dist/jquery.bootgrid.js"></script>

3. Just add the data-toggle="bootgrid" attribute to your html table and the plugin will take care of the rest.

<table id="grid" 
       class="table table-condensed table-hover table-striped"
       data-toggle="bootgrid">
  <thead>
    <tr>
      <th data-column-id="id" data-identifier="true" data-type="numeric">ID</th>
      <th data-column-id="sender" data-order="asc">Sender</th>
      ...
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>1</td>
      <td>[email protected]</td>
    </tr>
    ...
  </tbody>
</table>

3. To initialize the data grid manually:

$("#grid").bootgrid();

4. Available options. Note that the following options also can be passed via data-OPTIONNAME in the table elements.

$("#grid").bootgrid({

  // it's a flag: 0 = none, 1 = top, 2 = bottom, 3 = both (top and bottom)
  navigation: 3, 

  // page padding (pagination)
  padding: 2, 

  // enable column selection
  columnSelection: true,

  // rows per page int or array of int (-1 represents "All")
  rowCount: [10, 25, 50, -1], 

  /**
   * Enables row selection (to enable multi selection see also `multiSelect`). Default value is `false`.
   *
   * @property selection
   * @type Boolean
   * @default false
   * @for defaults
   * @since 1.0.0
   **/
  selection: false,

  /**
   * Enables multi selection (`selection` must be set to `true` as well). Default value is `false`.
   *
   * @property multiSelect
   * @type Boolean
   * @default false
   * @for defaults
   * @since 1.0.0
   **/
  multiSelect: false,

  /**
   * Enables entire row click selection (`selection` must be set to `true` as well). Default value is `false`.
   *
   * @property rowSelect
   * @type Boolean
   * @default false
   * @for defaults
   * @since 1.1.0
   **/
  rowSelect: false,

  /**
   * Defines whether the row selection is saved internally on filtering, paging and sorting
   * (even if the selected rows are not visible).
   *
   * @property keepSelection
   * @type Boolean
   * @default false
   * @for defaults
   * @since 1.1.0
   **/
  keepSelection: false,

  // highlights new rows (find the page of the first new row)
  highlightRows: false, 

  // enable table sorting
  sorting: true,
  multiSort: false,

  /**
   * General search settings to configure the search field behaviour.
   *
   * @property searchSettings
   * @type Object
   * @for defaults
   * @since 1.2.0
   **/
  searchSettings: {
      /**
       * The time in milliseconds to wait before search gets executed.
       *
       * @property delay
       * @type Number
       * @default 250
       * @for searchSettings
       **/
      delay: 250,
      
      /**
       * The characters to type before the search gets executed.
       *
       * @property characters
       * @type Number
       * @default 1
       * @for searchSettings
       **/
      characters: 1
  },

  /**
   * Defines whether the data shall be loaded via an asynchronous HTTP (Ajax) request.
   *
   * @property ajax
   * @type Boolean
   * @default false
   * @for defaults
   **/
  ajax: false,

  /**
   * Ajax request settings that shall be used for server-side communication.
   * All setting except data, error, success and url can be overridden.
   * For the full list of settings go to http://api.jquery.com/jQuery.ajax/.
   *
   * @property ajaxSettings
   * @type Object
   * @for defaults
   * @since 1.2.0
   **/
  ajaxSettings: {
      /**
       * Specifies the HTTP method which shall be used when sending data to the server.
       * Go to http://api.jquery.com/jQuery.ajax/ for more details.
       * This setting is overriden for backward compatibility.
       *
       * @property method
       * @type String
       * @default "POST"
       * @for ajaxSettings
       **/
      method: "POST"
  },

  /**
   * Enriches the request object with additional properties. Either a `PlainObject` or a `Function`
   * that returns a `PlainObject` can be passed. Default value is `{}`.
   *
   * @property post
   * @type Object|Function
   * @default function (request) { return request; }
   * @for defaults
   * @deprecated Use instead `requestHandler`
   **/
  post: {}, // or use function () { return {}; } (reserved properties are "current", "rowCount", "sort" and "searchPhrase")

  /**
   * Sets the data URL to a data service (e.g. a REST service). Either a `String` or a `Function`
   * that returns a `String` can be passed. Default value is `""`.
   *
   * @property url
   * @type String|Function
   * @default ""
   * @for defaults
   **/
  url: "", // or use function () { return ""; }

  /**
   * Defines whether the search is case sensitive or insensitive.
   *
   * @property caseSensitive
   * @type Boolean
   * @default true
   * @for defaults
   * @since 1.1.0
   **/
  caseSensitive: true,

  // note: The following properties should not be used via data-api attributes

  /**
   * Transforms the JSON request object in what ever is needed on the server-side implementation.
   *
   * @property requestHandler
   * @type Function
   * @default function (request) { return request; }
   * @for defaults
   * @since 1.1.0
   **/
  requestHandler: function (request) { return request; },

  /**
   * Transforms the response object into the expected JSON response object.
   *
   * @property responseHandler
   * @type Function
   * @default function (response) { return response; }
   * @for defaults
   * @since 1.1.0
   **/
  responseHandler: function (response) { return response; },

  /**
   * A list of converters.
   *
   * @property converters
   * @type Object
   * @for defaults
   * @since 1.0.0
   **/
  converters: {
      numeric: {
          from: function (value) { return +value; }, // converts from string to numeric
          to: function (value) { return value + ""; } // converts from numeric to string
      },
      string: {
          // default converter
          from: function (value) { return value; },
          to: function (value) { return value; }
      }
  },

  /**
   * Contains all css classes.
   *
   * @property css
   * @type Object
   * @for defaults
   **/
  css: {
      actions: "actions btn-group", // must be a unique class name or constellation of class names within the header and footer
      center: "text-center",
      columnHeaderAnchor: "column-header-anchor", // must be a unique class name or constellation of class names within the column header cell
      columnHeaderText: "text",
      dropDownItem: "dropdown-item", // must be a unique class name or constellation of class names within the actionDropDown,
      dropDownItemButton: "dropdown-item-button", // must be a unique class name or constellation of class names within the actionDropDown
      dropDownItemCheckbox: "dropdown-item-checkbox", // must be a unique class name or constellation of class names within the actionDropDown
      dropDownMenu: "dropdown btn-group", // must be a unique class name or constellation of class names within the actionDropDown
      dropDownMenuItems: "dropdown-menu pull-right", // must be a unique class name or constellation of class names within the actionDropDown
      dropDownMenuText: "dropdown-text", // must be a unique class name or constellation of class names within the actionDropDown
      footer: "bootgrid-footer container-fluid",
      header: "bootgrid-header container-fluid",
      icon: "icon glyphicon",
      iconColumns: "glyphicon-th-list",
      iconDown: "glyphicon-chevron-down",
      iconRefresh: "glyphicon-refresh",
      iconSearch: "glyphicon-search",
      iconUp: "glyphicon-chevron-up",
      infos: "infos", // must be a unique class name or constellation of class names within the header and footer,
      left: "text-left",
      pagination: "pagination", // must be a unique class name or constellation of class names within the header and footer
      paginationButton: "button", // must be a unique class name or constellation of class names within the pagination

      /**
       * CSS class to select the parent div which activates responsive mode.
       *
       * @property responsiveTable
       * @type String
       * @default "table-responsive"
       * @for css
       * @since 1.1.0
       **/
      responsiveTable: "table-responsive",

      right: "text-right",
      search: "search form-group", // must be a unique class name or constellation of class names within the header and footer
      searchField: "search-field form-control",
      selectBox: "select-box", // must be a unique class name or constellation of class names within the entire table
      selectCell: "select-cell", // must be a unique class name or constellation of class names within the entire table

      /**
       * CSS class to highlight selected rows.
       *
       * @property selected
       * @type String
       * @default "active"
       * @for css
       * @since 1.1.0
       **/
      selected: "active",

      sortable: "sortable",
      table: "bootgrid-table table"
  },

  /**
   * A dictionary of formatters.
   *
   * @property formatters
   * @type Object
   * @for defaults
   * @since 1.0.0
   **/
  formatters: {},

  /**
   * Contains all labels.
   *
   * @property labels
   * @type Object
   * @for defaults
   **/
  labels: {
      all: "All",
      infos: "Showing {{ctx.start}} to {{ctx.end}} of {{ctx.total}} entries",
      loading: "Loading...",
      noResults: "No results found!",
      refresh: "Refresh",
      search: "Search"
  },

  /**
   * Specifies the mapping between status and contextual classes to color rows.
   *
   * @property statusMapping
   * @type Object
   * @for defaults
   * @since 1.2.0
   **/
  statusMapping: {
      /**
       * Specifies a successful or positive action.
       *
       * @property 0
       * @type String
       * @for statusMapping
       **/
      0: "success",

      /**
       * Specifies a neutral informative change or action.
       *
       * @property 1
       * @type String
       * @for statusMapping
       **/
      1: "info",

      /**
       * Specifies a warning that might need attention.
       *
       * @property 2
       * @type String
       * @for statusMapping
       **/
      2: "warning",
      
      /**
       * Specifies a dangerous or potentially negative action.
       *
       * @property 3
       * @type String
       * @for statusMapping
       **/
      3: "danger"
  },

  /**
   * Contains all templates.
   *
   * @property templates
   * @type Object
   * @for defaults
   **/
  templates: {
      actionButton: "<button class=\"btn btn-default\" type=\"button\" title=\"{{ctx.text}}\">{{ctx.content}}</button>",
      actionDropDown: "<div class=\"{{css.dropDownMenu}}\"><button class=\"btn btn-default dropdown-toggle\" type=\"button\" data-toggle=\"dropdown\"><span class=\"{{css.dropDownMenuText}}\">{{ctx.content}}</span> <span class=\"caret\"></span></button><ul class=\"{{css.dropDownMenuItems}}\" role=\"menu\"></ul></div>",
      actionDropDownItem: "<li><a data-action=\"{{ctx.action}}\" class=\"{{css.dropDownItem}} {{css.dropDownItemButton}}\">{{ctx.text}}</a></li>",
      actionDropDownCheckboxItem: "<li><label class=\"{{css.dropDownItem}}\"><input name=\"{{ctx.name}}\" type=\"checkbox\" value=\"1\" class=\"{{css.dropDownItemCheckbox}}\" {{ctx.checked}} /> {{ctx.label}}</label></li>",
      actions: "<div class=\"{{css.actions}}\"></div>",
      body: "<tbody></tbody>",
      cell: "<td class=\"{{ctx.css}}\" style=\"{{ctx.style}}\">{{ctx.content}}</td>",
      footer: "<div id=\"{{ctx.id}}\" class=\"{{css.footer}}\"><div class=\"row\"><div class=\"col-sm-6\"><p class=\"{{css.pagination}}\"></p></div><div class=\"col-sm-6 infoBar\"><p class=\"{{css.infos}}\"></p></div></div></div>",
      header: "<div id=\"{{ctx.id}}\" class=\"{{css.header}}\"><div class=\"row\"><div class=\"col-sm-12 actionBar\"><p class=\"{{css.search}}\"></p><p class=\"{{css.actions}}\"></p></div></div></div>",
      headerCell: "<th data-column-id=\"{{ctx.column.id}}\" class=\"{{ctx.css}}\" style=\"{{ctx.style}}\"><a href=\"javascript:void(0);\" class=\"{{css.columnHeaderAnchor}} {{ctx.sortable}}\"><span class=\"{{css.columnHeaderText}}\">{{ctx.column.text}}</span>{{ctx.icon}}</a></th>",
      icon: "<span class=\"{{css.icon}} {{ctx.iconCss}}\"></span>",
      infos: "<div class=\"{{css.infos}}\">{{lbl.infos}}</div>",
      loading: "<tr><td colspan=\"{{ctx.columns}}\" class=\"loading\">{{lbl.loading}}</td></tr>",
      noResults: "<tr><td colspan=\"{{ctx.columns}}\" class=\"no-results\">{{lbl.noResults}}</td></tr>",
      pagination: "<ul class=\"{{css.pagination}}\"></ul>",
      paginationItem: "<li class=\"{{ctx.css}}\"><a data-page=\"{{ctx.page}}\" class=\"{{css.paginationButton}}\">{{ctx.text}}</a></li>",
      rawHeaderCell: "<th class=\"{{ctx.css}}\">{{ctx.content}}</th>", // Used for the multi select box
      row: "<tr{{ctx.attr}}>{{ctx.cells}}</tr>",
      search: "<div class=\"{{css.search}}\"><div class=\"input-group\"><span class=\"{{css.icon}} input-group-addon {{css.iconSearch}}\"></span> <input type=\"text\" class=\"{{css.searchField}}\" placeholder=\"{{lbl.search}}\" /></div></div>",
      select: "<input name=\"select\" type=\"{{ctx.type}}\" class=\"{{css.selectBox}}\" value=\"{{ctx.value}}\" {{ctx.checked}} />"
  }
  
});

5. API.

// adds new rows
$("#grid").bootgrid('append', ROWS);

// selects specific rows
$("#grid").bootgrid('select', IDs);

// deselects selected rows
$("#grid").bootgrid('deselect', IDs);

// removes rows
$("#grid").bootgrid('remove', IDs);

// searches in all visible columns for the given phrase.
// if no argument is passed, it will reset the search. 
$("#grid").bootgrid('search', Phrase);

// sorts rows by the given dictionary. 
// if no argument is passed, it will reset sorting.
$("#grid").bootgrid('sort', dictionary);

// removes all rows
$("#grid").bootgrid('clear');

// reloads data
$("#grid").bootgrid('reload');

// destroy the plugin
$("#grid").bootgrid('destroy');

// gets column settings.
$("#grid").bootgrid('getColumnSettings');

// gets the current page index
$("#grid").bootgrid('getCurrentPage');

// gets the current rows
$("#grid").bootgrid('getCurrentRows');

// gets a number represents the row count per page
$("#grid").bootgrid('getRowCount');

// gets the search phrase
$("#grid").bootgrid('getSearchPhrase');

// gets selected rows
$("#grid").bootgrid('getSelectedRows');

// gets the sort dictionary which represents the state of column sorting
$("#grid").bootgrid('getSortDictionary');

// gets a number represents the total page count
$("#grid").bootgrid('getTotalPageCount');

// gets a number represents the total row count
$("#grid").bootgrid('getTotalRowCount');

6. Events.

$("#grid").bootgrid({
  // options here
})

.on("load.rs.jquery.bootgrid", function (e){
  // ...


.on("loaded.rs.jquery.bootgrid", function (e){
  // ...
});

.on("appended.rs.jquery.bootgrid", function (e, appendedRows){
  // ...
});

.on("cleared.rs.jquery.bootgrid", function (e, affectedRows){
  // ...
});

.on("click.rs.jquery.bootgrid", function (e, columns, row){
  // ...
});

.on("selected.rs.jquery.bootgrid", function (e, selectedRows){
  // ...
});

.on("deselected.rs.jquery.bootgrid", function (e, deselectedRows){
  // ...
});

.on("initialize.rs.jquery.bootgrid", function (e){
  // ...
});

.on("initialized.rs.jquery.bootgrid", function (e, columns, row){
  // ...
});

.on("removed.rs.jquery.bootgrid", function (e, removedRows){
  // ...
});

This awesome jQuery plugin is developed by rstaib. For more Advanced Usages, please check the demo page or visit the official website.