Bootstrap Datagrid docs

Bootstrap Datagrid (bs_grid) is a jQuery datagrid plugin, based on Twitter Bootstrap.

Code structure according to official jQuery plugin authoring guide.

Created for Bootstrap 3, but it is also compatible with Bootstrap 2 (bootstrap_version option)

Fully customizable, simple yet powerful API, localization support. It has a modular design, so it uses:

As a javascript control, it can be integrated with any server-side technology (e.g. PHP, Perl, ASP, JSP and more) and any Database.

A helper PHP bs_grid class is available, supporting: "MYSQLi" and "POSTGRES".

Compatible with modern web browsers. Tested with: Google Chrome, Mozilla Firefox, Microsoft Internet Explorer >= 8, Android browser.

PROJECT HOME: http://pontikis.net/labs/bs_grid

DEMO: http://pontikis.net/labs/bs_grid/demo

DOCUMENTATION: http://pontikis.net/labs/bs_grid/docs

SUPPORT FORUM: http://pontikis.net/bbs

SOURCE REPOSITORY: https://github.com/pontikis/bs_grid

JQUERY PLUGIN REGISTRY: http://plugins.jquery.com/bs_grid/

Copyright © Christos Pontikis http://pontikis.net

License MIT

Requires

Optional

Current Release 0.9.2 (28 May 2014) Download here.

CHANGELOG here.

Features

  • Created for Bootstrap 3 (Bootstrap 2 supported)
  • Responsive web design
  • Fully configurable
  • Get data in JSON format using AJAX (any server-side technology)
  • A php class is provided for server side operations
  • Change columns order
  • Show/hide columns
  • Style columns
  • Simple column sorting with a click
  • Flexible data sorting (multi-column)
  • Single or multiple row selection
  • Powerful pagination
  • Powerful filters (Query builder)
  • Multiple instances in same page
  • Localization

How to use bs_grid

  1. Include bs_grid css, js and localization file in head section of your page. The same for bs_pagination and jui_filter_rules plugins. See code examples.
  2. Create a div in your page, where you want bs_grid to render and give it an ID (e.g. mygrid )
  3. In your javascript code, add
    $("#mygrid").bs_grid({
    	// your options here - see below or code examples
    })
    
  4. Create the ajax call, which your grid will use to fetch page data. This must return JSON code, using the following structure
    {
    	"total_rows": "200",
    	"page_data": [
    		{
    			"id": "111",
    			"lastname": "Diaz",
    			"firstname": "Kai",
    			"email": "odio.Aliquam@Phasellus.org",
    			"gender": "female"
    		},
    		{
    			"id": "112",
    			"lastname": "Snider",
    			"firstname": "Nelle",
    			"email": "vulputate@nonlobortis.org",
    			"gender": "female"
    		},
    		...
    	]
    }
    

    You may use any server-side technology to create this ajax script. A PHP class is provided (bs_grid.php). It uses Da Capo database wrapper, which you can get from Github.

Options

$("#element_id").bs_grid({
	pageNum: 1,
	rowsPerPage: 10,
	maxRowsPerPage: 100,
	row_primary_key: "",
	rowSelectionMode: "single", // "multiple", "single", false
	selected_ids: [],

	/**
	 * MANDATORY PROPERTIES: field
	 * UNIQUE PROPERTIES: field
	 * {field: "customer_id", header: "Code", visible: "no", is_function: "no", "headerClass": "th_code hidden-xs", "dataClass": "td_code hidden-xs"},
	 */
	columns: [],

	/**
	 * MANDATORY PROPERTIES: field, order
	 * UNIQUE PROPERTIES: field
	 * order is one of "ascending", "descending", "none"
	 * {sortingName: "Code", field: "customer_id", order: "none"},
	 */
	sorting: [],

	/**
	 * See bs_pagination plugin documentation
	 */
	paginationOptions: {
		containerClass: "well pagination-container",
		visiblePageLinks: 5,
		showGoToPage: true,
		showRowsPerPage: true,
		showRowsInfo: true,
		showRowsDefaultInfo: true,
		disableTextSelectionInNavPane: true
	}, // "currentPage", "rowsPerPage", "maxRowsPerPage", "totalPages", "totalRows", "bootstrap_version", "onChangePage" will be ignored

	/**
	 * See jui_filter_rules plugin documentation
	 */
	filterOptions: {
		filters: [],
		filter_rules: []
    }, // "bootstrap_version", "onSetRules", "onValidationError" will be ignored

	useFilters: true,
	showRowNumbers: false,
	showSortingIndicator: true,
	useSortableLists: true,
	customHTMLelementID1: "",
	customHTMLelementID2: "",

	/* STYLES ----------------------------------------------------*/
	bootstrap_version: "3",

	// bs 3
	containerClass: "grid_container",
	noResultsClass: "alert alert-warning no-records-found",

	toolsClass: "tools",

	columnsListLaunchButtonClass: "btn btn-default dropdown-toggle",
	columnsListLaunchButtonIconClass: "glyphicon glyphicon-th",
	columnsListClass: "dropdown-menu dropdown-menu-right",
	columnsListLabelClass: "columns-label",
	columnsListCheckClass: "col-checkbox",
	columnsListDividerClass: "divider",
	columnsListDefaultButtonClass: "btn btn-primary btn-xs btn-block",

	sortingListLaunchButtonIconClass: "glyphicon glyphicon-sort",
	sortingLabelCheckboxClass: "radio-inline",
	sortingNameClass: "sorting-name",

	selectButtonIconClass: "glyphicon  glyphicon-check",
	selectedRowsClass: "selected-rows",

	filterToggleButtonIconClass: "glyphicon glyphicon-filter",
	filterToggleActiveClass: "btn-info",

	sortingIndicatorAscClass: "glyphicon glyphicon-chevron-up text-muted",
	sortingIndicatorDescClass: "glyphicon glyphicon-chevron-down text-muted",

	dataTableContainerClass: "table-responsive",
	dataTableClass: "table table-bordered table-hover",
	commonThClass: "th-common",
	selectedTrClass: "warning",

	filterContainerClass: "well filters-container",
	filterToolsClass: "",
	filterApplyBtnClass: "btn btn-primary btn-sm filters-button",
	filterResetBtnClass: "btn btn-default btn-sm filters-button",

	// prefixes
	tools_id_prefix: "tools_",
	columns_list_id_prefix: "columns_list_",
	sorting_list_id_prefix: "sorting_list_",
	sorting_radio_name_prefix: "sort_radio_",
	selected_rows_id_prefix: "selected_rows_",
	selection_list_id_prefix: "selection_list_",
	filter_toggle_id_prefix: "filter_toggle_",

	table_container_id_prefix: "tbl_container_",
	table_id_prefix: "tbl_",

	no_results_id_prefix: "no_res_",

	custom_html1_id_prefix: "custom1_",
	custom_html2_id_prefix: "custom2_",

	pagination_id_prefix: "pag_",
	filter_container_id_prefix: "flt_container_",
	filter_rules_id_prefix: "flt_rules_",
	filter_tools_id_prefix: "flt_tools_",

	// misc
	debug_mode: "no",

	// events
	onCellClick: function() {
	},
	onRowClick: function() {
	},
	onDatagridError: function() {
	},
	onDebug: function() {
	},
	onDisplay: function() {
	}
});

