1 theme.inc theme_table(array $variables)

Returns HTML for a table.

@since 1.18.4 "footer" key added to $variables parameter.

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").
    • "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. Only one column should be given a default sort order because table sorting only applies to one column at a time.
    • Any HTML attributes, such as "colspan", to apply to the column header cell.
  • footer: An array of table rows which will be printed within a <tfoot> tag, in the same format as the rows element (see above). The structure is the same the one defined for the "rows" key except that the no_striping boolean has no effect, there is no rows striping for the table footer.
  • 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'), // Attribute for the COL element.
        ),
      ),
      // Colgroup with attributes and inner COL elements.
      array(
        'data' => array(
          array(
            'class' => array('funky'), // Attribute for the COL element.
          ),
        ),
        'class' => array('jazzy'), // Attribute for the COLGROUP element.
      ),
    );

These optional tags are used to group and set properties on columns within a table. For example, one may group three columns and apply the 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.

Return value

string: The HTML output.

Related topics

Default theme implementations Functions and templates for the user interface to be implemented by themes.

File

core/includes/theme.inc, line 2154
The theme system, which controls the output of Backdrop.

Code

function theme_table(array $variables) {
  $header = (array) $variables['header'];
  $rows = (array) $variables['rows'];
  $attributes = $variables['attributes'];
  $caption = $variables['caption'];
  $colgroups = $variables['colgroups'];
  $sticky = $variables['sticky'];
  $empty = $variables['empty'];

  // The output string contains the inner content of the table. The table tag
  // itself is added at the end.
  $output = '';
  if (isset($caption)) {
    $output .= '<caption>' . $caption . "</caption>\n";
  }

  // Format the table columns:
  if (!empty($colgroups)) {
    foreach ($colgroups as $colgroup) {
      $colgroup_attributes = array();

      // Check if we're dealing with a simple or complex column.
      if (isset($colgroup['data'])) {
        foreach ($colgroup as $key => $value) {
          if ($key == 'data') {
            $cols = $value;
          }
          else {
            $colgroup_attributes[$key] = $value;
          }
        }
      }
      else {
        $cols = $colgroup;
      }

      // Build colgroup.
      if (is_array($cols) && count($cols)) {
        $output .= ' <colgroup' . backdrop_attributes($colgroup_attributes) . '>';
        foreach ($cols as $col) {
          $output .= ' <col' . backdrop_attributes($col) . ' />';
        }
        $output .= " </colgroup>\n";
      }
      else {
        $output .= ' <colgroup' . backdrop_attributes($colgroup_attributes) . " />\n";
      }
    }
  }

  // Add the 'empty' row message if available.
  if (empty($rows) && $empty) {
    $header_count = 0;
    if (!empty($header)) {
      foreach ($header as $header_cell) {
        if (is_array($header_cell)) {
          $header_count += isset($header_cell['colspan']) ? $header_cell['colspan'] : 1;
        }
        else {
          $header_count++;
        }
      }
    }
    $rows[] = array(array('data' => $empty, 'colspan' => $header_count, 'class' => array('empty', 'message')));
  }

  $responsive_columns = array();
  // Format the table header.
  if (!empty($header)) {
    $ts = tablesort_init($header);
    // HTML requires that the thead tag has tr tags in it followed by tbody
    // tags. Using ternary operator to check and see if we have any rows.
    $output .= (!empty($rows) ? ' <thead><tr>' : ' <tr>');
    $i = 0;
    foreach ($header as $cell) {
      $i++;
      // Track responsive classes for each column as needed. Only the header
      // cells for a column are marked up with the responsive classes by a
      // module developer or themer. The responsive classes on the header cells
      // must be transferred to the content cells.
      if (!empty($cell['class']) && is_array($cell['class'])) {
        if (in_array(RESPONSIVE_PRIORITY_MEDIUM, $cell['class'])) {
          $responsive_columns[$i] = RESPONSIVE_PRIORITY_MEDIUM;
        }
        elseif (in_array(RESPONSIVE_PRIORITY_LOW, $cell['class'])) {
          $responsive_columns[$i] = RESPONSIVE_PRIORITY_LOW;
        }
      }
      $cell = tablesort_header($cell, $header, $ts);
      $output .= _theme_table_cell($cell, TRUE);
    }
    // Using ternary operator to close the tags, based on whether or not there
    // are rows.
    $output .= (!empty($rows) ? " </tr></thead>\n" : "</tr>\n");
  }
  else {
    $ts = array();
  }

  // Format the table and footer rows.
  $sections = array();

  if (!empty($rows)) {
    $sections['tbody'] = $rows;
  }

  if (!empty($variables['footer'])) {
    $sections['tfoot'] = $variables['footer'];
  }

  // The tbody and tfoot HTML tags have the same structure, and are built
  // using the same procedure.
  foreach ($sections as $tag => $content) {
    $output .= "<$tag>\n";
    $flip = array('even' => 'odd', 'odd' => 'even');
    $class = 'even';
    $default_no_striping = ($tag === 'tfoot');

    foreach ($content as $number => $row) {
      // Check if we're dealing with a simple or complex row.

      if (isset($row['data'])) {
        $cells = $row['data'];
        $no_striping = isset($row['no_striping']) ? $row['no_striping'] : $default_no_striping;

        // Set the attributes array and exclude 'data' and 'no_striping'.
        $tr_attributes = $row;
        unset($tr_attributes['data']);
        unset($tr_attributes['no_striping']);
      }
      else {
        $cells = $row;
        $tr_attributes = array();
        $no_striping = $default_no_striping;
      }

      if (!empty($cells)) {
        // Add odd/even class.
        if (!$no_striping) {
          $class = $flip[$class];
          $tr_attributes['class'][] = $class;
        }

        // Build row.
        $output .= ' <tr' . backdrop_attributes($tr_attributes) . '>';
        $i = 0;
        foreach ($cells as $cell) {
          // Add active class if needed for sortable tables.
          $cell = tablesort_cell($cell, $header, $ts, $i);
          $i++;
          // Copy RESPONSIVE_PRIORITY_LOW/RESPONSIVE_PRIORITY_MEDIUM
          // class from header to cell as needed.
          if (isset($responsive_columns[$i])) {
            if (is_array($cell)) {
              $cell['class'][] = $responsive_columns[$i];
            }
            else {
              $cell = array('data' => $cell, 'class' => array($responsive_columns[$i]));
            }
          }
          $output .= _theme_table_cell($cell);
        }
        $output .= " </tr>\n";
      }
    }

    $output .= "</$tag>\n";
  }

  // Add sticky headers if enabled.
  if (!empty($header) && $sticky) {
    backdrop_add_js('core/misc/tableheader.js');
    // Add 'sticky-enabled' class to the table to identify it for JS.
    // This is needed to target tables constructed by this function.
    $attributes['class'][] = 'sticky-enabled';
  }
  // If the responsive classes were used, add the matching library.
  if (count($responsive_columns)) {
    backdrop_add_library('system', 'backdrop.tableresponsive');
    // Add 'responsive-enabled' class to the table to identify it for JS.
    // This is needed to target tables constructed by this function.
    $attributes['class'][] = 'responsive-enabled';
  }

  // Wrap the result in the table tag. This is done last so that the
  // responsive-enabled class is added only when needed.
  $output = '<table' . backdrop_attributes($attributes) . ">\n$output</table>\n";

  return $output;
}