datatables.module in DataTables 6

Provides integration of the jQuery DataTables plugin

File

datatables.module

<?php

/**
 * @file
 * Provides integration of the jQuery DataTables plugin
 */

/**
 * Implementation of hook_theme().
 */
function datatables_theme() {
  return array(
    'datatable' => array(
      'arguments' => array(
        $header => NULL,
        $rows => NULL,
        $attributes => $caption,
      ),
    ),
  );
}

/**
 * Implementation of hook_views_api().
 */
function datatables_views_api() {
  return array(
    'api' => 2.0,
    'path' => drupal_get_path('module', 'datatables') . '/views',
  );
}

/**
 * Return a themed DataTable.
 *
 * This function takes the same parameters as theme_table, but also allows the 
 * inclusion of DataTable specific information in the $header and $attributes 
 * parameters in order to configure a DataTable.  If an id is not set in the 
 * $attributes paramater, a unique one is generated.
 *
 * To set features and options for the DataTable, add
 * $parameters['datatable_options'] as an associative array.
 * For example:
 * @code
 *   $parameters['datatables_options'] = array(
 *     'bFilter'   => FALSE,  // Disable filtering of data.
 *     'bInfo'     => TRUE,   // Show the table information display.
 *     'aaSorting' => array(  // Sort by 3rd column first, and then 4th column.
 *        array(2, 'asc'),
 *        array(3, 'desc'),
 *      ),
 *   );
 * @endcode
 * See http://datatables.net/usage/features and 
 * http://datatables.net/usage/options for a full list of features and options.
 *
 * To enable column specific options, set the datatable_options for each of the 
 * columns in the $header parameter.
 * For example:
 * @code
 *   $header = array(
 *     array(
 *       'data' => t('Column 1'),
 *       'datatable_options' => array(
 *        'bSortable' => TRUE,  // Enable sorting on this column.
 *       ),
 *     ),
 *     array(
 *       'data' => t('Column 2'),
 *       'datatable_options' => array(
 *         'bSearchable' => FALSE, // Disable filtering on this column.
 *       ),
 *     ),
 *   );
 * @endcode
 * Note: if the aaColumns option is enabled in $parameters['datatable_options'], 
 * then all datatable_options in the $header parameter will be ignored, since 
 * the parameters will override column options.  See 
 * http://datatables.net/usage/columns for a full list of column options.
 *
 * @param $header
 *   An array containing the table headers. Each element of the array can be
 *   either a localized string or an associative array with the following keys:
 *   - "data": The localized title of the table column.
 *   - Any HTML attributes, such as "colspan", to apply to the column header cell.
 *   - "datatable_options": An associative array containing DataTable column 
 *     specific features/options.
 * @param $rows
 *   An array of table rows. Every row is an array of cells, or an associative
 *   array with the following keys:
 *   - "data": an array of cells
 *   - Any HTML attributes, such as "class", to apply to the table row.
 *
 *   Each cell can be either a string or an associative array with the following keys:
 *   - "data": The string to display in the table cell.
 *   - "header": Indicates this cell is a header.
 *   - Any HTML attributes, such as "colspan", to apply to the table cell.
 *
 *   Here's an example for $rows:
 *   @code
 *   $rows = array(
 *     // Simple row
 *     array(
 *       'Cell 1', 'Cell 2', 'Cell 3'
 *     ),
 *     // Row with attributes on the row and some of its cells.
 *     array(
 *       'data' => array('Cell 1', array('data' => 'Cell 2', 'colspan' => 2)), 'class' => 'funky'
 *     )
 *   );
 *   @endcode
 *
 * @param $attributes
 *   An array of HTML attributes to apply to the table tag.  If the
 *   datatable_options is set, then those options are passed to the 
 *   dataTable constructor.
 * @param $caption
 *   A localized string to use for the <caption> tag.
 * @return
 *   An HTML string representing the table.
 * @see theme_table
 */
function theme_datatable($header, $rows, $attributes = array(), $caption = NULL) {
  $datatable_options = $attributes['datatable_options'];

  // Column settings can either be set with the global options
  // or in each header definition.
  if (!$datatable_options['aoColumns']) {
    foreach ($header as $key => $cell) {
      $datatable_options['aoColumns'][] = $cell['datatable_options'];
      unset($header[$key]['datatable_options']);
    }
  }

  // Set unique id
  if (!$attributes['id']) {
    $attributes['id'] = _datatables_get_id();
  }
  drupal_add_css(drupal_get_path('module', 'datatables') . '/dataTables/media/css/demo_table.css');
  drupal_add_js(drupal_get_path('module', 'datatables') . '/dataTables/media/js/jquery.dataTables.js');
  drupal_add_js(drupal_get_path('module', 'datatables') . '/js/datatables.js');
  drupal_add_js(array(
    'datatables' => array(
      '#' . $attributes['id'] => $datatable_options,
    ),
  ), 'setting');
  unset($attributes['datatable_options']);
  return theme('table', $header, $rows, $attributes, $caption);
}

/**
 * Display a view as a DataTable style.
 */
