Organizing data in a tabular way: the table

Basic concept

The most common way to display multiple rows of data from a source in your application is a table. In P4A, all we have to do is to create a new table widget by calling the build method.

// Use the p4a_table parameter on the build method
$this->build("p4a_table", "myTable");

Preparing a source

Now let's add some data to our table. First of all, we have to define a source to get the data from. In this case we'll just take a database table as explained in the chapter Connecting to a database. I assume a table called "users" in the database.

For my example, I will be using a MySQL table. Here's my sample table for "users":

CREATE TABLE IF NOT EXISTS `users` (
  `id` int(11) NOT NULL auto_increment,
  `first_name` varchar(100) character set utf8 NOT NULL,
  `last_name` varchar(100) character set utf8 NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COLLATE=utf8_bin AUTO_INCREMENT=3 ;

--
-- Data for table `users`
--

INSERT INTO `users` (`id`, `first_name`, `last_name`) VALUES
(1, 'John', 'Doe'),
(2, 'Peter', 'Foo');

Feel free to experiment with your own tables as soon as you understand the concept.

$this->build("p4a_db_source", "userTable");// instance a database object and name it "testTable"
$this->userTable->setTable("users");       // we use the database table "users"
$this->userTable->load();                  // get the data and assign it to our mask

Connecting table and source

Source and table are glued together by calling the setSource method on the table object.

$this->myTable->setSource($this->userTable);

All that's left to do now is sent our table to either a frame or the display itself.

$this->display("main",  $this->myTable);

Some configuration

Now that we have our first table up and running, let's do some configuration.

$this->myTable
	->setWidth(400)                                         // Set the width of the table to 400
	->setVisibleCols(array("id","last_name"))               // Display only certain rows in our table
	->hideNavigationBar()                                   // Hide navigation bar (default), opposite of showNavigationBar(), which is default
	->hideRowIndicator();                                   // Hide row indicator, opposite of showRowIndicator(), which is default

Toy around with these options until you feel at home or check the API reference for more useful options.

Columns

Each column of our table can be directly addressed via the table object.

$this->myTable->cols->last_name
	->setWidth(50)       // set column width to 50
	->setLabel('Name');

You can even enhance your table with custom columns. Let's just add an "edit" and a "delete" column for good measure and prepare them for some action.

$this->myTable
	->addActionCol('delete')
	->addActionCol('edit');

Now let's add the actions. First we want the "edit" column to call the function "editValue" within our mask when clicked. Please be aware that clicking on "edit" will result in an error as long as you do not have a method called "editValue" within your class. Since this is for demonstration only, I will not include the function here.

$this->myTable->cols->edit
	->setWidth(50)                                       // set column width to 50
	->setLabel('[Edit]')                                 // set column content
	->implement("afterClick", $this, "editValue");       // add action,: after being clicked, function "editValue" is called

And finally we add the "delete" button.

$this->myTable->cols->delete
	->setWidth(50)
	->setLabel('[Delete]')
	->requireConfirmation('onClick', 'Do you really want to delete this entry?');
// add an interceptor to check if the onClick check returned true. If so, use "deleteRow()" on table
$this->myTable->data->intercept($this->myTable->cols->delete,'afterClick','deleteRow');

Grid table

Coming with P4A 3.2, the p4a_grid table was added. This widget allows you to edit the table content within each cell. Let's exchange our p4a_table with a p4a_grid table.

// Define the grid table
$this->build("p4a_grid", "myTable")
	->setWidth(400)
	->setSource($this->userTable)
	->setVisibleCols(array("id","first_name", "last_name"))
	->showNavigationBar()
	->hideRowIndicator();
// Auto-save edited values
$this->myTable->autosave();

The p4a_grid inherits all methods from p4a_table plus:

void autoSave () 
void getRows ($num_page, $rows) 
void preChange ([$params = null]) 
void saveData ($obj, $params) 

Simple Edit Mask

Another addition made in 3.2 was the so-called "Simple Edit Mask", which provides you with both with a table and an edit form.

class test_users extends P4A_Base_Mask   
{   
    public function __construct()   
    {   
        parent::__construct();   
        $this->constructSimpleEdit("users");   
    }   
}

Or the even much simpler:

class test_users extends P4A_Simple_Edit_Mask
{   
  
    public function __construct()   
    {   
     parent::__construct("users");   
    }      
}  

You can find more information on grid tables and the simple edit mask at Mario Spada's blog (written in Italian), where you can also find the examples mentioned here.