Table Building Function

TAPIr uses a method similar to the Forms API for defining tables. A table building function defines the fields and populates them with data.

Anatomy of a builder function for the imaginary table my_test_table:

<?php
function my_test_table($op) {
  switch (
$op) {
    case
'fields':
     
$fields[] = array('name' => 'name', 'title' => t('Name'), 'weight' => 0, 'enabled' => TRUE);
     
$fields[] = array('name' => 'age', 'title' => t('Age'), 'weight' => 1, 'enabled' => TRUE);
      return
$fields;

    case

'data':
     
$data['name'] = array('Bob', 'Sue');
     
$data['age'] = array('23', '21');
      return
$data;

    case

'attributes':
      return array(
'class' => 'test-table');
  }
}
?>

Defining Fields
Notice the switch checks $op and returns the appropriate data depending on how the function was called. If $op == 'fields', it is expected to return an array of field arrays for each field defined for the table. The field arrays should include the following keys:

  • string name - The internal designator of the field, never seen on the page.
  • string title - The title of the field as displayed in the table's header. This sets the default option, but a user may change this via the table's settings page.
  • int weight - The weight of the field, used to define its column position in the table. Fields are displayed from lowest to highest by weight.
  • bool enabled - TRUE if the field should be visible in the table, FALSE if it should not.
  • bool locked - Optional. When set to TRUE, the enabled setting of the field cannot be modified from the table's settings page. This will lock it either in the enabled or disabled position.

This list reflects the currently enabled keys, but we are open to ideas on expanding the offering. Other possibilities considered are user role and permission keys that would only display a field to a user who met a certain requirement.

Loading Table Data
When the builder function is called with $op == 'data', it is expected to return an array of row data arrays for each field. So, the array should have keys that coincide with the defined name of the field (one of the several internal uses of the field name). Each key's value should be an array of row data for that field. The row data is for the cells in that column, the first being the highest and displayed in order with no gaps. For a visual example, continue onto the next page.

Setting Table Attributes
If you want to assign attributes to the table tag (in this example, a class that applies to the whole table), you need to include a case for 'attributes' in the $op switch. It is expected to return an array of attributes, with the name of the attributes as keys and their values as values in the array.