jui_datagrid docs

jui_datagrid is an Ajax-enabled jQuery plugin, useful to manipulate database data in tabular format.

Fully customizable, simple yet powerful API, jQuery themes compatible, localization support. It has a modular design, so it is using jui_pagination plugin for paging and jui_filter_rules plugin for searching.

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 jui_datagrid class is available, supporting: "MYSQLi", "MYSQL_PDO", "MYSQL", "POSTGRES", "ADODB". (ADODB drivers tested: mysqli, pdo_mysql, mysqlt, mysql, postgres).

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

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

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

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

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

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

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

NuGet GALLERY: https://nuget.org/packages/jui_datagrid/

Copyright © Christos Pontikis http://pontikis.net

License MIT

Requires

Tested with jquery >= 1.8.2 and >= jquery-ui 1.8.23 (recommended jquery-ui >= 1.9)

Current Release 0.9.1 (18 Oct 2013) Download here.

CHANGELOG here.

View jui_datagrid References.

Features

  • Display tabular data
  • CSS based themes compatible with jQuery-UI Theming
  • Multiple instances
  • Get data in JSON format using AJAX (any server-side technology)
  • Change columns order
  • Show/hide columns
  • Style columns
  • Flexible data sorting
  • Single or multi-select rows
  • Powerful pagination
  • Powerful filters
  • Column value conversion using javascript (or server side) function
  • Preferences dialog available to user
  • Debug mode available
  • Localization

Usage

HTML (head section)

<link rel="stylesheet" type="text/css" href="/path/to/jqueryui_theme/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="/path/to/jquery-ui-timepicker-addon.min.css"/>

<link rel="stylesheet" type="text/css" href="/path/to/jquery.jui_dropdown.css">
<link rel="stylesheet" type="text/css" href="/path/to/jquery.jui_pagination.css">
<link rel="stylesheet" type="text/css" href="/path/to/jquery.jui_filter_rules.css">
<link rel="stylesheet" type="text/css" href="/path/to/jquery.jui_datagrid.css">

<!--  if custom classes used -->
<link rel="stylesheet" type="text/css" href="/path/to/custom.css">

<script type="text/javascript" src="/path/to/bowser.js"></script>
<script type="text/javascript" src="/path/to/moment.js"></script>
<script type="text/javascript" src="/path/to/jquery.js"></script>
<script type="text/javascript" src="/path/to/jquery-ui.js"></script>
<script type="text/javascript" src="/path/to/jquery-ui-timepicker-addon.js"></script>

<!--  if touch event support for touch devices is needed (see folder /lib) -->
<script type="text/javascript" src="/path/to/jquery.ui.touch-punch.min.js"></script>

<script type="text/javascript" src="/path/to/jquery.jui_dropdown.min.js"></script>

<script type="text/javascript" src="/path/to/jquery.jui_pagination.min.js"></script>
<script type="text/javascript" src="/path/to/jui_pagination/localization/en.js"></script>

<script type="text/javascript" src="/path/to/jquery.jui_filter_rules.min.js"></script>
<script type="text/javascript" src="/path/to/jui_filter_rules/localization/en.js"></script>

<script type="text/javascript" src="/path/to/jquery.jui_datagrid.min.js"></script>
<script type="text/javascript" src="/path/to/jui_datagrid/localization/en.js"></script>

JS code

    $("#element_id").jui_datagrid({
        ajaxFetchDataURL: 'ajax/ajax_fetch_data1.php',
        caption: 'Customers',

        columns: [
            {field: "customer_id", visible: "no", "header": 'Code', "headerClass": "th_code", "dataClass": "td_code"},
            {field: "lastname", visible: "yes", "header": 'Lastname', "headerClass": "th_lastname", "dataClass": "td_lastname"},
            {field: "firstname", visible: "yes", "header": 'Firstname', "headerClass": "th_firstname", "dataClass": "td_firstname"},
            {field: "email", visible: "yes", "header": 'Email', "headerClass": "th_email", "dataClass": "td_email"},
            {field: "gender", visible: "yes", "header": 'Gender', "headerClass": "th_gender", "dataClass": "td_gender"}
        ],

        sorting: [
            {"sortingName": "Code", field: "customer_id", order: "none"},
            {"sortingName": "Lastname", field: "lastname", order: "ascending"},
            {"sortingName": "Firstname", field: "firstname", order: "ascending"}
        ],

        ajaxFetchDataURL: 'ajax/ajax_fetch_data1.php',

        containerClass: 'grid1_container ui-state-default ui-corner-all',
        datagridClass: 'grid1_data ui-widget-content',

        autoSetColumnsWidth: false,

        paginationOptions: {
            sliderAnimation: false
        }

        onDelete: function() {
            var a_sel = $(this).jui_datagrid("getSelectedIDs"),
                sel = a_sel.length;
            if(sel == 0) {
                log = 'Nothing selected...';
                create_log(elem_dlg_log1, log);
            } else {
                log = sel + ' Row(s) with ID: ' + a_sel + ' will be deleted.';
                create_log(elem_dlg_log1, log);
            }
        },
        onCellClick: function(event, data) {
            log = 'Click on cell: col ' + data.col + ' row ' + data.row + '.';
            create_log(elem_dlg_log1, log);
        },
        onRowClick: function(event, data) {
            log = 'Row with ID ' + data.row_id + ' ' + data.row_status + '.';
            create_log(elem_dlg_log1, log);
        },
        onDisplay: function() {
            log = 'Datagrid created.';
            create_log(elem_dlg_log1, log);
        }

    });
    

