Joomla! Documentation - User contributions [en]

Textarea form field type

2012-02-15T15:40:22Z

Toadster122: /* Tips */

[[Image:Params.textarea.jpg|right]]

{{Ambox|type=notice|text=In Joomla! 1.5, [[Form field|form fields]] were [[Parameter|parameters]]. For that version, you may want to use the corresponding [[Textarea parameter type]].}}

The '''textarea''' form field type provides a text area for entry of multi-line text. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

* '''type''' (mandatory) must be ''textarea''.
* '''name''' (mandatory) is the unique name of the field.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''rows''' (mandatory) is the height of the visible text area in lines. If omitted the width is determined by the browser. The value of rows does not limit the number of lines that may be entered.
* '''cols''' (mandatory) is the width of the visible text area in characters. If omitted the width is determined by the browser. The value of cols does not limit the number of characters that may be entered.
* '''default''' (optional) (translatable) is the default value.
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.
* '''filter''' (optional) allow the system to save certain html tags or raw data.

Example XML field definition:
<source lang="xml"><field name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" /></source>
Use the raw filter to ensure that html code is preserved when the form is processed:
<source lang="xml"><field name="mytextarea" type="textarea" default="default" label="Enter some html" description="" rows="10" cols="5" filter="raw"/></source>
<noinclude>
=== Tips ===
* If you need to line break just encode <code><br /></code> in the XML config file like this: <code>&lt;br /&gt;</code>
* If you need a new line character in your default value, add <code>&#13;&#10;</code> to the default parameter

=== See also ===
* [[Text form field type]]
* [[Standard form field types|List of standard form field types]]
[[Category:Standard form field types]]</noinclude>

Textarea form field type

2012-02-15T15:40:02Z

Toadster122: /* Tips */

[[Image:Params.textarea.jpg|right]]

{{Ambox|type=notice|text=In Joomla! 1.5, [[Form field|form fields]] were [[Parameter|parameters]]. For that version, you may want to use the corresponding [[Textarea parameter type]].}}

The '''textarea''' form field type provides a text area for entry of multi-line text. If the field has a value saved, this value is displayed when the page is first loaded. If not, the default value (if any) is selected.

* '''type''' (mandatory) must be ''textarea''.
* '''name''' (mandatory) is the unique name of the field.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''rows''' (mandatory) is the height of the visible text area in lines. If omitted the width is determined by the browser. The value of rows does not limit the number of lines that may be entered.
* '''cols''' (mandatory) is the width of the visible text area in characters. If omitted the width is determined by the browser. The value of cols does not limit the number of characters that may be entered.
* '''default''' (optional) (translatable) is the default value.
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'text_area'.
* '''filter''' (optional) allow the system to save certain html tags or raw data.

Example XML field definition:
<source lang="xml"><field name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" /></source>
Use the raw filter to ensure that html code is preserved when the form is processed:
<source lang="xml"><field name="mytextarea" type="textarea" default="default" label="Enter some html" description="" rows="10" cols="5" filter="raw"/></source>
<noinclude>
=== Tips ===
* If you need to line break just encode <code><br /></code> in the XML config file like this: <code>&lt;br /&gt;</code>
* If you need a new line character in your default value, add this <code>&#13;&#10;</code> to the default

=== See also ===
* [[Text form field type]]
* [[Standard form field types|List of standard form field types]]
[[Category:Standard form field types]]</noinclude>

J1.5:Using the JTable class

2011-06-02T17:08:14Z

Toadster122: Tested in Joomla! 1.5.22, and if $row->store is successful, it returns true, not NULL

[[Category:Development]]
== Writing an extension of JTable ==

