edatatables

Goal of this widget/wrapper is to provide a drop in replacement for base CGridView widget from the Yii framework, using DataTables plugin.

It's usable, but in an early stage and needs some refurbishing. Please post issues on project's page.

Features ¶

• Redrawing of table contents (after paging/sorting/searching) using AJAX calls.
• Using CGridView columns definition format, supports all basic special columns like Buttons, Checkbox, etc.
• Partial editable cells support.
• Custom buttons in table header.
• Smoothness theme from JUI by default

It will be gradually enhanced to support more of DataTables features.

Requirements ¶

Yii 1.1.8 or above.

Changes ¶

0.8.5 ¶

• bootstrap theme, enabled with 'bootstrap' attribute
• fixed setting default sorting, use an array for $sort->defaultOrder
• fixed fixed width of first column when selectableRows is set
• fixed restoring the state from cookie when 'bStateSave' is used

0.8.3 ¶

• fixed styles, by default jquery UI smoothness themeroller style is applied
• fixed some JS code, all should work for now
• by default, left only the refresh button in the toolbar located in the table header
• updated the polish localization files to use » and › html entities, to be used as a template
• started documenting features on the [wiki] (http://code.google.com/p/edatatables/w/list)

0.8.2 ¶

• i18n support
• fixed a but in the getFormattedData method, used to get data for ajax response
• updated DataTables to 1.9.0

Usage ¶

It's not 100% compatible with CGridView. I've decided not to alter the GET parameter names used by DataTables, so you have to use the provided EDTSort and EDTPagination classes as well as alter filter processing. See below.

Installation ¶

Extract into extensions dir.

Import in config/main.php

'import' => array(
  ...
  'ext.EDataTables.*',
  ...

Using ¶

Use similar to CGridView. If displayed in a normal call just run the widget. To fetch AJAX response send json encoded result of $widget->getFormattedData().

The action in a controller:

$widget=$this->createWidget('ext.EDataTables.EDataTables', array(
 'id'            => 'products',
 'dataProvider'  => $dataProvider,
 'ajaxUrl'       => Yii::app()->getBaseUrl().'/products/index',
 'columns'       => $columns,
));
if (!Yii::app()->getRequest()->getIsAjaxRequest()) {
  $this->render('index', array('widget' => $widget,));
  return;
} else {
  echo json_encode($widget->getFormattedData(intval($_REQUEST['sEcho'])));
  Yii::app()->end();
}

The index view (for non-ajax requests):

<?php $widget->run(); ?>

Preparing the dataprovider ¶

To use features like sorting, pagination and filtering (by quick search field in the toolbar or a custom advanced search filter form) the dataprovider object passed to the widget must be prepared using provided EDTSort and EDTPagination class and CDbCriteria filled after parsing sent forms.

The simplest example:

$criteria = new CDbCriteria;
// bro-tip: $_REQUEST is like $_GET and $_POST combined
if (isset($_REQUEST['sSearch']) && isset($_REQUEST['sSearch']{0})) {
    // use operator ILIKE if using PostgreSQL to get case insensitive search
    $criteria->addSearchCondition('textColumn', $_REQUEST['sSearch'], true, 'AND', 'ILIKE');
}
 
$sort = new EDTSort('ModelClass', $sortableColumnNamesArray);
$sort->defaultOrder = 'id';
$pagination = new EDTPagination();
 
$dataProvider = new CActiveDataProvider('ModelClass', array(
    'criteria'      => $criteria,
    'pagination'    => $pagination,
    'sort'          => $sort,
))

An advanced example would be based on a search form defined with a model and a view. Its attributes would be then put into a critieria and passed to a dataProvider.

Other options ¶

Check out the DataTables web page for docs regarding: * Table layout * Styling * Multi-column sorting etc. * Tons of examples and funky plugins

Todo ¶

• Documentation.
• Support for more DataTables properties.
• Checkbox column behaves different than in CGridView.

Coming soon ¶

• Docs on usage with external search filters.
• Documentation how to process row selections (from checkbox column) and re-set them after page reload.
• Docs how to use editable cells.

Resources ¶

• Project page
• Project wiki