JSON data 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"
            },
            ...
        ]
    }
    

User functions (column value conversion)

Use can set custom functions for column value conversion either javascript or server side functions.

Arguments can be passed as an array of objects. Each argument object can contain:

  • a direct value: {"value": "DD/MM/YYYY"}
  • or the value of a column, providing the column index: {"col_index": 5}

So, any column value can become 'argument' for conversion functions.

Example of javascript user function

        columns: [
            {field: "customer_id", visible: "no", "header": 'Code', "headerClass": "th_code", "dataClass": "td_code"},
            {field: "lastname", visible: "yes", "header": 'Lastname', "headerClass": "th_lastname", "dataClass": "td_lastname"},
            {field: "firstname", visible: "yes", "header": 'Firstname', "headerClass": "th_firstname", "dataClass": "td_firstname"},
            {field: "date_of_birth", visible: "yes", "header": 'Date of birth', "headerClass": "th_date_of_birth", "dataClass": "th_date_of_birth",
                column_value_conversion: {
                    function_name: "date_decode",
                    args: [
                        {"col_index": 3},
                        {"value": "DD/MM/YYYY"}
                    ]
                }
            }
        ]
        

Example of server-side user function

        columns: [
            {field: "customer_id", visible: "no", "header": 'Code', "headerClass": "th_code", "dataClass": "td_code"},
            {field: "lastname", visible: "yes", "header": 'Lastname', "headerClass": "th_lastname", "dataClass": "td_lastname"},
            {field: "date_updated", visible: "yes", "header": 'Date updated', "headerClass": "th_date_updated", "dataClass": "th_date_updated",
                column_value_conversion_server_side: {
                    function_name: "UTC_timestamp_to_local_datetime",
                    args: [
                        {"col_index": 2},
                        {"value": "Europe/Athens"},
                        {"value": "d/m/Y H:m:s"}
                    ]
                }
            }
        ]
        

Structure