Methods

getVersion

var version = $("#element_id").bs_grid('getVersion');

getDefaults

$("#element_id").bs_grid('getDefaults');

getOption

$("#element_id").bs_grid('getOption', 'option_name');

getAllOptions

$("#element_id").bs_grid('getAllOptions');

destroy

$("#element_id").bs_grid('destroy');

selectedRows

Get selected IDs

$("#element_id").bs_grid('selectedRows', 'get_ids');

Clear selected IDs

$("#element_id").bs_grid('selectedRows', 'clear_all_ids');

Update selected IDs counter

$("#element_id").bs_grid('selectedRows', 'update_counter');

Get row selected index

$("#element_id").bs_grid('selectedRows', 'selected_index', row_id);

Add row to selected rows

$("#element_id").bs_grid('selectedRows', 'add_id', row_id);

Remove row from selected rows

$("#element_id").bs_grid('selectedRows', 'remove_id', row_index_in_selected_ids);

Mark row as selected

$("#element_id").bs_grid('selectedRows', 'mark_selected', row_id);

Mark row as deselected

$("#element_id").bs_grid('selectedRows', 'mark_deselected', row_id);

Mark page as selected

$("#element_id").bs_grid('selectedRows', 'mark_page_selected');

Mark page as deselected

$("#element_id").bs_grid('selectedRows', 'mark_page_deselected');

Mark page as inversed

$("#element_id").bs_grid('selectedRows', 'mark_page_inversed');

setPageColClass

$("#element_id").bs_grid('setPageColClass', col_index, headerClass, dataClass);

removePageColClass

$("#element_id").bs_grid('setPageColClass', col_index, headerClass, dataClass);

displayGrid

$("#element_id").bs_grid('displayGrid', refresh_pagination);

Using this method, you can refresh Grid after an external change.

takeSnapshot

var options = $("#element_id").bs_grid('takeSnapshot');

Get current daragrid status (row selections, current page, filters, columns to display etc).

restoreSnapshot

$("#element_id").bs_grid('restoreSnapshot', options);

Restore datagrid status from previous taken snapshot.

Events

onCellClick

$("#element_id").bs_grid({
	onCellClick: function(event, data) {
		// your code here e.g.
		console.log('Click on cell: col ' + data.col + ' row ' + data.row + '.');
	}
});

data is an object with properties: col and row (the index of the column and row).

onRowClick

$("#element_id").bs_grid({
	onRowClick: function(event, data) {
		// your code here e.g.
		console.log('Row with ID ' + data.row_id + ' ' + data.row_status + '.');
	}
});

data is an object with properties: row_id and row_status ('selected', 'deselected').

onDatagidError

$("#element_id").bs_grid({
	onDatagridError: function(event, data) {
		alert(data["err_description"] + ' (' + data["err_code"] + ')');
	}
});

onDebug

$("#element_id").bs_grid({
	onDebug: function(event, data) {
	// your code here
	}
});

onDisplay

$("#element_id").bs_grid({
	onDisplay: function() {
	// your code here
	}
});