Marmot Manual

Chapter 14. Tabulators

Table of Contents

Introduction to Tabulators
Creating a tabulator object
Adding columns to a tabulator
Adding rows to a tabulator
Getting data from a tabulator
Summarizing Tabulator data

The MU_Tabulator class implements an end-to-end method for displaying data in rows and columns. The tabulator class provides the following types of services:

  • Navigation services

  • Data caching

  • Data input

  • Summarization

Introduction to Tabulators

The typical order of operation for using tabulator objects is:

  1. Instanciate the tabulator object

  2. Add columns

  3. Add rows (if necessary)

  4. Add the tabulator to a presentation object

The user then interacts with the tabulator. If it is a display only tabulator, you have no further responsibility. If the tabulator contains data input, the user will submit the tabulator and you:

  1. Instanciate the tabulator object

  2. Process selected or changed rows

It is not uncommon to instanciate the tabulator early in your page, check if the user did anything, and then perform appropriate actions in the script. Tabulators know two important pieces of information about themselves that facilitate this.

  1. the action clicked by the user

  2. the validation state

$table_name = 'instructors'; $presentation = new MU_Presentation($cfg_xslt); $presentation->parameters(array('title' => 'Edit Instructors', 'appname' => $cfg_appname)); add_nav($presentation); $body =& $presentation->add_body(); $table = new MU_Tabulator($table_name, 'all'); if ($table->user_action == 'delete') { foreach ($table->selected() as $row) { $instructor->read($row->id); $instructor->delete(); } $table->refresh(); } elseif ($table->user_action == 'save') { foreach ($table->changed() as $row) { $instructor->read($row->id); $instructor->uniqueid = $row->value('uniqueid'); $instructor->last_name = $row->value('last_name'); $instructor->first_name = $row->value('first_name'); $instructor->active = $row->value('active'); $instructor->gb_admin = $row->value('gb_admin'); $instructor->save(); } #We need to refresh the tabulator now since changing the active status for an #instructor can alter the rows displayed. $table->refresh(); } $table->title = 'Instructors'; $table->number = 'on'; $table->allow_show_all = 1; $table->navigation = 'on'; $table->row_select = 'on'; $table->set_default('sort_by', 'last_name'); $table->add_column('uniqueid', array('input_type' => 'text', 'sortable' => '1'), 'UniqueID'); $table->add_column('last_name', array('input_type' => 'text', 'sortable' => '1'), 'Last Name'); $table->add_column('first_name', array('input_type' => 'text', 'sortable' => '1'), 'First Name'); $table->add_column('active', array('input_type' => 'option', 'list_source' => array('1' => '')), 'Active'); $table->add_column('gb_admin', array('input_type' => 'option', 'list_source' => array('1' => '')), 'Admin'); if ($table->wants_records) { $finder = new MU_Object_Finder('Instructor'); if ($_SESSION['show_instructors']) { $finder->attribute('active', '=', 1); } $finder->order($table->sort_by, $table->sort_direction); $instructor_count = $finder->find(); while ($instructor = $finder->next()) { $table->add_row($instructor->instructor_id, array( 'uniqueid' => $instructor->uniqueid, 'last_name' => $instructor->last_name, 'first_name' => $instructor->first_name, 'active' => $instructor->active, 'gb_admin' => $instructor->gb_admin )); } } $table->add_user_action('delete', ' Delete Selected '); $table->add_user_action('save', ' Save ', 'validate'); $body->add_object($table);

You should notice some points of particular interest from this example:

  1. Tabulators are created by name.

    A tabulator's name, the first parameter in the constructor, is important to using the tabulator. When you create a tabulator, it checks for any existing tabulator information of that name and, if found, uses it to initialize itself. That's how it finds its data, knows the user action, and knows if it is validated as soon as it is created.

  2. Tabulators require a key.

    The second paramter in the constructor is a key for the data in a particular tabulator. The key is related to row caching (see more below) and is used to indicate that the data displayed is for a different key, causing the cache to be cleared. For example, I have a list of classes which I can click on to a student roster. The tabulator name may be "class_roster" and the key is the CRN of the class. That way as each class is displayed, the tabulator knows when its data changes.

  3. Actions are keyed on name.

    Tabulator actions are referred to by name, first parameter in the add_user_action method. The display value of the action, the second paramter, is used internally.

  4. Tabulators must be added to the presentation after they are built.

    Unlike presentation elements, the tabulator object must be completely built before adding it to the presentation object. Once you have completed building the tabulator object, you add it to the presentation layer by calling the add_object method on the presentation element that will contain the tabulator (ie, the body), giving the tabulator as the paramter.

Please refer to the class documentation for MU_Tabulator for details about class attributes and methods.

Prev Up Next
Gathering Data from a Move List Home Creating a tabulator object