Joomla! Documentation™

This tutorial is for

Introduction to JTable

The JTable class is an implementation of the Active Record design pattern. It is used throughout Joomla! for creating, reading, updating, and deleting aka CRUD tasks for records in the database table.

Since JTable is an abstract class that forms the basis for all database table classes, some of the methods listed will be overridden by the child class so you should check the child class documentation for further information. Also take note that as of Joomla! 2.5, JTable properties are automatically generated based on the schema of the specified table, which means you don't need to declare Member variables in your class (although you can still do it if you want to).

Each physical database table created should have a corresponding class derived from JTable to represent it. JTable provides many methods to make common manipulations to the table much simpler. For example, one of the most common operations you will need to perform is to read a table row into memory given a value for the primary key. This can be done easily using the load method. The table row can then be just as easily updated using the save method, which also performs any predefined sanity checks on the table fields.

Writing an extension of JTable

To use JTable, you will create an extension of the JTable class. In this example, we have a database table "#__recipes" with an autoincrementing primary key "id" containing all of our recipes. The only thing we need to do to start using JTable is to create a constructor in our extended JTable class. The class constructor will call the parent constructor to get the table: all it needs is the name of the table, the name of the primary key column, and the database instance.

<?php

defined('_JEXEC') or die();

class TableRecipes extends JTable
{
	public function __construct($db)
	{
		parent::__construct( '#__recipes', 'id', $db );
	}
}

If you were using this class as a part of a backend component called 'Recipes', you would place this code in the file /administrator/components/com_recipes/tables/recipes.php.

You can use this functionality in plugins just as in components. As a general rule you should avoid writing to the database from a module, and use plugins/components for this. Remember to use the built-in constants when linking to a custom path (outside the adminstrator/{com_nameofyourcomponent}/tables folder).

Using a JTable class extension

Once the table class is in place we can use it in our model getTable() function.

public function getTable($type = 'Recipes', $prefix = 'Table', $config = array())
{
	return JTable::getInstance($type, $prefix, $config);
}

You can use your JTable classes in any other Joomla! extension by using JTable::addIncludePath() in your extension's source code (use com_nameofyourcomponent in place of com_recipes):

JTable::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_recipes/tables');
$row = JTable::getInstance('recipes', 'Table', array());

Notice that the lowercase version of the suffix of your class name is used as the first parameter, with the prefix 'Table' as the second. Also, the getInstance() member function of JTable returns a JTableObject by reference instead of a value;.

Reserved Database Field Names

Some of the optional features of JTable require the existence of specially-named fields in the database table. If you require this additional functionality you should ensure that these named fields are present in the table. These field names should be considered reserved as any attempts to use them for purposes other than those supported by JTable may result in conflict.

Field name	Methods using the field name
checked_out	checkOut, checkIn, isCheckedOut
checked_out_time	checkOut, checkIn, isCheckedOut
hits	hit
ordering	getNextOrder, reorder, move
published	publish

Check-in/check-out

Joomla! tables implement a simple mechanism for preventing a race condition while editing rows in a database. This depends on the existence of database fields called "checked_out" and "checked_out_time" and if these fields are present in the view (JForm) JTable will automatically support this mechanism so that it can be easily used in your tables too.

Hit counter

Some Joomla tables contain a field called "hits" which records the number of times that a table row has been accessed. JTable provides a simple method to increment this field: hit.

Example JForm fields for Reserved database names in JTable

<field	name="state"
	type="list"
	label="JSTATUS"
	description="JFIELD_PUBLISHED_DESC"
	size="1"
	default="1">
	<option value="1">JPUBLISHED</option>
	<option	value="0">JUNPUBLISHED</option>
	<option	value="2">JARCHIVED</option>
	<option	value="-2">JTRASHED</option>
</field>
<field	name="checked_out"
	type="hidden"
	filter="unset"
	/>
<field	name="checked_out_time"
	type="hidden"
	filter="unset"
	/>
<field	name="created_user_id"
	label="JGLOBAL_FIELD_CREATED_BY_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="created_time"
	label="JGLOBAL_FIELD_CREATED_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="modified_user_id"
	label="JGLOBAL_FIELD_MODIFIED_BY_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="modified_time"
	label="JGLOBAL_FIELD_MODIFIED_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="hits"
	type="text"
	id="hits"
	class="readonly"
	label="JGLOBAL_HITS"
	size="20"
	readonly="true"
	filter="unset"
	/>

Useful Member Functions

• load Method to load into the JTable object a record by its primary key value (id) or a combination of criteria
• bind Method to bind a JTable object to a generic key / value array, i.e. assign the values from the array to the JTable object matching the array keys with the JTable object properties
• check Method to validate data before storing the object
• store Method to persist the object into database
• save Method to provide a shortcut to binding, checking and storing a JTable instance to the database table.

See Also

• Part 7 of J3.x:Developing an MVC Component/Using the database
• Part 14 of J2.5:Developing a MVC Component/Adding configuration

Summary

When properly extended, JTable gives you all of the basic functions you need for managing and retrieving records in a database table.