function theme_datatable in DataTables 7

Same name and namespace in other branches

1. 6 datatables.module \theme_datatable()
2. 7.2 datatables.module \theme_datatable()

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:

$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',
    ),
  ),
);

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:

$header = array(
  array(
    'data' => t('Column 1'),
    'datatable_options' => array(
      'bSortable' => TRUE,
    ),
  ),
  array(
    'data' => t('Column 2'),
    'datatable_options' => array(
      'bSearchable' => FALSE,
    ),
  ),
);

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.

Parameters

array $variables: An associative array containing:

• 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.
  • "field": The database field represented in the table column (required if user is to be able to sort on this column).
  • "sort": A default sort order for this column ("asc" or "desc").
  • Any HTML attributes, such as "colspan", to apply to the column header cell.
  • "datatable_options": An associative array containing DataTable column specific features/options.
• 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.
  • "no_striping": a boolean indicating that the row should receive no 'even / odd' styling. Defaults to FALSE.

  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:

$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' => array(
      'funky',
    ),
  ),
);

• attributes: An array of HTML attributes to apply to the table tag.
• caption: A localized string to use for the <caption> tag.
• colgroups: An array of column groups. Each element of the array can be either:
  • An array of columns, each of which is an associative array of HTML attributes applied to the COL element.
  • An array of attributes applied to the COLGROUP element, which must include a "data" attribute. To add attributes to COL elements, set the "data" attribute with an array of columns, each of which is an associative array of HTML attributes.

  Here's an example for $colgroup:

$colgroup = array(
  // COLGROUP with one COL element.
  array(
    array(
      'class' => array(
        'funky',
      ),
    ),
  ),
  // Colgroup with attributes and inner COL elements.
  array(
    'data' => array(
      array(
        'class' => array(
          'funky',
        ),
      ),
    ),
    'class' => array(
      'jazzy',
    ),
  ),
);

These optional tags are used to group and set properties on columns within a table. For example, one may easily group three columns and apply same background style to all.

• sticky: Use a "sticky" table header.
• empty: The message to display in an extra row if table does not have any rows.

• 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.
• caption: A localized string to use for the <caption> tag.

Return value

string An HTML string representing the table.

See also

theme_table()

File

./datatables.module, line 208

Provides integration of the jQuery DataTables plugin

Code

function theme_datatable($variables) {
  $header =& $variables['header'];
  $attributes =& $variables['attributes'];
  if (isset($variables['rows'])) {
    $datatable_options = !empty($attributes['datatable_options']) ? $attributes['datatable_options'] : array();

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

    // Set unique id.
    if (!isset($attributes['id'])) {
      $attributes['id'] = _datatables_get_id();
    }
    drupal_add_library('datatables', 'datatables');
    drupal_add_js(array(
      'datatables' => array(
        '#' . $attributes['id'] => $datatable_options,
      ),
    ), 'setting');
    unset($attributes['datatable_options']);
  }
  return theme('table', $variables);
}