function template_preprocess_datatables_view(&$vars) {
  $view = $vars['view'];

  // We need the raw data for this grouping, which is passed in as $vars['rows'].
  // However, the template also needs to use for the rendered fields.  We
  // therefore swap the raw data out to a new variable and reset $vars['rows']
  // so that it can get rebuilt.
  $result = $vars['rows'];
  $vars['rows'] = array();
  $options = $view->style_plugin->options;
  $handler = $view->style_plugin;
  $fields =& $view->field;
  $columns = $handler
    ->sanitize_columns($options['columns'], $fields);
  $active = !empty($handler->active) ? $handler->active : '';
  $order = !empty($handler->order) ? $handler->order : 'asc';

  // Fields must be rendered in order as of Views 2.3, so we will pre-render
  // everything.
  $renders = array();
  $keys = array_keys($view->field);
  foreach ($result as $count => $row) {
    foreach ($keys as $id) {
      $renders[$count][$id] = $view->field[$id]
        ->theme($row);
    }
  }
  $position = 0;
  foreach ($columns as $field => $column) {
    $column_options = NULL;
    switch ($options['hidden_columns'][$field]) {
      case 'expandable':
        $datatable_options['bExpandable'] = TRUE;

      // ... and fall through, since expandable columns are also hidden
      case 'hidden':

        // Hidden or expandable columns get the bVisible init option set to false
        $column_options['bVisible'] = FALSE;
    }

    // render the header labels
    if ($field == $column && empty($fields[$field]->options['exclude'])) {
      $vars['header'][$field] = check_plain(!empty($fields[$field]) ? $fields[$field]
        ->label() : '');
      if (empty($options['info'][$field]['sortable']) || !$fields[$field]
        ->click_sortable()) {
        $column_options['bSortable'] = FALSE;
      }
      else {

        // Attempt to autodetect the type of field in order to handle sorting correctly.
        if (strlen($fields[$field]->last_render) != strlen(strip_tags($fields[$field]->last_render))) {
          $column_options['sType'] = 'html';
        }
        elseif (is_numeric($fields[$field]->last_render)) {
          $column_options['sType'] = 'numeric';
        }
        elseif ($fields[$field] instanceof views_handler_field_date) {
          $column_options['sType'] = 'date';
        }
        $column_options['bSortable'] = TRUE;
      }
      $datatable_options['aoColumns'][] = $column_options;

      // Save header columns for use in expandable hidden rows.
      $datatable_options['aoColumnHeaders'][] = $vars['header'][$field];
    }

    // Set default sort order
    if ($options['default'] == $field) {
      $datatable_options['aaSorting'] = array(
        array(
          $position,
          $options['order'],
        ),
      );
    }

    // Create a second variable so we can easily find what fields we have and what the
    // CSS classes should be.
    $vars['fields'][$field] = views_css_safe($field);
    if ($active == $field) {
      $vars['fields'][$field] .= ' active';
    }

    // Render each field into its appropriate column.
    foreach ($result as $num => $row) {
      if (!empty($fields[$field]) && empty($fields[$field]->options['exclude'])) {
        $field_output = $renders[$num][$field];

        // Don't bother with separators and stuff if the field does not show up.
        if (empty($field_output) && !empty($vars['rows'][$num][$column])) {
          continue;
        }

        // Place the field into the column, along with an optional separator.
        if (!empty($vars['rows'][$num][$column])) {
          if (!empty($options['info'][$column]['separator'])) {
            $vars['rows'][$num][$column] .= filter_xss_admin($options['info'][$column]['separator']);
          }
        }
        else {
          $vars['rows'][$num][$column] = '';
        }
        $vars['rows'][$num][$column] .= $field_output;
      }
    }
    $position++;
  }

  // Enable table info display, if necessary.
  $datatable_options['bInfo'] = $options['elements']['table_info'];
  $datatable_options['bFilter'] = $options['elements']['search_box'];
  $datatable_options['bStateSave'] = $options['elements']['save_state'];
  $datatable_options['bLengthChange'] = $options['pages']['length_change'];
  $datatable_options['iDisplayLength'] = (int) $options['pages']['display_length'];

  // Enable ThemeRoller support, if necessary.
  if ($options['layout']['themeroller']) {
    $datatable_options['bJQueryUI'] = TRUE;
  }

  // Pass the sDOM parameter, if one is specified.
  if ($options['layout']['sdom']) {
    $datatable_options['sDom'] = $options['layout']['sdom'];
  }
  $datatable_options['bAutoWidth'] = $options['layout']['autowidth'];

  // Enable full_numbers pagination if selected
  switch ($options['pages']['pagination_style']) {
    case 'full_numbers':
      $datatable_options['sPaginationType'] = 'full_numbers';
      break;
    case 'no_pagination':
      $datatable_options['bPaginate'] = FALSE;
      break;
    default:

      // Do nothing. No parameters need to be sent for the default (two-button) style
      break;
  }
  foreach ($vars['rows'] as $num => $row) {
    $vars['row_classes'][$num][] = $num % 2 == 0 ? 'odd' : 'even';
  }
  $vars['class'] = 'views-table';
  $vars['id'] = _datatables_get_id();
  drupal_add_css(drupal_get_path('module', 'datatables') . '/dataTables/media/css/demo_table.css');
  drupal_add_js(drupal_get_path('module', 'datatables') . '/dataTables/media/js/jquery.dataTables.js');
  drupal_add_js(drupal_get_path('module', 'datatables') . '/js/datatables.js');
  drupal_add_js(array(
    'datatables' => array(
      '#' . $vars['id'] => $datatable_options,
    ),
  ), 'setting');
}

/**
 * Returns an unique DataTable id
 */
function _datatables_get_id() {
  static $datatable_id;
  return 'datatable-' . ++$datatable_id;
}

Functions

Name	Description
datatables_theme	Implementation of hook_theme().
datatables_views_api	Implementation of hook_views_api().
template_preprocess_datatables_view	Display a view as a DataTable style.
theme_datatable	Return a themed DataTable.
_datatables_get_id	Returns an unique DataTable id