Options

    $("#element_id").jui_datagrid({
        ajaxFetchDataURL: 'some_server_url', // REQUIRED
        caption: 'Your title here'  // OPTIONAL

        // DEFAULTS
        columns: [
            {field: "", visible: "no", "header": '', "headerClass": "", "dataClass": ""}
        ],

        sorting: [
            {"sortingName": "", field: "", order: "none"}
        ],

        filterOptions: {
            filters: []
        }, // 'onValidationError' will be ignored

        pageNum: 1,
        rowsPerPage: 10,
        maxRowsPerPage: 100,

        row_primary_key: '',
        rowSelectionMode: 'multiple', // 'multiple', 'single', 'false'

        autoSetColumnsWidth: true,
        showRowNumbers: false,
        showSortingIndicator: true,

        // toolbar options
        showPrefButton: true,
        showSelectButtons: true,
        showRefreshButton: true,
        showDeleteButton: true,
        showPrintButton: true,
        showExportButton: true,
        showSortingButton: true,
        showFiltersButton: true,
        showPrefButtonText: false,
        showRefreshButtonText: false,
        showDeleteButtonText: false,
        showPrintButtonText: false,
        showExportButtonText: false,
        showSortingButtonText: false,
        showFiltersButtonText: false,

        // select dropdown options
        dropdownSelectOptions: {
            menuClass: 'dropdown_select_menu',
            launcherClass: 'dropdown_select_launcher'
        }, // 'launcher_id', 'launcher_container_id', 'menu_id', 'onSelect' will be ignored

        // pagination options
        usePagination: true,
        paginationOptions: {
            visiblePageLinks: 5,
            useSlider: true,
            showGoToPage: false,
            showRowsPerPage: true,
            showRowsInfo: true,
            showPreferences: false,
            disableSelectionNavPane: true
        }, // 'currentPage', 'rowsPerPage', 'totalPages', 'containerClass', 'onSetRowsPerPage', 'onChangePage', 'onDisplay' will be ignored

        // main divs classes
        containerClass: 'grid_container ui-state-default ui-corner-all',
        captionClass: 'grid_caption ui-widget-header ui-corner-top',
        datagridHeaderClass: 'grid_header ui-state-default',
        datagridClass: 'grid_data ui-widget-content',
        noResultsClass: "no_records_found",
        toolsClass: 'grid_tools ui-state-default ui-corner-all',
        paginationClass: 'grid_pagination',

        // data table classes
        headerTableClass: 'grid_header_table',
        dataTableClass: 'grid_data_table',
        trHoverTrClass: '',
        trHoverTdClass: 'ui-state-hover',
        thClass: 'grid_th_common ui-state-default',
        tdClass: 'grid_td_common ui-widget-content',
        thRowNumberClass: 'grid_th_common grid_th_row_number ui-state-default',
        tdRowNumberClass: 'grid_td_common grid_td_row_number ui-widget-content',

        rowIndexHeaderClass: '',
        rowIndexClass: '',

        selectedTrTrClass: '',
        selectedTrTdClass: 'ui-state-highlight',

        //toolbar classes
        tbButtonContainer: 'tbBtnContainer',
        tbPrefIconClass: 'ui-icon-gear',
        tbRefreshIconClass: 'ui-icon-refresh',
        tbDeleteIconClass: 'ui-icon-trash',
        tbPrintIconClass: 'ui-icon-print',
        tbExportIconClass: 'ui-icon-extlink',
        tbSortingIconClass: 'ui-icon ui-icon-carat-2-n-s',
        tbFiltersIconClass: 'ui-icon-search',

        //sortable list classes
        sortableListClass: 'grid_sortable_list',
        sortableListLiClass: 'ui-state-default grid_sortable_list_li',
        sortableListLiDisabledClass: 'ui-state-disabled',
        sortableListLiIconClass: 'ui-icon ui-icon-arrowthick-2-n-s grid_sortable_list_li_icon',

        // common list
        commonListClass: 'grid_common_list',

        // dialog Preferences
        dlgPrefClass: 'dlg_pref',
        dlgPrefButtonClass: 'dlg_pref_button',

        // dialog Sorting
        dlgSortClass: 'dlg_sort',
        dlgSortButtonClass: 'dlg_sort_button',

        // dialog Filters
        dlgFiltersClass: 'dlg_filters',
        dlgFiltersButtonClass: 'dlg_filters_button',

        // elements id prefix
        caption_id_prefix: 'caption_',
        datagrid_header_id_prefix: 'dgh_',
        datagrid_id_prefix: 'dg_',
        table_id_prefix: 'tbl_',
        header_table_id_prefix: 'tblh_',
        tools_id_prefix: 'tools_',
        pagination_id_prefix: 'pag_',

        pref_dialog_id_prefix: 'pref_dlg_',
        pref_tabs_id_prefix: 'pref_tabs_',

        //column order list prefix
        col_order_list_id_prefix: 'col_order_',
        col_visible_chk_id_prefix: 'col_visible_',

        sort_dialog_id_prefix: 'sort_dlg_',

        filters_dialog_id_prefix: 'filter_dlg_',
        filter_rules_id_prefix: 'flt_rules_',

        //sorting list prefix
        sorting_list_id_prefix: 'sort_criteria_',
        sort_radio_name_prefix: 'sort_order_',
        sort_asc_radio_id_prefix: 'sort_asc_',
        sort_desc_radio_id_prefix: 'sort_desc_',
        sort_none_radio_id_prefix: 'sort_none_',

        fix_border_collapse_td_width: 1, // FF, MSIE >= 10 seems to return correct computed td width while Chrome <=23, MSIE <=9 and Opera one pixel less

        debug_mode: "no",

        onCellClick: function() {
        },
        onRowClick: function() {
        },
        onDelete: function() {
        },
        onDatagridError: function() {
        },
        onDebug: function() {
        },
        onChangeSelectedRows: function() {
        }
        onDisplay: function() {
        }
    });
    

Methods

getDefaults

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

getOption

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

getAllOptions

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

setOption

    $("#element_id").jui_datagrid('setOption', 'option_name', option_value, reinit);
    
    $("#element_id").jui_datagrid({option1_name: option1_value, etc});
    

refresh

    $("#element_id").jui_datagrid('refresh');
    

destroy

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

getSelectedIDs

    $("#element_id").jui_datagrid('getSelectedIDs');
    

getGridElemTableID

    $("#element_id").jui_datagrid('getGridElemTableID');
    

getGridElemHeaderTableID

    $("#element_id").jui_datagrid('getGridElemHeaderTableID');
    

setPageColClass

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

removePageColClass

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

Set Pagination Options

    $("#element_id").jui_datagrid({
        paginationOptions: {
            // options here
        }
    });
    

getPaginationOption

    $("#element_id").jui_datagrid('getPaginationOption', 'option_name');
    

getAllPaginationOptions

    $("#element_id").jui_datagrid('getAllPaginationOptions');
    

getDropdownLauncherID

    $("#element_id").jui_datagrid('getDropdownLauncherID');
    

Events

onCellClick

    $("#element_id").jui_datagrid({
        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").jui_datagrid({
        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', 'clicked', undefined).

onDelete

    $("#element_id").jui_datagrid({
        onDelete: function() {
            // your code here e.g.
            var a_sel = $(this).jui_datagrid("getSelectedIDs"),
                sel = a_sel.length;
            if(sel == 0) {
                console.log('Nothing selected...');
            } else {
                console.log(sel + ' Row(s) with ID: ' + a_sel + ' will be deleted.');
            }
        }
    });
    

onDatagidError

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

data is an object:

    {
        err_code: 'err_code',
        err_description: 'description',
        elem_filter: 'the filter element as jquery object' // availbale only on Filter validation errors
    }
    

onDebug

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

data is an object:

    {
        debug_message: 'err_code'
    }
    

onChangeSelectedRows

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

onDisplay

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