JTable

From Joomla! Documentation
(Difference between revisions)
Jump to: navigation, search
(Made a start on updating JTable documentation.)
Line 1: Line 1:
−
'''JTable''' is an abstract class which provides a number of methods to handle database tables.  Some of the methods listed will be overridden by the child class so you should check the child class documentation for further information.
+
'''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.
 +
 
 +
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 [[JTable/load|load]] method.  The table row can then be just as easily updated using the [[JTable/save|save]] method, which also performs any predefined sanity checks on the table fields.
  
 
===Defined in===
 
===Defined in===
Line 8: Line 10:
  
 
===Extended by===
 
===Extended by===
−
* [[JTableMenuTypes]]
+
* [[JTableARO]]
−
* [[JTableContent]]
+
−
* [[JTableCategory]]
+
 
* [[JTableAROGroup]]
 
* [[JTableAROGroup]]
−
* [[JTablePlugin]]
+
* [[JTableAsset]] (from 1.6)
−
* [[JTableUser]]
+
* [[JTableCategory]]
−
* [[JTableARO]]
+
 
* [[JTableComponent]]
 
* [[JTableComponent]]
−
* [[JTableSession]]
+
* [[JTableContent]]
 
* [[JTableMenu]]
 
* [[JTableMenu]]
−
* [[JTableSection]]
+
* [[JTableMenuTypes]]
 
* [[JTableModule]]
 
* [[JTableModule]]
 +
* [[JTableNested]] (from 1.6)
 +
* [[JTablePlugin]]
 +
* [[JTableSection]]
 +
* [[JTableSession]]
 +
* [[JTableTree]] (from 1.6)
 +
* [[JTableUser]]
 +
 +
===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.
 +
{| class="wikitable"
 +
|-
 +
!Field name
 +
!Methods using the field name
 +
|-
 +
|checked_out
 +
|[[JTable/checkOut|checkOut]], [[JTable/checkIn|checkIn]], [[JTable/isCheckedOut|isCheckedOut]]
 +
|-
 +
|checked_out_time
 +
|[[JTable/checkOut|checkOut]], [[JTable/checkIn|checkIn]], [[JTable/isCheckedOut|isCheckedOut]]
 +
|-
 +
|hits
 +
|[[JTable/hit|hit]]
 +
|-
 +
|ordering
 +
|[[JTable/getNextOrder|getNextOrder]], [[JTable/reorder|reorder]], [[JTable/move|move]]
 +
|-
 +
|published
 +
|[[JTable/publish|publish]]
 +
|}
 +
 +
====Check-in/check-out====
 +
Joomla tables implement a simple mechanism for preventing a [[wikipedia:race condition|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 '''JTable''' will automatically support this mechanism so that it can be easily used in your tables too.  In addition to the [[JTable/checkOut|checkOut]] and [[JTable/checkIn|checkIn]] methods, there is a [[JTable/isCheckedOut|isCheckedOut]] method to determine if a given table row is currently checked out by another user.
 +
 +
====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: [[JTable/hit|hit]].
 +
 +
====Ordering====
 +
Many Joomla tables support a user-defined ordering of the rows.
 +
 +
To be written.
 +
 +
====Publish/Unpublish====
 +
To be written.
  
 
===Get and Set Methods===
 
===Get and Set Methods===
Line 28: Line 70:
 
!Set method
 
!Set method
 
!Description
 
!Description
−
!Property
+
|-
 +
|[[JTable/getAssetNamePrefix|getAssetNamePrefix]]
 +
|
 +
|Abstract method to return the name prefix to use for the asset table.  From 1.6.
 +
|-
 +
|[[JTable/getAssetSection|getAssetSection]]
 +
|
 +
|Abstract method to return the access section name for the asset table.  From 1.6.
 +
|-
 +
|[[JTable/getAssetTitle|getAssetTitle]]
 +
|
 +
|Abstract method to return the title to use for the asset table.  From 1.6.
 
|-
 
|-
 
|[[JTable/getDBO|getDBO]]
 
|[[JTable/getDBO|getDBO]]
 
|[[JTable/setDBO|setDBO]]
 
|[[JTable/setDBO|setDBO]]
−
|Method to set/get the Database Object used for all table transactions
+
|Method to set/get the [[JDatabase]] connector object associated with the table.
−
|$_db
+
 
|-
 
|-
 
|[[JTable/getTableName|getTableName]]
 
|[[JTable/getTableName|getTableName]]
 
|
 
|
−
|Method to get the name of the database table, that is being representent by the table-object
+
|Method to get the name of the database table.
−
|$_tbl
+
 
|-
 
|-
 
|[[JTable/getKeyName|getTableKey]]
 
|[[JTable/getKeyName|getTableKey]]
 
|
 
|
−
|Method to get the name of the primary key of the table
+
|Method to get the primary key field name for the table
−
|$_tbl_key
+
 
|}
 
|}
  
Line 56: Line 106:
 
|-
 
|-
 
|[[JTable/addIncludePath|addIncludePath]]
 
|[[JTable/addIncludePath|addIncludePath]]
−
|Add a directory where JTable should search for table types. You may either pass a string or an array of directories.
+
|Add a filesystem path where '''JTable''' should search for table class files.
 
|-
 
|-
 
|[[JTable/bind|bind]]
 
|[[JTable/bind|bind]]
−
|Binds a named array/hash to this object
+
|Binds an associative array or object to the '''JTable''' instance.
 
|-
 
|-
 
|[[JTable/canDelete|canDelete]]
 
|[[JTable/canDelete|canDelete]]
−
|Generic check for whether dependancies exist for this object in the db schema
+
|Checks whether dependencies exist for this object in the database schema.
 
|-
 
|-
 
|[[JTable/check|check]]
 
|[[JTable/check|check]]
−
|Generic check method
+
|Perform sanity checks on the '''JTable''' instance properties.
 
|-
 
|-
 
|[[JTable/checkin|checkin]]
 
|[[JTable/checkin|checkin]]
−
|Checks in a row
+
|Checks a row in if the necessary instance properties and table fields exist.
 
|-
 
|-
 
|[[JTable/checkout|checkout]]
 
|[[JTable/checkout|checkout]]
−
|Checks out a row
+
|Checks a row out if the necessary instance properties and table fields exist.
 
|-
 
|-
 
|[[JTable/delete|delete]]
 
|[[JTable/delete|delete]]
−
|Default delete method
+
|Deletes a row from the database table by primary key value.
 
|-
 
|-
 
|[[JTable/getInstance|getInstance]]
 
|[[JTable/getInstance|getInstance]]
−
|Returns a reference to the a Table object, always creating it
+
|Static method to get an instance of a '''JTable''' class.
 
|-
 
|-
 
|[[JTable/getNextOrder|getNextOrder]]
 
|[[JTable/getNextOrder|getNextOrder]]
−
|Returns the ordering value to place a new item last in its group
+
|Gets the next ordering value for a group of rows defined by an SQL WHERE clause.
 
|-
 
|-
 
|[[JTable/hit|hit]]
 
|[[JTable/hit|hit]]
−
|
+
|Increments the hits for a row if the necessary instance property and table field exists.
 
|-
 
|-
 
|[[JTable/isCheckedOut|isCheckedOut]]
 
|[[JTable/isCheckedOut|isCheckedOut]]
−
|Check if an item is checked out
+
|Determines if a row is checked out and therefore un-editable by a user.
 
|-
 
|-
 
|[[JTable/load|load]]
 
|[[JTable/load|load]]
−
|Loads a row from the database and binds the fields to the object properties
+
|Loads a row from the database by primary key and binds the fields to the '''JTable''' instance properties.
 
|-
 
|-
 
|[[JTable/move|move]]
 
|[[JTable/move|move]]
−
|
+
|Moves a row in the ordering sequence of a group of rows defined by an SQL WHERE clause.
 
|-
 
|-
 
|[[JTable/publish|publish]]
 
|[[JTable/publish|publish]]
−
|Generic Publish/Unpublish function
+
|Sets the publishing state for a row or list of rows in the database table.
 
|-
 
|-
 
|[[JTable/reorder|reorder]]
 
|[[JTable/reorder|reorder]]
−
|Compacts the ordering sequence of the selected records
+
|Compacts the ordering values of rows in a group of rows defined by an SQL WHERE clause.
 
|-
 
|-
 
|[[JTable/reset|reset]]
 
|[[JTable/reset|reset]]
−
|Resets the default properties
+
|Resets class properties to the defaults set in the class definition.
 
|-
 
|-
 
|[[JTable/save|save]]
 
|[[JTable/save|save]]
−
|Generic save function
+
|Provides a shortcut to binding, checking and storing a '''JTable''' instance to the database table.
 
|-
 
|-
 
|[[JTable/store|store]]
 
|[[JTable/store|store]]
−
|Inserts a new row if id is zero or updates an existing row in the database table
+
|Stores a row in the database from the '''JTable''' instance properties.
 
|-
 
|-
 
|[[JTable/toXML|toXML]]
 
|[[JTable/toXML|toXML]]
−
|Export item list to xml
+
|Exports the '''JTable''' instance properties to an XML string.
 
|}
 
|}
 
===Importing===
 
===Importing===
Line 120: Line 170:
  
 
===See also===
 
===See also===
−
* [http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4_-_Creating_an_Administrator_Interface#Creating_the_Table_Class Extending the JTable Class (MVC Tutorial)]
+
* [[How to use the database classes in your script]]
 +
* [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]
 +
* [[How to connect to an external database]]
 
<noinclude>[[Category:Development]][[Category:Framework]][[Category:JTable]]</noinclude>
 
<noinclude>[[Category:Development]][[Category:Framework]][[Category:JTable]]</noinclude>

Revision as of 12:14, 13 June 2009

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.

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.

Contents

Defined in

/joomla/database/table.php

Extends

Extended by

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 JTable will automatically support this mechanism so that it can be easily used in your tables too. In addition to the checkOut and checkIn methods, there is a isCheckedOut method to determine if a given table row is currently checked out by another user.

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.

Ordering

Many Joomla tables support a user-defined ordering of the rows.

To be written.

Publish/Unpublish

To be written.

Get and Set Methods

Properties which do not have specific get or set methods listed here can be retrieved or set using the inherited JObject->get method.

Get method Set method Description
getAssetNamePrefix Abstract method to return the name prefix to use for the asset table. From 1.6.
getAssetSection Abstract method to return the access section name for the asset table. From 1.6.
getAssetTitle Abstract method to return the title to use for the asset table. From 1.6.
getDBO setDBO Method to set/get the JDatabase connector object associated with the table.
getTableName Method to get the name of the database table.
getTableKey Method to get the primary key field name for the table

Other Methods

Method name Description
construct Object constructor to set table and key field
addIncludePath Add a filesystem path where JTable should search for table class files.
bind Binds an associative array or object to the JTable instance.
canDelete Checks whether dependencies exist for this object in the database schema.
check Perform sanity checks on the JTable instance properties.
checkin Checks a row in if the necessary instance properties and table fields exist.
checkout Checks a row out if the necessary instance properties and table fields exist.
delete Deletes a row from the database table by primary key value.
getInstance Static method to get an instance of a JTable class.
getNextOrder Gets the next ordering value for a group of rows defined by an SQL WHERE clause.
hit Increments the hits for a row if the necessary instance property and table field exists.
isCheckedOut Determines if a row is checked out and therefore un-editable by a user.
load Loads a row from the database by primary key and binds the fields to the JTable instance properties.
move Moves a row in the ordering sequence of a group of rows defined by an SQL WHERE clause.
publish Sets the publishing state for a row or list of rows in the database table.
reorder Compacts the ordering values of rows in a group of rows defined by an SQL WHERE clause.
reset Resets class properties to the defaults set in the class definition.
save Provides a shortcut to binding, checking and storing a JTable instance to the database table.
store Stores a row in the database from the JTable instance properties.
toXML Exports the JTable instance properties to an XML string.

Importing

jimport( 'joomla.database.table' );

Extending the JTable Class for new database tables

The JTable Class can easily be extended in order to make the table object represent any table in your database. A good start how to learn about creating Child Classes for the JTable Class is to take a look at the fourth part of the MVC Tutorial

See also

Retrieved from "http://docs.joomla.org/index.php?title=JTable&oldid=14629"
Personal tools
Namespaces

Variants
Actions
Navigation
Joomla! Sites
Toolbox