You are here

Home » API reference » DataTables 8 » datatables.theme.inc

function template_preprocess_datatable in DataTables 8

Same name and namespace in other branches
  1. 2.x datatables.theme.inc \template_preprocess_datatable()
  2. 1.x datatables.theme.inc \template_preprocess_datatable()

Prepares variables for DataTable templates.

Default template: datatable.html.twig.

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 $variables['attributes']['datatable_options'] as an associative array. For example:

$variables['attributes']['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.

$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',
    ),
  ),
);
  • footer: An array of table rows which will be printed within a <tfoot> tag, in the same format as the rows element (see above).
  • 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.

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, as a string or render array.
    • 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"). Only one column should be given a default sort order because table sorting only applies to one column at a time.
    • class: An array of values for the 'class' attribute. In particular, the least important columns that can be hidden on narrow and medium width screens should have a 'priority-low' class, referenced with the RESPONSIVE_PRIORITY_LOW constant. Columns that should be shown on medium+ wide screens should be marked up with a class of 'priority-medium', referenced by with the RESPONSIVE_PRIORITY_MEDIUM constant. Themes may hide columns with one of these two classes on narrow viewports to save horizontal space.
    • Any HTML attributes, such as "colspan", to apply to the column header cell.
  • 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 or render array 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:

See also

template_preprocess_table()

File

./datatables.theme.inc, line 147
Preprocessors for DataTable theming.

Code

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

    // 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']);
          }
        }
      }
    }

    // Generate unique id.
    if (empty($variables['attributes']['id'])) {
      $variables['attributes']['id'] = Html::getUniqueId('datatable');
    }
    $variables['#attached']['library'][] = 'datatables/datatables';
    $variables['#attached']['library'][] = 'datatables/datatables_core';
    $variables['#attached']['drupalSettings']['datatables']['#' . $variables['attributes']['id']] = $datatable_options;
    unset($attributes['datatable_options']);
  }
  template_preprocess_table($variables);
}