The [[JTable]] class is an implementation of the [http://en.wikipedia.org/wiki/Active_record_pattern Active Record] design pattern. It is used throughout Joomla! for [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete creating, reading, updating, and deleting] records in the database table.

To use JTable, create an extension of the class. In this example, we have a database table containing recipes.

<pre>
<?php

defined('_JEXEC') or die();

class TableRecipes extends JTable
{
var $id = null;
var $ingredients = null;
var $instructions = null;
var $serves = null;
var $difficulty = null;
var $prep_time = null;
var $cook_time = null;
var $published = 0;

function __construct(&$db)
{
parent::__construct( '#__recipes', 'id', $db );
}
}
</pre>

When naming your class extension, the convention is to prefix it with 'Table', then follow with a [http://en.wikipedia.org/wiki/CamelCase CamelCased] version of the table's name. All of the member variables of your class should match the column names in the database. The default values should be valid according to the table schema For instance, if you have columns that are NOT NULL, you must use a value other than 'null' as the default.

Finally, create a constructor for the class that accepts a reference to the current database instance. This will call the parent constructor which needs the name of the table, the name of the primary key column, and the database instance. The name of the table uses #__ instead of jos_, as the administrator can pick any table prefix desired during Joomla! installation.

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

== Using a JTable class extension ==

Once the table class is in place, you can use it in any Joomla! extension. To include the file, place this line in your extension's source code (use com_nameofyourcomponent in place of com_recipes):

<pre>
JTable::addIncludePath(JPATH_ADMINISTRATOR.DS.'components'.DS.'com_recipes'.DS.'tables');
</pre>

To get an instance of the object, use this code:

<pre>
$row =& JTable::getInstance('recipes', 'Table');
</pre>

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 the object by reference instead of value; use =& to enforce this.

In a model class (extends JModel) you can also use:

<pre>
$row =& $this->getTable('recipes');
</pre>

Notice that if you have not used the standard naming convention, you can supply the class prefix as the optional second parameter.

=== Create/Update ===
In a typical situation, you will have an HTML form submitted by the user which will PHP will interpret for you as an associative array. The JRequest class in Joomla! has functions ready to assist with retrieving this data safely. Use JRequest::get('post') to retrieve all of the elements in the HTTP POST request as a sanitized array.

Once you have this array, you can pass it into the bind() method of JTable. Doing this will match the associated items of the array with member variables of the class. In the following example, the array is retrieved from JRequest::get('post') and immediately passed into bind().

<pre>
if (!$row->bind( JRequest::get( 'post' ) )) {
return JError::raiseWarning( 500, $row->getError() );
}
</pre>

If bind() fails, you want to stop the application and explain the failure before your extension attempts to send the data. The raiseWarning() function of JError allows you to stop Joomla!, while the getError() function returns the error message stored in the JTable object.

When binding succeeds and your object is ready, call the store() function. Again, if something goes wrong, stop the application and explain why.

<pre>
if (!$row->store()) {
JError::raiseError(500, $row->getError() );
}
</pre>

Notes:
* If any member variables of your JTable object are null when store() is called, they are ignored by default. This allows you to update specific columns of your table, while leaving the others untouched. If you wish to override this behavior to ensure that all columns have a value, pass true into store().
* The JTable::bind() and JRequest::get() functions do not enforce data types. If you need a column to be a specific type (for instance, integer), you need to add this logic to your code before calling store().

=== Read ===
To load a specific row of the database with JTable, pass the key into the load() member function.

<pre>
$row->load( $id );
</pre>

This relies on the key column you specified in the second parameter of parent::__construct() when you extended JTable.

=== Delete ===
Like read(), delete() allows you to destroy a specific row in the table based on the key specified earlier.

<pre>
$row->delete( $id );
</pre>

If you want to delete multiple rows at once, you will need to write the query manually.

== Member Functions ==
{{jfr summary|class=JTable|methods=yes}}

== Summary ==
When properly extended, JTable gives you all of the basic functions you need for managing and retrieving records in a database table. Member functions take care of the rest when you add member variables, the table name, and the key column.

J1.5:Using the JTable class

2011-06-02T17:02:49Z

Toadster122:

[[Category:Development]]
== Writing an extension of JTable ==

The [[JTable]] class is an implementation of the [http://en.wikipedia.org/wiki/Active_record_pattern Active Record] design pattern. It is used throughout Joomla! for [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete creating, reading, updating, and deleting] records in the database table.

To use JTable, create an extension of the class. In this example, we have a database table containing recipes.

<pre>
<?php

defined('_JEXEC') or die();

class TableRecipes extends JTable
{
var $id = null;
var $ingredients = null;
var $instructions = null;
var $serves = null;
var $difficulty = null;
var $prep_time = null;
var $cook_time = null;
var $published = 0;

function __construct(&$db)
{
parent::__construct( '#__recipes', 'id', $db );
}
}
</pre>

When naming your class extension, the convention is to prefix it with 'Table', then follow with a [http://en.wikipedia.org/wiki/CamelCase CamelCased] version of the table's name. All of the member variables of your class should match the column names in the database. The default values should be valid according to the table schema For instance, if you have columns that are NOT NULL, you must use a value other than 'null' as the default.

Finally, create a constructor for the class that accepts a reference to the current database instance. This will call the parent constructor which needs the name of the table, the name of the primary key column, and the database instance. The name of the table uses #__ instead of jos_, as the administrator can pick any table prefix desired during Joomla! installation.

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

== Using a JTable class extension ==

Once the table class is in place, you can use it in any Joomla! extension. To include the file, place this line in your extension's source code (use com_nameofyourcomponent in place of com_recipes):

<pre>
JTable::addIncludePath(JPATH_ADMINISTRATOR.DS.'components'.DS.'com_recipes'.DS.'tables');
</pre>

To get an instance of the object, use this code:

<pre>
$row =& JTable::getInstance('recipes', 'Table');
</pre>

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 the object by reference instead of value; use =& to enforce this.

In a model class (extends JModel) you can also use:

<pre>
$row =& $this->getTable('recipes');
</pre>

Notice that if you have not used the standard naming convention, you can supply the class prefix as the optional second parameter.

=== Create/Update ===
In a typical situation, you will have an HTML form submitted by the user which will PHP will interpret for you as an associative array. The JRequest class in Joomla! has functions ready to assist with retrieving this data safely. Use JRequest::get('post') to retrieve all of the elements in the HTTP POST request as a sanitized array.

Once you have this array, you can pass it into the bind() method of JTable. Doing this will match the associated items of the array with member variables of the class. In the following example, the array is retrieved from JRequest::get('post') and immediately passed into bind().

<pre>
if (!$row->bind( JRequest::get( 'post' ) )) {
return JError::raiseWarning( 500, $row->getError() );
}
</pre>

If bind() fails, you want to stop the application and explain the failure before your extension attempts to send the data. The raiseWarning() function of JError allows you to stop Joomla!, while the getError() function returns the error message stored in the JTable object.

When binding succeeds and your object is ready, call the store() function. Unlike the bind() method, the store() method returns null if successful. Again, if something goes wrong, stop the application and explain why.

<pre>
if (!$row->store()) {
JError::raiseError(500, $row->getError() );
}
</pre>

Notes:
* If any member variables of your JTable object are null when store() is called, they are ignored by default. This allows you to update specific columns of your table, while leaving the others untouched. If you wish to override this behavior to ensure that all columns have a value, pass true into store().
* The JTable::bind() and JRequest::get() functions do not enforce data types. If you need a column to be a specific type (for instance, integer), you need to add this logic to your code before calling store().

=== Read ===
To load a specific row of the database with JTable, pass the key into the load() member function.

<pre>
$row->load( $id );
</pre>

This relies on the key column you specified in the second parameter of parent::__construct() when you extended JTable.

=== Delete ===
Like read(), delete() allows you to destroy a specific row in the table based on the key specified earlier.

<pre>
$row->delete( $id );
</pre>

If you want to delete multiple rows at once, you will need to write the query manually.

== Member Functions ==
{{jfr summary|class=JTable|methods=yes}}

== Summary ==
When properly extended, JTable gives you all of the basic functions you need for managing and retrieving records in a database table. Member functions take care of the rest when you add member variables, the table name, and the key column.