Joomla! Documentation - User contributions [en]

Categories and CategoryNodes API Guide

2024-11-27T15:20:31Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to the [https://manual.joomla.org/docs/general-concepts/categories/ Joomla Manual ] instead}}

{{version/tutor|3.x}}

== Introduction ==

The Joomla Categories and CategoryNode APIs enable you to access details of Joomla categories. The diagram below illustrates how the Joomla category classes relate to the database structures.

[[File:Categories.jpg|right|Categories diagram]]

The Joomla Categories table is split into "partitions", one partition for each component which uses categories. (Here "partitions" is used in a loose sense, not related to the technical term "database partition" for example). Within each partition the category records are held within a tree structure, but always associated with the same component – for example, you can't have a com_content category which has as a parent a com_contact category. At the root of the tree is a single system root node, which is the parent of all the top-level category records of the components.

Each component record which is associated with a category holds the id of the category record (as a foreign key), with all the category attributes being held in the category record within the Categories table. (Shown in the diagram using the example of com_contact).

There are 2 Joomla classes (shown in yellow) which provide APIs for accessing category data:
# Categories – This relates to the partition within the Categories table. You must first of all specify which partition you want to access by creating a Categories object and passing the name of the component as a parameter to the constructor.
# CategoryNode – This relates to an individual Category record. Once you have the Categories object you can get access to the CategoryNode objects within that partition.

In your code you can access the category data for several components, through creating several Categories instances, one for each component/partition.

== Categories ==
To get access to the set of categories for com_content use:

<source lang="php">
use Joomla\CMS\Categories\Categories;
$extension = "content";
$categories = Categories::getInstance($extension);
// The above replaces the older format $categories = JCategories::getInstance($extension);
$categoryNodes = $categories->get(12); // returns the category node for category with id=12
</source>

Note that you don't have the usual "com_" prefix in the extension.

You can provide an associative array of options as a second parameter to the Categories static <tt>getInstance()</tt> method. The keys of this array are:
* "access" – if this is true (or some value which equates to PHP true) then only categories which the current user has access to view will be returned. If false then all categories will be returned, regardless of whether the current user has access to view them or not. The default is true.
* "published" – if this is 1 (integer one) then only categories which have a published state of 1 (ie 'published') will be returned. Otherwise categories of any state will be returned. The default is 1, meaning that only 'published' categories will be returned.
* "countitems" – if this is 1 (integer one) then when categories are returned Joomla will determine for each category record how many of the extension records are associated with that category (the default is not to count the items). To do this, Joomla will do a SQL JOIN with the extension table, WHERE the category id field in that table matches, and COUNTing the instances of a "key" field in that table. Joomla needs to know what these tables and fields are called, and these can be provided in the array options below.
* "table" – the name of the extension table. There is no default, so you must supply this if you're using "countitems".
* "field" – the name of the field in the extension table which holds the category id (default "catid")
* "key" – the name of the key field in the extension table over which the SQL COUNT is performed (default 'id').
* "statefield" – the name of the field in the extension table which holds the published status of the record (default 'state'). If Joomla is returning only published categories (as determined by the "published" option described above) then it will count over just published items in the extension table as well. (Note that the equivalent is NOT done for "access" – any Access field in the extension table is ignored).

Examples:
<source lang="php">
$categories = Categories::getInstance("content", array("access" => false, "published" => 0));
</source>
Category nodes returned will not be restricted by Access or the Published state.

<source lang="php">
$categories = Categories::getInstance("helloworld", array("countitems" => 1, "table" => "helloworld", "statefield" => "published"));
</source>
Category nodes of the "helloworld" component will include the number of associated records in the "helloworld" table, where the published state is held in a field called "published".

The Categories <tt>get()</tt> method takes as its first parameter the <tt>id</tt> of the category record to be read from the database and returns to the caller the corresponding CategoryNode object. If no <tt>id</tt> is given, then the method returns the CategoryNode object relating to the system ROOT record at the very top of the category tree in the database.

The <tt>get()</tt> functionality actually reads from the database all the ascendents of the requested category record up to the category root record (which enables the Category Path described below to be determined), as well as all the descendants of the requested category record. It then stores these locally so that subsequent calls to obtain data for any of those children can be served by returning the data from this cache rather than performing another query on the database.

However, if the second parameter <tt>$forceload</tt> is set to true, then it will service the request by querying the database again, rather than using the cached records.

In a multilanguage site the categories returned will be restricted to those of the current language or language * (for all). Similarly, any counting of items in the extension table will be restricted to those of the current language or language *, and Joomla will assume that the language is stored in field called "language" (you can't override what this language field is called).

== CategoryNode Properties ==

The object from a call to the Categories <tt>get($id)</tt> method will be a CategoryNode object relating to the category with id <tt>$id</tt>. If you called <tt>get()</tt> using the default of 'root' then you will have to make a subsequent call to <tt>getChildren()</tt> to get an array of CategoryNode objects for the extension you want, eg:

<source lang="php">
use Joomla\CMS\Categories\Categories;
use Joomla\CMS\Categories\CategoryNode;

$categories = Categories::getInstance("content");
$rootNode = $categories->get();
$categoryNodes = $rootNode->getChildren();
</source>

Once you have a CategoryNode object you can access the properties of this object as defined in the API definition, and these mostly relate closely to the category attributes visible in the Joomla admin forms. Properties where the meaning is fairly clear are not described below, but below is a list of those where the meaning may not be totally apparent.

* asset_id – where the administrator has defined ACLs for the individual category, then this is the id of the record in the asset table where these ACLs are stored.

* parent_id, lft, rgt, level – these fields relate to the category's position in the category tree, which is implemented using the [https://en.wikipedia.org/wiki/Nested_set_model Nested Set] model. The lft and rgt values are implemented as required by the model, the parent_id is the id of the parent record in the category table (NOT in the asset table – this is a typo in the Joomla code), and the level is 0 for the root node, 1 for those records whose parent is the root node, 2 for the next level of descendants, etc.

* extension – this time the "com_" prefix is present

* numitems – the number of records in the extension table which are associated with this category

* childrennumitems – this isn't set – don't try to use it!

* slug – this is what Joomla has traditionally displayed as part of the URL when SEF URLs are displayed. It's of the form id:alias, for example 3:uncategorised.

* assets – this isn't set – don't try to use it!

== CategoryNode get Methods ==

A number of the CategoryNode get methods enable you to access other CategoryNode objects in the tree:

* <tt>getChildren(boolean $recursive = false)</tt> returns an array of the immediate children, or an array of all the descendants if <tt>$recursive = true</tt>.

* <tt>getParent()</tt> returns the parent CategoryNode

* <tt>getSibling(boolean $right = true)</tt> returns the sibling CategoryNode to the right, or to the left if <tt>$right = false</tt>.

A number of the get methods return properties of the CategoryNode object

* <tt>getAuthor(boolean $modified_user = false)</tt> returns the User object associated with the user who created the category, or the user who last modified the user if <tt>$modified_user = true</tt>

* <tt>getMetadata()</tt> returns a Joomla Registry object containing the category metadata (json structure)

* <tt>getParams()</tt> returns a Joomla Registry object containing the category params (json structure)

* <tt>getNumItems(boolean $recursive = false)</tt> returns the number of records in the extension table which are related to this category. If <tt>$recursive = true</tt> then it's the total number of records associated with this category and all of this category's descendants.

* <tt>getPath()</tt> returns an array of the slugs going from the root of the category tree down the tree to this category. For example, if this category has id 9 and alias "dog", it's parent has id 6 and alias "mammal", and grandparent (immediately below the root) has id 3 and alias "animal" then <tt>getPath()</tt> will return <tt>array(3 => "3:animal", 6 => "6:mammal", 9 => "9:dog")</tt>.

Note that <tt>hasParent()</tt> includes the parent being the root node, so that a call to this method will always return <tt>true</tt> unless you're calling it on the root node.

== CategoryNode set Methods ==

There are a number of <tt>set</tt> methods of the CategoryNode API, but these are primarily used by the Joomla category functionality to set up the CategoryNode objects, based on data retrieved from the database. Calling one of these does not persist the data to the database, eg you can't use <tt>setParent()</tt> to reparent a category record under a different category parent in the database.

== Sample Module Code ==

Below is the code for a simple Joomla module which you can install and run to demonstrate use of the Categories and CategoryNode API functionality. If you are unsure about development and installing a Joomla module then following the tutorial at [[S:MyLanguage/J3.x:Creating a simple module/Introduction| Creating a simple module ]] will help.

In a folder mod_sample_categories create the following 2 files:

<tt>mod_sample_categories.xml</tt>
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>Categories demo</name>
<version>1.0.1</version>
<description>Code demonstrating use of Joomla APIs related to Categories</description>
<files>
<filename module="mod_sample_categories">mod_sample_categories.php</filename>
</files>
</extension>
</source>

<tt>mod_sample_categories.php</tt>
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;
use Joomla\CMS\Categories\Categories;
use Joomla\CMS\Categories\CategoryNode;

$app = Factory::getApplication();
$input = $app->input;
$ext = $input->get('categoryextension', "Content", "STRING");
$tab = $input->get('categorytable', "Content", "STRING");
echo "Getting {$ext} categories and using {$tab} table<br>";
echo "-------------<br>";

$categories = Categories::getInstance($ext, array("table" => "Content", "countItems" => 1, "access" => false));

$cat0 = $categories->get('root');

$cats = $cat0->getChildren(true);
foreach ($cats as $cat)
{
echo "Category {$cat->id}, title: {$cat->title}<br>";
echo "Level: {$cat->level}, parent id: {$cat->parent_id}<br>";
echo "Numitems {$cat->getNumitems()}, including descendants: {$cat->getNumitems(true)}<br>";
var_dump($cat->getPath());
echo "-------------<br>";
}

$ext2 = $input->get('option', "", "STRING");
$catid = $input->get('catid', 0, "INT");
$view = $input->get('view', "", "STRING");
$id = $input->get('id', 0, "INT");
if ($ext2 && (strtolower(substr($ext2, 0, 4)) == "com_") && ($catid || (strtolower($view) == "category" && $id)))
{
$ext2 = substr($ext2, 4);
$categories2 = Categories::getInstance($ext2, array("access" => false));
$categoryId = $catid ? $catid : $id;
echo "<br>Getting $ext2 category $categoryId<br>";
$cat2 = $categories2->get($categoryId);
if ($cat2)
{
echo "Category {$cat2->id}, title: {$cat2->title}<br>";
}
}
</source>

Zip up the mod_sample_categories directory to create <tt>mod_sample_categories.zip</tt>.

Within your Joomla administrator go to Install Extensions and via the Upload Package File tab select this zip file to install this sample categories module.

Make this module visible by editing it (click on it within the Modules page) then:
# making its status Published
# selecting a position on the page for it to be shown
# on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position, and it should show the set of com_content categories in the database and for each category:
* the id and title
* the level in the category tree and the id of the parent
* the number of articles which have this category set, and the number of articles which have this category or any of the category's descendants
* a <tt>var_dump</tt> of the category <tt>getPath()</tt> return value.

You can get categories for other components by adding the parameters <tt>categoryextension</tt> and <tt>categorytable</tt> to the URL, eg <tt>...&categoryextension=contact&categorytable=contact_details</tt> to get com_contact categories. Note that if you're trying to get the categories of a component which isn't one of the core Joomla components, then you may need to supply the component field names etc within the <tt>options</tt> to the <tt>Categories::getInstance()</tt> call, as described above.

The code also tries to guess if the page displayed relates to a category, by checking if there's a <tt>catid</tt> parameter in the URL, or if the <tt>view</tt> parameter is set to 'category'. In this case it shows the id and title of the associated category. Obviously this may not work correctly in all cases.

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]

Menu and Menuitems API Guide

2024-11-27T11:04:48Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to the [https://manual.joomla.org/docs/general-concepts/menus-menuitems/ Joomla Manual ] instead}}

{{version/tutor|3.x}}

== Introduction ==

This is one of a series of [[API Guides]] to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

In Joomla a Menu is the set of navigation links you can have as a main menu (e.g. at the top of your site) or subsidiary menu (e.g. in the footer). Each of the individual navigation links is a menu item.

Within an overall Menu structure you can have a "submenu". This isn't implemented as a Joomla Menu construct, rather as a set of menu items below a parent menu item. The Joomla menu items are thus implemented in an ordered tree structure, specifically using the [https://en.wikipedia.org/wiki/Nested_set_model Nested Set model].

This guide explains the Joomla API around the Menu/Menuitem area and includes sample module code which you can install on your site as a demonstration of the capabilities.

== Basic Operations ==
There isn't a Joomla API to enable you to get the set of Menus on the system, so if you really do need these then your only recourse is to read the data from the ''menu_types'' table directly using a SQL query. But you can find from the menu item structure described below the Menu to which that menu item belongs and find all the menu items for a particular Menu.

When the Joomla application starts up in response to an HTTP request arriving at a Joomla site, it builds up a big structure containing lots of things which it realises will likely be needed during the process of working out what will be displayed on the web page. Within this structure it includes all the menu items which may be needed. To get at this structure do:

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
$app = Factory::getApplication();
$sitemenu = $app->getMenu();
</syntaxhighlight>

The ''$sitemenu'' structure will have entries for all the menu items (plus access to a lot of other information besides, but which doesn't concern us).

To get at the individual menu items we apply a filter to ''$sitemenu'' using ''getItems()'' to select the particular menu items we're interested in. To obtain an array of all the menu items use a blank filter:

<syntaxhighlight lang="php">
$menuitems = $sitemenu->getItems(array(), array());
</syntaxhighlight>

To obtain an array of all the menu items which are in the "mainmenu" menu use:

<syntaxhighlight lang="php">
$mainmenuItems = $sitemenu->getItems('menutype', 'mainmenu');
</syntaxhighlight>

The above gives all the menu items within the "mainmenu" menu, including those in submenus. To access just the menu items which are in the topmost or first submenu level of the "mainmenu" menu use:

<syntaxhighlight lang="php">
$mainmenuItems = $sitemenu->getItems(array('menutype','level'), array('mainmenu',array("1","2")));
</syntaxhighlight>

To filter the specific menu items you want, you pass an array of properties (from the list in the next section) and an array of corresponding values which those properties should have.

Unpublished menu items are not returned. They're not included within the ''$sitemenu'' structure.

Note that there isn't an equivalent method to get the menu items on the administrator back-end, as the equivalent structure to ''$sitemenu'' above isn't populated with the admin menu structure. If you wanted to access the menu details you would have to read and interpret the appropriate records from the database.

== Properties and Parameters ==

The following are available as public properties of the ''Menuitem'' class. Most of these are shown in the first tab ("Details") of the "Menus: Edit Item" form when you're editing a menu item within the back end. Once you have a ''Menuitem'' object you can access the properties directly, as shown below.

<syntaxhighlight lang="php">
$menuitems = $sitemenu->getItems(array(), array());
foreach ($menuitems as $menuitem)
{
echo "Itemid: {$menuitem->id}";
}
</syntaxhighlight>

* '''id''' – this is the id of the menu item. In Joomla code its usually referred to as the Itemid, probably to distinguish it from the id of, for example, an article (as both often appear in URLs when not using SEF URLs)
* '''menutype''' – this identifies the Menu which the menu item belongs to. It's a unique identifier Menu Type which you assign to a menu
* '''title''' – what will be displayed when the menu item is shown on the menu (called the "Menu Title" in the form).
* '''alias''' – the segment of the URL when using SEF URLs
* '''note''' – the optional note shown on the form
* '''route''' – the section of the SEF URL which gets to this menu item. For example if the alias of this menu item is "me", the alias of its parent is "dad" and of its grandparent (at the top level of the menu) is "gran" then the route returned is "gran/dad/me".
* '''link''' – the link shown in the Link field of the form
* '''type''' – usually this will be "component" and the link will point to component functionality in Joomla. But it may also be one of the following, when the Menu Item Type selected is one of the System Links:
** '''"heading"''' – Menu Heading – a heading for the parent of submenu items
** '''"alias"''' – Menu Item Alias – an alias to another menu item
** '''"separator"''' – Separator – a text string (e.g. dashes) to separate items in a menu
** '''"url"''' – URL – a link to an external URL.
* '''level''' – the level within the menu item tree. The "root" entry at the base of the tree is level "0", menu items at the top level in a menu have level "1", first submenu level "2", etc.
* '''language''' – the language code. For example, "es-ES"
* '''browserNav''' – the value associated with the option entered in the Target Window field of the form. Generally this means the following;
** ''' 0''' – Parent – the link opens in the same tab
** '''1''' – New Window with Navigation – the link opens in a new tab
** '''2''' – New Window without Navigation – the link opens in a new window
* '''access''' – the id of the AccessLevel assigned to this menu item. When you use this API it checks the logged on user and returns only those menu items which this user is permitted to view.
* '''home''' – whether or not this is a home page ("Default Page") for the site or language.
* '''img''' – this doesn't seem to be used any more. You can specify an image to be used in the menu item, but this is now specified in the Link Type tab in the form and stored in the params "menu_image" field.
* '''template_style_id''' – the id of the Template Style entered in the form
* '''component_id''' – the id of the component associated with this menu item
* '''parent_id''' – the id of the parent in the menu item tree
* '''component''' – the name of the associated component, e.g. "com_contact"
* '''tree''' – an array of the menu item ids getting to this menu item in the tree. If this menu item has id 789, its parent id 456 and grandparent 123, where the grandparent is on the topmost menu (ie its parent is the root node), then tree returned will be an ''array ("123", "456", "789")''.
* '''query''' – an associative array of the query parameters shown in the Link field on the form. For example for a menu item pointing to a single article this will be of the form: ''array("option" => "com_content", "view" => "article", "id" => "123")''.

All the other attributes of the menu item are stored in the params field in the database and accessed using the ''getParams()'' method. These are too many and varied to specify completely here. Two examples are shown below:

<syntaxhighlight lang="php">
$params = $menuitem->getParams();
$displayed = $params->get("menu_show");
$show_tags = $params->get("show_tags");
</syntaxhighlight>

The ''$displayed'' variable will hold a boolean depending on whether this menu item should be shown in the menu or hidden, corresponding to the setting of the "Display in Menu" field in the Link Type tab in the form.

The ''$show_tags'' variable will hold a boolean defining whether or not to show tags associated with the item being displayed. However the presence of this field will depend on what is being presented on the web page which the menu item points to. If it's an article or contact then it's relevant and may be set, but if it's a link to a Search Form or Search Results then it isn't relevant and will not be set.

Some of these parameters (e.g. those defined in the Link Type tab of the menu item edit form) may be defined for menu items in general, although the specific fields stored depend on the Menu Item Type selected (ie ''type'' property in the list of properties above). To find these look in the Joomla code under ''administrator/components/com_menus/model/form/item_???.xml'', replacing ??? by the ''type''. These xml files provide definitions of parts of the "Menus: Edit Item" form and you can find in them the name of the attribute which is stored in the params json string in the database and accessed programmatically via the ''getParams()->get()'' method.

Other parameters are related to the component which is navigated to via this menu item and contain attributes which related to how the output of that component is displayed on that particular web page. To find these locate the ''.xml'' file in the folder where the layout file for that particular page is held. For example, for a page displaying a single contact look in ''components/com_contact/contact/tmpl''. (See the Joomla Component MVC Tutorial step [[J3.x:Developing an MVC Component/Adding a variable request in the menu type|Adding a variable request in the menu type]] for an example showing how components define the options to be shown against menu items).

== Getting Individual Menu Iitems ==

As well as the mechanisms described above for filtering down to the menu item(s) you want, there are some methods available to get directly to certain menu items.

=== Active Menu Item ===

The active menu item of a site web page relates to the menu item which Joomla is using to determine the presentation of that page (e.g. using the Template Style defined for the menu item). To find this use:

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
$app = Factory::getApplication();
$sitemenu = $app->getMenu();
$activeMenuitem = $sitemenu->getActive();
</syntaxhighlight>

You can then get the properties and parameters of this menu item as described above.

However, note that there are unusual cases where (in Joomla 3.x at least) the active menu item is not set. You can show this by configuring your site as described below and using the sample module code included at the end of this page which outputs the active menu item Itemid.

Set up your site as an international site (e.g. using the multi-language installation option) and ensure you've got the menu switcher module being displayed. Then create for example:
* a contact "John" with language "English"
* a contact "Jean" with language "French"
* associate together these 2 contacts via the Contact Associations feature
* an "english" menu which contains a menu item with language "English" pointing to the contact "John"
* a "french" menu but which has no menu items relating to Contacts.
Display on your site the English menu and click on the contact menu item to show "John". Then click on the French flag in the menu switcher module. This should display the "Jean" contact, but have no active menu item. Joomla is displaying the French contact (as it's associated to the English one), but can find no menu item relating to contacts and so uses a default mechanism for presenting the page, but doesn't have an active menu item. In general it seems that if you use a menu item for component A but force it to present component B (by setting the "option" parameter to override the default option associated with a menu item) then the active menu item is not set.

=== Default Menu Item ===
To find the default menu item for a language use for example:

<syntaxhighlight lang="php">
$lang = "es-ES"; // or $lang = "*" for all languages
$defaultMenuitem = $sitemenu->getDefault($lang);
</syntaxhighlight>

=== Menu Item from Itemid ===
If you wish to find the menu item associated with a specific id ''$itemid'' use:

<syntaxhighlight lang="php">
$menuitem = $sitemenu->getItem($itemid);
</syntaxhighlight>

== Setting Menu Items ==
You can set menu item properties and parameters using for example:

<syntaxhighlight lang="php">
$menuitem->setParams($params) //set the params values

$sitemenu->setActive($itemid) // set the active menu item
</syntaxhighlight>

or by simply assigning different values to the menu item public properties. However these changes are not saved to the database and will last only for the duration of handling the current HTTP request.

== Sample Module Code ==
Below is the code for a simple Joomla module which you can install and run to demonstrate use of the menu item API functionality. If you are unsure about development and installing a Joomla module then following the tutorial at [[S:MyLanguage/J3.x:Creating a simple module/Introduction| Creating a simple module ]] will help.

In a folder mod_sample_menu create the following 2 files:

''mod_sample_menu.xml''
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>Menu demo</name>
<version>1.0.1</version>
<description>Code demonstrating use of Joomla APIs related to Menus and Menu Items</description>
<files>
<filename module="mod_sample_menu">mod_sample_menu.php</filename>
</files>
</extension>
</syntaxhighlight>

''mod_sample_menu.php''
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;

$app = Factory::getApplication();
$input = $app->input;

$sitemenu = $app->getMenu();

if ($activeMenuitem = $sitemenu->getActive())
{
echo "Active menuitem is Itemid: {$activeMenuitem->id}<br>";
}
else
{
echo "No active menuitem<br>";
}

if ($input->exists('menulanguage'))
{
$lang = $input->get('menulanguage', "", "STRING");
}
else
{
$lang = Factory::getLanguage()->getTag();
}
echo "Getting details for language {$lang}<br>";

$menuitems = $sitemenu->getItems(array("language"), array($lang));

echo "<br>---- properties of menuitems ----<br>";
foreach ($menuitems as $menuitem)
{
echo "<br>Itemid: {$menuitem->id}, title: {$menuitem->title}, type: {$menuitem->type}<br>";
echo "<br>Language: {$menuitem->language}, level: {$menuitem->level}<br>";
$params = $menuitem->getParams();
if (!($displayed = $params->get("menu_show")))
{
echo "This menu item is hidden<br>";
}
if ($img = $params->get("menu_image"))
{
$imgURL = JURI::root() . $img;
echo "Image: {$img}<br><img src='{$imgURL}'><br>";
}
}
</syntaxhighlight>

Zip up the mod_sample_menu directory to create ''mod_sample_menu.zip''.

Within your Joomla administrator go to Install Extensions and via the Upload Package File tab select this zip file to install this sample menu module.

Make this module visible by editing it (click on it within the Modules page) then:
# making its status Published
# selecting a position on the page for it to be shown
# on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position and it should show
* the Itemid of the current active menuitem,
* a set of properties associated with menu items having the current language,
* a couple of attributes from the params (displaying if the menu item is hidden and any image associated with a menu item).
You can get it to display the properties and parameters for other languages by adding a URL parameter like ''?menulanguage=fr-FR''.

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]

Retrieving request data using JInput

2024-11-27T10:48:27Z

Robbiej: Added deprecation notice and link to Joomla Manual

Creating a custom form field type

2024-11-27T10:47:02Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to the [https://manual.joomla.org/docs/general-concepts/forms-fields/custom-fields-overview/ Joomla Manual ] instead}}

<noinclude><languages /></noinclude>

<noinclude>{{Joomla version|version=3.x|comment=<translate>
series</translate>}}</noinclude>
{{-}}
{{page|needs review}}

<translate>

[https://api.joomla.org/cms-3/classes/Joomla.CMS.Form.Form.html JForm], a feature introduced in Joomla! 2.5, lets you easily create HTML forms (''<form>''). Forms created using JForm consist of [[S:MyLanguage/Form field|form fields]], implemented as [https://api.joomla.org/cms-3/classes/Joomla.CMS.Form.FormField.html JFormField]. There is a JFormField for each different field type you can find in a form, such as a text field type and a date field type. JForm supports a large selection of standard field types. For a full list, see [[S:MyLanguage/Standard form field types|Standard form field types]].
</translate>

<translate>

Joomla! makes it possible to extend standard field types or define your own. For example, if your component manages phone book entries, you might want to define a form field type that outputs a select list of cities. There are several advantages to defining a custom form field type:
</translate>

<translate>

* You will be able to mix standard field types with your custom field type in a JForm-based form.
* You will eventually have a reusable code package that can be used easily throughout your code.
* Extensions that collaborate with your extension will be able to create form fields without meddling with your database tables and other internals.
</translate>

<translate>
== Form Field Type Class Requirements == 
</translate>

<translate>

A form field type is defined in a [[wikipedia:Class (computer programming)|class]] that must be a (not necessarily direct) subclass of JFormField. To work correctly, the class must define at least three methods:
</translate>

* ''public function getLabel()''
<translate>
*: This function will be called to create the label that belongs to your field and must return an HTML string containing it. Since JFormField defines a ready-to-use ''getLabel()'' implementation, custom form field types usually do not define their own ''getLabel()''. If you leave it out, the inherited method of creating labels will be used. It is recommended to leave out the ''getLabel()'' method for consistency and speed unless you actually want to modify the label's HTML.</translate>
* ''public function getInput()''
<translate>
*: This function will be called to create the field itself and must return an HTML string containing it. This is also where most of the processing usually happens. In our phone book City field example, this function will have to retrieve a list of available cities and return an HTML ''<select>'' with the cities inserted as ''<option>''s.</translate>
* ''public function getValue()''
<translate>
*: This function will be called to get the field value. The value is obtained from the function LoadFormData in the Model</translate>
<translate>

Inside your code, you will have to process the attributes set by the field's user in the XML form definition. Some of those attributes are accessible via protected member variables of JFormField. For example, the ''name'' attribute is available in your code as ''$this->name''. Similarly, ''label'', ''description'', ''default'', ''multiple'' and ''class'' are also available as properties of ''$this''. Other parameters you might have defined can be accessed through the ''$this->element'' array: the attribute ''size'' will be in ''$this->element['size']''.
</translate>

<translate>
== Which Class to Subclass? == 
</translate>

<translate>

For a form field type to be usable in JForm, it needs to be a subclass of JFormField. However, it does not have to be a direct child of that class. You can also subclass an existing (standard or custom) form field type and thereby inherit useful code.
</translate>

<translate>

If your form field type is similar to an existing type, you '''should''' subclass that type. Especially if your form field type is a ''list'', please subclass [https://api.joomla.org/cms-3/classes/JFormFieldList.html JFormFieldList]. You only have to override ''getOptions()'' method to return the options to be shown. The ''getInput()'' method will convert those options to HTML.
</translate>

<translate>
To subclass an existing type, for example JFormFieldList, load it by adding the following after ''jimport('joomla.form.formfield');'':</translate>

<syntaxhighlight lang="php">
jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');
</syntaxhighlight>

<translate>
If your form field type is unlike any existing type, subclass ''JFormField'' directly.</translate>

<translate>
== Location of Files == 
</translate>

<translate>
* The standard form field types are located in ''libraries/joomla/form/fields/''. You should not store custom fields there, nor should you have to use this path in your own code. The standard types are usually good examples.</translate>
<translate>
* The custom field types that belong to your component are usually located in ''administrator/components/<name of your component>/models/fields''. You can specify this or another path in your code:</translate>
<syntaxhighlight lang="php">JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');</syntaxhighlight>
<translate>
* The XML files that define forms are usually located in ''administrator/components/<name of your component>/models/forms''. Use something like the following snippet to specify a path to your forms:</translate>
<syntaxhighlight lang="php">JForm::addFormPath(JPATH_COMPONENT . '/models/forms');</syntaxhighlight>

<translate>
== Naming Conventions and Skeleton == 
</translate>

<translate>
In this section, <ComponentName> represents the camel-cased name of your component and <FieldName> represents the camel-cased name of your form field type. The field's class should be placed in ''administrator/components/<name of your component>/models/fields/<name of your field>.php'', and look like this:</translate>

<syntaxhighlight lang="php"><?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

jimport('joomla.form.formfield');

// The class name must always be the same as the filename (in camel case)
class JFormField<FieldName> extends JFormField {

//The field class must know its own type through the variable $type.
protected $type = '<FieldName>';

public function getLabel() {
// code that returns HTML that will be shown as the label
}

public function getInput() {
// code that returns HTML that will be shown as the form field
}
}
</syntaxhighlight>

<translate>
=== Grouping Custom Field Types === 
</translate>

<translate>
'''Warning: this information is partially incorrect and needs to be improved.'''</translate>

<translate>
Custom field types can be grouped by using an underscore in the field name. A field class with a name for example like "JFormFieldMy_randomField" must be stored in ''administrator/components/<name of your component>/models/fields/my/randomField.php''. We can prefix our form field names with some group name, then we put an underscore and then a name of a field.</translate>

<translate>
== An Example Custom Field Type == 
</translate>

<translate>
Suppose you're working on your component named ''com_phonebook'' and you want to define a field that contains cities. Create the file ''administrator/components/com_phonebook/models/fields/city.php'' and write something similar to the following:</translate>

<syntaxhighlight lang="php"><?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

jimport('joomla.form.formfield');

class JFormFieldCity extends JFormField {

protected $type = 'City';

// getLabel() left out

public function getInput() {
return '<select id="'.$this->id.'" name="'.$this->name.'">'.
'<option value="1" >New York</option>'.
'<option value="2" >Chicago</option>'.
'<option value="3" >San Francisco</option>'.
'</select>';
}
}
</syntaxhighlight>

<translate>

A more advanced approach is extending the ''JFormFieldList'' class. Suppose you want to create a drop-down of cities dynamically from database based on a dynamic condition. You can do this in the following way:</translate>

<syntaxhighlight lang="php"><?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

JFormHelper::loadFieldClass('list');

class JFormFieldCity extends JFormFieldList {

protected $type = 'City';

public function getOptions() {
$app = JFactory::getApplication();
$country = $app->input->get('country'); //country is the dynamic value which is being used in the view
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('a.cityname')->from('`#__tablename` AS a')->where('a.country = "'.$country.'" ');
$rows = $db->setQuery($query)->loadObjectlist();
foreach($rows as $row){
$cities[] = $row->cityname;
}
// Merge any additional options in the XML definition.
$options = array_merge(parent::getOptions(), $cities);
return $options;
}
}
</syntaxhighlight>

<translate>
The above example shows a simple query which will show a list of cities from a table where city name belongs to its country respectively. You can create a drop-down based on more complex queries.</translate>

<translate>
== Setting the Values of a List Option and Using JSON or an API Instead of a Database Call == 
</translate>
<translate>

If you want to use an API call instead of a database call to build a custom list item, use the following code.


This field was created in a module. To get it to work it needs to be saved to
''mod_modulename/models/fields/stackexchangesites.php''.
The naming convention is important as it is used within our function name.</translate>
<syntaxhighlight lang="php">
<?php
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

// call the list field type
JFormHelper::loadFieldClass('list');

// The class name must always be the same as the filename (in camel case)
// extend the list field type
class JFormFieldStackexchangesites extends JFormFieldList
{
//The field class must know its own type through the variable $type.
protected $type = 'Stackexchangesites';

// get the options for the list field
public function getOptions()
{
// insert your JSON here or else call an API
$json = {"api_site_parameter":"meta.stackoverflow","site_url":"https://meta.stackoverflow.com"~}
// decode the JSON
$sites = json_decode($json, true);

// use a for each to iterate over the JSON
foreach($sites['items'] as $site)
{
// choose the element of the JSON we want, and set it as a variable so we can use it in our array.
$site = $site['api_site_parameter'];
$site_url = $site['site_url'];
// set an array and start adding values to it. Set another array within our array to set our value / text items.
$stackExchangesSitesOptions[] = array("value" => $site, "text" => $site_url);
}

// Merge any additional options in the XML definition.
$options = array_merge(parent::getOptions(), $stackExchangesSitesOptions);
return $options;
}
}</syntaxhighlight>
<translate>

On the Frontend simply calling the parameter gets us the value.</translate>
<syntaxhighlight lang="php">
$stackexchangesites = $params->get('stackexchangesites');
</syntaxhighlight>

<translate>
=== Pitfalls === 
</translate>
<translate>
Loading a custom field can result in a Fatal Error if a core field exists with the same filename and the custom field extends the core field.</translate>

<translate>
Consider a file ''testfields/radio.php'' containing</translate>
<syntaxhighlight lang="php">
<?php
class TestFormFieldRadio extends JFormFieldRadio {}
</syntaxhighlight>

<translate>
Calling ''JFormHelper::loadFieldClass('radio')'' will yield a Fatal error: Class 'JFormFieldRadio' not found.</translate>

<translate>
There are two reasons for this.</translate>

<translate>
# JLoader cannot autoload ''JFormFieldRadio'' because the class name (''JFormField*'') does not match the path name (''joomla/form/fields/*'' - notice the plural on fields).</translate>
<translate>
# JFormHelper cannot load ''JFormFieldRadio'' because custom paths are scanned first and the requested field type('radio') gets resolved before the core classes are reached.</translate>

<translate>
'''Solution'''</translate>

<translate>
Require the core field file directly:</translate>

<syntaxhighlight lang="php">
<?php
require_once JPATH_LIBRARIES . '/joomla/form/fields/radio.php';

class TestFormFieldRadio extends JFormFieldRadio {}
</syntaxhighlight>

<translate>
and use ''JFormHelper::loadFieldClass'' properly with 'test.radio' instead of 'radio'.</translate>

<translate>
=== Using the Custom Field Type === 
</translate>
<translate>
==== Linked with a Form ==== 
</translate>
<translate>
To use the field type City, we need to update the XML file that contains the form fields. Open your XML file located in ''administrator/components/com_phonebook/models/forms'' and add the field in the usual way:</translate>

<syntaxhighlight lang="xml"><field name="title" type="City" label="JGLOBAL_TITLE"
description="JFIELD_TITLE_DESC"
required="true" /></syntaxhighlight>

<translate>
The attribute name is cAsE-sEnSiTiVe.</translate>

<translate>
In addition, you may need to add the field path to the parent <fieldset>:</translate>

<syntaxhighlight lang="xml">
<fieldset addfieldpath="/administrator/components/<component name>/models/fields">
</syntaxhighlight>

<translate>
==== Not Linked with a Form ==== 
</translate>
<translate>
For example, when you need the field as a dropdown in a component as admin/site filter.</translate>

<syntaxhighlight lang="php">
//Get custom field
JFormHelper::addFieldPath(JPATH_COMPONENT . '/models/fields');
$cities = JFormHelper::loadFieldType('City', false);
$cityOptions=$cities->getOptions(); // works only if you set your field getOptions on public!!
</syntaxhighlight>

<translate>
== Overriding ''getLabel()'' == 
</translate>

<translate>
As mentioned in the section [[#Form field type class requirements|Form field type class requirements]], custom form field types usually do not define their own ''getLabel()''. If you do want to create a custom label, you can still make use of the ''getLabel()'' that every field type class inherits from JFormField by defining it as follows:</translate>

<syntaxhighlight lang="php">public function getLabel() {
return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
} </syntaxhighlight>

<translate>
This code will underline your form labels. (Please note that if your goal is to underline form labels, using [[CSS]] is the preferred way.)


If you want to do something completely different, you can of course also override it completely:</translate>

<syntaxhighlight lang="php">public function getLabel() {
// Initialize variables.
$label = '';
$replace = '';

// Get the label text from the XML element, defaulting to the element name.
$text = $this->element['label'] ? (string) $this->element['label'] : (string) $this->element['name'];

// Build the class for the label.
$class = !empty($this->description) ? 'hasTip' : '';
$class = $this->required == true ? $class.' required' : $class;

// Add replace checkbox
$replace = '<input type="checkbox" name="update['.$this->name.']" value="1" />';

// Add the opening label tag and main attributes attributes.
$label .= '<label id="'.$this->id.'-lbl" for="'.$this->id.'" class="'.$class.'"';

// If a description is specified, use it to build a tooltip.
if (!empty($this->description)) {
$label .= ' title="'.htmlspecialchars(trim(JText::_($text), ':').'::' .
JText::_($this->description), ENT_COMPAT, 'UTF-8').'"';
}

// Add the label text and closing tag.
$label .= '>'.$replace.JText::_($text).'</label>';

return $label;
}</syntaxhighlight>

<translate>
This example will add a checkbox inside the label.</translate>

== Sample Component Code ==
Below is the code for a small component which you can install and run and can adapt to experiment further with custom fields. The component includes two custom fields
# A "City" field as described above (except that the options are hard-coded rather than being selected from a database). We'll also allow multiple Cities to be selected and pre-select two of them as default.
# A custom "time" field which maps to the HTML "time" input type and includes underlining the label and support for setting a minimum and maximum time.

Create the following five files in a folder called com_custom_fields. Then zip up this folder to create com_custom_fields.zip. Install this component on your Joomla instance. Once installed, navigate on your browser to your Joomla site and add to the URL the parameter ''&option=com_custom_fields''. This should display the form with the two custom fields. You can submit the form and see the HTTP POST parameters using the browser development tools but the component doesn't contain any code which handles those parameters.

(As described in [[Basic_form_guide#MVC_and_other_considerations|Basic form guide]], the approach below isn't the recommended way to design Joomla components but it's written in this minimalist fashion to focus on the custom fields aspects).

''com_custom_fields.xml'' The manifest file for the component.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

<name>com_custom_fields</name>
<version>1.0.0</version>
<description>Custom Fields demo component</description>

<administration>
</administration>

<files folder="site">
<filename>custom_fields.php</filename>
<filename>form_definition.xml</filename>
<filename>City.php</filename>
<filename>Time.php</filename>
</files>
</extension>
</syntaxhighlight>

''custom_fields.php'' The main code file which is run when an HTTP GET or POST is directed towards this component.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Form\Form;

$form = Form::getInstance("sample", __DIR__ . "/form_definition.xml", array("control" => "jform"));
Form::addFieldPath(__DIR__);
?>
<form action="<?php echo JRoute::_('index.php?option=com_custom_fields'); ?>"
method="post" name="adminForm" id="adminForm" enctype="multipart/form-data">

<?php echo $form->renderField('mytime'); ?>

<?php echo $form->renderField('mycity'); ?>

<button type="submit">Submit</button>
</form>
</syntaxhighlight>

''form_definition.xml'' File containing the XML for the form definition, basically the two custom fields.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form name="myForm">
<field
name="mytime"
type="time"
label="Time:"
class="inputbox"
min="09:00"
max="17:30"
required="true" />
<field name="mycity"
type="City"
label="City:"
required="true"
multiple="true"
class="inputbox" />
</form>
</syntaxhighlight>

''City.php'' PHP code for the City custom field.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');
use Joomla\CMS\Form\FormHelper;

FormHelper::loadFieldClass('list');

class JFormFieldCity extends JFormFieldList {

protected $type = 'City';

public function getOptions() {
$cities = array(
array('value' => 1, 'text' => 'New York'),
array('value' => 2, 'text' => 'Chicago'),
array('value' => 3, 'text' => 'San Francisco'),
);
// Merge any additional options in the XML definition.
$options = array_merge(parent::getOptions(), $cities);

// pre-select values 2 and 3 by setting the protected $value property
$this->value = array(2, 3);

return $options;
}
}
</syntaxhighlight>

''Time.php'' PHP code for the time custom field.
<syntaxhighlight lang="php">
<?php
defined('JPATH_PLATFORM') or die;

use Joomla\CMS\Factory;
use Joomla\CMS\Form\FormField;

class JFormFieldTime extends FormField
{
protected $type = 'time';

protected function getInput()
{
// get relevant attributes which were defined in the XML form definition
$attr = !empty($this->class) ? ' class="' . $this->class . '"' : '';
$attr .= !empty($this->element['min']) ? ' min="' . $this->element['min'] . '"' : '';
$attr .= !empty($this->element['max']) ? ' max="' . $this->element['max'] . '"' : '';

// set up html, including the value and other attributes
$html = '<input type="time" name="' . $this->name . '" value="' . $this->value . '"' . $attr . '/>';

return $html;
}

public function getLabel() {
return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
}
}
</syntaxhighlight>

<noinclude>
<translate>

[[Category:Development]]
[[Category:Extension development]]
[[Category:Form fields]]
[[Category:Joomla! 2.5]]
[[Category:Joomla! 3.x]]
</translate>
</noinclude>

Advanced form guide

2024-11-27T10:43:22Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to the [https://manual.joomla.org/docs/general-concepts/forms/manipulating-forms/ Joomla Manual ] instead}}

== Introduction ==

This is one of a series of [[API Guides]], which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

This guide describes more advanced features of the Joomla Form API than is covered in [[Basic form guide]], and comprises the following aspects:
* setting the file Path to enable Joomla to find your definitions of your form, your form fields and your form field validation, in the case where you don't follow the Joomla standards.
* defining groupings of fields – Joomla provides two types, namely fieldsets and field groups.
* dynamically changing your form (after it's been loaded from an XML file)
* reflection-like methods which allow you to extract information from your form structure and data.

The guide concludes with a sample component with examples of the above aspects.

== File Paths ==
By default Joomla will look in the …/models/forms folder of your component to find the XML definition of your form, within the site files if your form is being displayed on the front end, or within the administrator files if your form is being displayed on the back end. The static function <tt>addFormPath()</tt> allows you to add a different directory to the list of directories which Joomla will search.

Similarly <tt>addFieldPath()</tt> allows you to define a different directory for any custom form field definitions (the default being …/models/fields) and <tt>addRulePath()</tt> allows you to define a different directory for any custom validation rules (the default being …/models/rules).

There are examples of all three in the sample component code at the end of this guide.

== Fieldsets ==
Fieldsets are associated with the <tt><fieldset name="myfieldset"></tt> element in the XML definition of the form. The advantage of using fieldsets is that in your layout file you can use

<tt>$form->renderFieldset("myfieldset");</tt>

to render all the fields which have <tt><field></tt> elements inside the <tt><fieldset></tt> opening and closing tags. This is instead of having to call <tt>renderField()</tt> for each field within the fieldset.

A fieldset can be viewed as a set of fields which should be displayed together in a form, and are thus similar in concept to the HTML <fieldset> element. However, note that <tt> renderFieldset()</tt> does not output the HTML <fieldset> or related tags.

== Field Groups ==
Field groups are associated with the <tt><fields name="mygroup"></tt> element in the XML definition of the form. This affects the HTML name attribute which is assigned to HTML input elements of fields which are defined within the <tt><fields></tt> opening and closing tags in the XML form definition, and hence the name of the parameter as sent to the server in the HTTP POST request.

If you specify the option <tt>"control" => "myform"</tt> when you set up your Form instance then input field values will be sent to the server in the HTTP POST request keyed like

<tt>myform[field1]</tt>

<tt>myform[field2]</tt>

<tt>myform[field3]</tt>

If you enclose these fields in the XML form definition within a <tt><fields name="mygroup"></tt> element then the POST parameters will be sent with names like

<tt>myform[mygroup][field1]</tt>

<tt>myform[mygroup][field2]</tt>

<tt>myform[mygroup][field3]</tt>

If your component has a database table and you store a number of parameters in a json string in one of the columns of the table, then you can group the HTML input elements of those parameters inside a <tt><fields></tt> element. If you name the fields tag to match your column name then you can use the Joomla Table functionality to easily convert the PHP associative array arising from the POST parameters into the json string for storing in the database.

The <tt>$group</tt> parameter which appears in several Form API methods refers to the name attribute of the <tt><fields></tt> tag in the form definition XML.

Examples of this approach can be seen in the Joomla MVC tutorial [[J3.x:Developing an MVC Component/Adding an Image|Adding an Image]] step and many of the Joomla core components.

Note that fieldsets and field groups are independent. In your form XML definition you can have <tt><fields></tt> elements within <tt><fieldset></tt> elements, and also <tt><fieldset></tt> elements within <tt><fields></tt> elements.

== Dynamically Changing Forms ==
If you have defined your form statically in an XML file, then once it's been loaded you can modify it dyamically in your PHP code using the Form APIs
* adding further fields to your form by loading another form XML definition
* modifying an existing field or fields,
* removing a field or group of fields.

=== Adding Fields via form definition ===
To include additional definitions from a file into your form do

<tt>$form->loadFile($filename);</tt>

passing the <tt>$filename</tt> of an XML file structured in the same way as your main form definition file.

Alternatively you can create a SimpleXMLElement ($xml say) in your code which contains the same XML and then call

<tt>$form->load($xml);</tt>

(The Joomla code for <tt>loadFile()</tt> just reads the data from the file into a SimpleXMLElement variable and then calls <tt>load()</tt>).

With both these functions you can pass additional parameters:

* <tt>$replace</tt> (in the <tt>load()</tt> method) / <tt>$reset</tt> (in the <tt>loadFile()</tt> method) – both of these have the same effect, and relate to the case where a field in the XML being loaded has a name which is the same as one in the form already. If set to <tt>true</tt> then the new field replaces the old one. If set to <tt>false</tt> then the new field is ignored.
* <tt>$xpath</tt> – if you want only part of the XML structure being loaded to be considered then you can specify an <tt>xpath</tt> to select the part or parts of the XML you want to include.

In addition to the example in the sample code below, you can find examples of loading additional XML files in the core Joomla administrator <tt>com_menu</tt> code, related to when an admin is setting up site menu options. The basic options for a site menuitem are specified in the <tt>item.xml</tt> file in administrator/com_menus/models/forms, but in the <tt>com_menu</tt> model <tt>item.php</tt> code this is supplemented with options defined in the XML file which is in the layout directory related to the site page which is going to be displayed.

An example of building and loading an XML structure is in the Joomla MVC development tutorial [[J3.x:Developing an MVC Component/Adding Associations|Adding Associations]] step, where the Associations fields are added dynamically this way, because the associations to be added depend upon what the language of the record is.

=== Dynamically Setting Fields ===
You can use <tt>setField()</tt> to add or replace a single field in the Form instance, and <tt>setFields()</tt> to add or replace several fields. To use these you create the XML relating to a field, then pass this to <tt>setField()</tt>

<source lang="php">
$xml = new SimpleXMLElement('<field name="newfield" … />');
setField($xml);
</source>

Similarly you can define an array of such XML elements and pass these to <tt>setFields()</tt>, which is the equivalent of calling <tt>setField()</tt> on each of the individual elements.

Specify the <tt>$group</tt> and <tt>$fieldset</tt> parameters to include the new field within a specific field group and fieldset.

If the <tt>$replace</tt> parameter is set to <tt>true</tt> then if an existing field with the same field group and name is found, it will be replaced.

If the <tt>$replace</tt> parameter is set to <tt>false</tt> and an existing field with the same field group and name is found, then the new field will be ignored.

=== Setting Field Attributes and Values ===
<tt>setFieldAttribute()</tt> allows you to set / amend an attribute associated with a field. Note that the attribute refers to the Joomla field attribute, rather than the HTML attribute of the input element. For example, to set the HTML <tt>placeholder</tt> attribute you have to set the Joomla <tt>hint</tt> field attribute, and this works only if the [[Standard form field types|Form Field type]] supports that attribute.

The HTML <tt>value</tt> attribute is treated somewhat differently from other HTML attributes. As outlined in the [[Basic form guide]], in the Joomla Form instance the XML form structure (defined by the form definition XML file) is held separately from the form pre-fill data (passed in the <tt>bind()</tt> method). What is output in the value attribute of the HTML input element is primarily the <tt>default</tt> Joomla form field attribute (if supported for that field type), but this is overridden by any value specified for that field in the <tt>bind()</tt> call.

You can thus set the <tt>default</tt> attribute using <tt>setFieldAttribute()</tt>, but to set the field value directly within the pre-fill data use <tt>setValue()</tt>.

=== Removing Fields ===
You can remove fields from the Form definition by calling <tt>removeField()</tt> to remove a specific field or <tt>removeGroup()</tt> to remove all the fields within a specified field group.

== Reflection Methods ==
There are a number of methods which allow you to access various aspects of the Form instance data. Mostly these are fairly straightforward to understand, and only cases where it may not be totally clear are explained below.

<tt>getData()</tt> returns as a Joomla Registry object the pre-fill data which has been set using the Form <tt>bind()</tt> call.

The methods <tt>getField()</tt>, <tt>getFieldset()</tt> and <tt>getGroup()</tt> all return fields as Joomla FormField objects, rather than how they're held internally within the Form instance.

<tt>getFieldsets()</tt> returns an array of Fieldset objects with properties which reflect the <tt><fieldset></tt> tag in the form definition file. So if you have

<tt><fieldset name="myfieldset" label="myfieldsetLabel" description="myfieldsetDescription"></tt>

then you can do

<source lang="php">
$fieldsets = $form->getFieldsets();
echo $fieldsets['myfieldset']->label; // outputs "myfieldsetLabel"
</source>

<tt>getFormControl()</tt> returns the string from your <tt>$options</tt> parameter passed when you created the Form instance. If you used the Joomla standard of <tt>"control" => "jform"</tt> within this <tt>$options</tt> array then <tt>getFormControl()</tt> will return the string "jform".

<tt>getInput()</tt> and <tt>getLabel()</tt> return the HTML for the <tt><input></tt> tag and <tt><label></tt> respectively of the field which has been passed as a parameter. However, note that neither of these work if you have a [[Creating_a_custom_form_field_type|Custom Field]]. Also note that these Form methods are different from the <tt>getInput()</tt> and <tt>getLabel()</tt> FormField methods which you have to provide when you are setting up some types of Custom Fields.

<tt>getValue()</tt> returns the value of the field you pass as a parameter, reading this from the data passed in the <tt>bind()</tt> call. It doesn't take account of the <tt>default</tt> attribute set against the field, which will get converted into the HTML field value attribute if no pre-fill data for that field is provided.

== Sample Component Code ==
Below are 6 files which constitute a small component which you can install and run to demonstrate a number of the features described above, and which you can adapt to experiment with other features.

Create the first 3 files in a folder "com_sample_form3", and the second 3 files in a subdirectory of this "com_sample_form3/extra". Then zip up the "com_sample_form3" folder to create <tt>com_sample_form3.zip</tt> and install this as a component on your Joomla instance. Once installed navigate on your browser to your Joomla site and add the URL parameter <tt>&option=com_sample_form3</tt>, which should display the form and allow you to enter data and submit the form. The comments in the code should make it clear what's going on.

As described in the associated [[Basic form guide]], this isn't the best way to design a Joomla MVC component, but it's written this way to make the use of the <tt>Form</tt> APIs as clear as possible.

<tt>com_sample_form3.xml</tt> Manifest file for the component
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

<name>com_sample_form3</name>
<version>1.0.0</version>
<description>Sample form 3</description>

<administration>
</administration>

<files folder="site">
<filename>sample_form3.php</filename>
<filename>sample_form.xml</filename>
<folder>extra</folder>
</files>
</extension>
</source>

<tt>sample_form.xml</tt> File containing the XML for the form definition. The 3 fields are enclosed within a fieldset "mainFieldset", and the email and telephone number fields are within a field group "details". The message field has a custom validation "noasterisk".
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form name="myFormName">
<fieldset name="mainFieldset" label="mainFieldsetLabel" description="mainFieldsetDescription">
<field
name="message"
type="text"
label="Message"
size="40"
validate="noasterisk"
class="inputbox"
required="true" />
<fields name="details">
<fieldset name="detailsFieldset">
<field name="email"
type="email"
label="Email"
required="true"
size="40"
class="inputbox" />
</fieldset>
<field name="telephone"
type="tel"
label="Telephone number"
required="true"
size="40"
class="inputbox"
validate="tel" />
</fields>
</fieldset>
</form>
</source>

<tt>sample_form3.php</tt> The main code file which is run when an HTTP GET or POST is directed towards this component.
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\Form\Form;
use Joomla\CMS\Factory;

// base form definition
$form = Form::getInstance("sample", __DIR__ . "/sample_form.xml", array("control" => "myform"));

// because email and telephone are within the "details" group, prefill data needs to reflect that
$prefillData = array("details" => array("email" => ".@.", "telephone" => "0"), "time" => "12:34");

// add form and field paths (rule path added later, before validation in HTTP POST handling)
Form::addFieldPath(__DIR__ . "/extra");
Form::addFormPath(__DIR__ . "/extra");

// using xpath parameter include just the "time" field from extra_form.xml, not the "ignored" field
$extraForm = $form->loadFile("extra_form", true, "//field[@name='time']");

// add a new element to the form, into "details" group and "mainFieldset" fieldset
$xml = new SimpleXMLElement('<field name="upload" type="file" label="Photo" accept="image/*" />');
$form->setField($xml, 'details', true, "mainFieldset");

// Change label on message field to say "Description" and set hint (html placeholder) to be "No asterisks!"
$form->setFieldAttribute("message", "label", "Description");
$form->setFieldAttribute("message", "hint", "No asterisks!");

// Remove telephone field - uncomment line below to activate
// $form->removeField("telephone", "details");

// Some reflection methods
echo "<h2>Reflection methods output</h2>";

$formName = $form->getAttribute("name");
echo "Form name is: $formName<br>";

$formControl = $form->getFormControl();
echo "Form control is: $formControl<br>";

$detailsGroup = $form->getGroup('details');
echo "Fields in details group: <br>";
foreach ($detailsGroup as $key => $value)
{
echo "Key is: $key, PHP class of field is " . get_class($value) . ", and name attribute is " . $value->getAttribute("name") . "<br>";
}

$fieldsets = $form->getFieldsets();
echo "Fieldset label for mainFieldset is " . $fieldsets['mainFieldset']->label . "<br>";

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$app = Factory::getApplication();
$data = $app->input->post->get('myform', array(), "array");
echo "<h2>POST data</h2>";
echo "Message was " . $data["message"] .
", email was " . $data["details"]["email"] .
", and time was " . $data["time"] . "<br>";
// add rule path for validation
Form::addRulePath(__DIR__ . "/extra");
$filteredData = $form->filter($data);
$result = $form->validate($filteredData);
if ($result)
{
echo "Validation passed ok<br>";
}
else
{
echo "Validation failed<br>";
$errors = $form->getErrors();
foreach ($errors as $error)
{
echo $error->getMessage() . "<br>";
}
// in the redisplayed form show what the user entered (after data is filtered)
$prefillData = $filteredData;
}
}

$form->bind($prefillData);
$data = $form->getData();
echo "<br>Form data is: $data<br>";

?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form3'); ?>"
method="post" name="sampleForm" id="adminForm" enctype="multipart/form-data">

<h2>mainFieldset fieldset</h2>
<?php echo $form->renderFieldset('mainFieldset'); ?>

<h2>time field</h2>
<?php echo $form->renderField('time'); ?>

<h2>ignored field - should be blank</h2>
<?php echo $form->renderField('ignored'); ?>

<button type="submit">Submit</button>
</form>
</source>

<tt>extra/extra_form.xml</tt> The form definition for the additional form fields to be added to the form. The component code includes just the "time" field from this form definition, and this is a [[Creating a custom form field type|custom field]] of type "mytime".
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<field
name="ignored"
type="number"
label="Number"
step="0.1"
class="inputbox"
required="true" />
<field name="time"
type="mytime"
label="Enter time"
required="true"
class="inputbox" />
</form>
</source>

<tt>extra/Mytime.php</tt> This provides the <tt><input></tt> HTML element for the "mytime" custom field. As there is no <tt>getLabel()</tt> method here, the label will be taken from the form field definition XML.
<source lang="php">
<?php
defined('JPATH_PLATFORM') or die;

use Joomla\CMS\Factory;
use Joomla\CMS\Form\FormField;

class JFormFieldMytime extends FormField
{
protected $type = 'Mytime';

protected function getInput()
{
// Set attributes - here just the CSS class for the input element, if specified
$attr = !empty($this->class) ? ' class="' . $this->class . '"' : '';

// set up html, including the value and other attributes
$html = '<input type="time" name="' . $this->name . '" value="' . $this->value . '"' . $attr . '/>';

return $html;
}
}
</source>

<tt>extra/noasterisk.php</tt> This provides the validation rule for the "noasterisk" custom validation for the message field.
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

class JFormRuleNoasterisk extends JFormRule
{
// regex to allow anything except an asterisk
protected $regex = '^[^\*]+$';
}
</source>

Basic form guide

2024-11-27T10:41:26Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to the [https://manual.joomla.org/docs/general-concepts/forms/ Joomla Manual ] instead}}

== Introduction ==
This is one of a series of [[API Guides]], which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

The Joomla Form class and API enables you to easily develop HTML forms and handle the user's input.

This page describes how you interact in general with the Joomla Form class and provides the code of a simple component which you can install to demonstrate use of this API. A companion guide [[Advanced form guide|Advanced Form Guide]] deals with more advanced aspects of the Joomla Form class.

Joomla itself also has a specific way of designing form functionality, and this page includes tutorial material to help you understand and develop your component to align with these principles.

== Overall Description ==
The diagram below shows the basic use of the Joomla Form class.

[[File:basicform.jpg|Using Joomla Forms]]

Firstly, you need to define your form in XML using Joomla [[Standard form field types]]. See the component code below for an example. In basic terms, each field element in your XML file maps to an HTML (mostly "input") element in the form, with the XML field attributes mapping to the (input) element attributes. Many of the possible field attributes are listed in [[Text form field type]].

=== Step 1 Loading the Form ===
The user clicks on the URL of your form, and Joomla routes the HTTP GET request through to your component code. You need to call ''Form::getInstance()'' passing the name of your XML file with your form definition. The Joomla Form code creates a Form instance, and then (in ''Form::loadFile()'') reads the file into memory (as a PHP ''SimpleXMLElement'') and parses the XML to ensure it's valid. The main parameters passed to ''getInstance()'' are:
* name – a string specifying the identity to give to this form – it just needs to be unique, so that it doesn't clash with any other Joomla forms on the same webpage
* data – the name of the XML file which has your form definition
* options – an array of options, with the "control" element specifying the name of the array which the POST parameters will be held in. For example, the sample code has ''array("control"=>"myform")'' which means that the HTML input elements will have name attributes set to "myform[message]", "myform[email]", etc,. They will be passed in POST parameters that way, and it's then very easy to get these into a PHP array.

=== Step 2 Providing Pre-fill Data ===
You provide values for any form element you wish. For example, if this form is being used to edit a record in the database, then you would pre-populate it with existing field values from the database. You can provide values by setting up an associative array ''$data'' and passing it to ''Form::bind($data)'' method, and Joomla Form then stores this data locally within the Form instance.

=== Step 3 Outputting the Form in HTML ===
You call ''renderField(fieldName)'' on the Form instance and you get returned the HTML which you can echo to the output. Joomla processes its XML representation of your form to obtain the section relating to the passed-in fieldName, generates the HTML for this HTML element and includes the "value" attribute based on the pre-populated data which you passed in step 2.
When outputting the form you also need to surround the input elements in a ''<form>'' element and add a submit button.

=== Step 4 User Submitting the Form ===
The user enters data into your HTML form and clicks on the submit button. The browser generates an HTTP POST request to the URL specified in the ''<form>'' element and passes to the server in POST parameters the values entered by the user; each parameter keyed by the "name" attribute of the HTML input element.

Joomla routes this POST through to your component. As this is a new HTTP request the previous Form instance no longer exists, so you have to again call ''Form::getInstance()'', passing the filename of your form XML, and Joomla (as before) creates a Form instance and reads this file into memory.

=== Step 5 Handling the HTTP POST Data ===
In this step you process the submitted data. This involves:
# Getting the POST data using ''Factory::getApplication->input->get()''. Usually the "name" attributes of the input elements are defined so that the POST parameters appear as an array, and you can use the ARRAY filter from [[Retrieving_request_data_using_JInput]] to read these directly into a PHP array. However, this means that the individual elements are not filtered at all.
# Filtering. This applies filtering on each of the input values. The filter applied to a field is governed by the "filter=..." attribute on that field in your form XML file, or if not present then the default filter will remove HTML tags etc from your data values. The possible filters are in the ''filterField()'' method of the Form class (and see https://joomla.stackexchange.com/questions/5764/what-are-possible-filters-in-joomla-form-fields). Note that these form field filters are different from the jinput filters.
# Validation. You validate the data which the user has entered by calling validate($data) on your Form instance, passing an associative array of the (filtered) user data. Joomla compares the user-entered data with the validation you defined in your form XML file, and generates errors for fields which fail the validation.

If there are validation errors then you should display those errors to the user, and redisplay the form, pre-populating the fields with the (filtered) data which the user entered previously.

If there are no errors then you can confirm this to the user, and show the next web page.

== Sample Form 1 ==
Below is the code for a small component which you can install to demonstrate basic use of Joomla forms. Place the following 3 files into a folder called "com_sample_form1". Then zip up the folder to create ''com_sample_form1.zip'' and install this as a component on your Joomla instance.

''com_sample_form1.xml'' Manifest file for the component
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

<name>com_sample_form1</name>
<version>1.0.0</version>
<description>Sample form 1</description>

<administration>
</administration>

<files folder="site">
<filename>sample_form1.php</filename>
<filename>sample_form.xml</filename>
</files>
</extension>
</syntaxhighlight>

''sample_form.xml'' File containing the XML for the form definition
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<field
name="message"
type="text"
label="Enter message"
size="40"
class="inputbox"
required="true" />
<field name="email"
type="email"
label="Enter email"
required="true"
size="40"
class="inputbox" />
<field name="telephone"
type="tel"
label="Enter telephone number"
required="true"
size="40"
class="inputbox"
validate="tel" />
</form>
</syntaxhighlight>

''sample_form1.php'' Component code.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\Form\Form;
use Joomla\CMS\Factory;

$form = Form::getInstance("sample", __DIR__ . "/sample_form.xml", array("control" => "myform"));
$prefillData = array("email" => ".@.");

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$app = JFactory::getApplication();
$data = $app->input->post->get('myform', array(), "array");
echo "Message was " . $data["message"] .
", email was " . $data["email"] .
", and telephone was " . $data["telephone"] . "<br>";
$filteredData = $form->filter($data);
$result = $form->validate($filteredData);
if ($result)
{
echo "Validation passed ok<br>";
}
else
{
echo "Validation failed<br>";
$errors = $form->getErrors();
foreach ($errors as $error)
{
echo $error->getMessage() . "<br>";
}
// in the redisplayed form show what the user entered (after data is filtered)
$prefillData = $filteredData;
}
}

$form->bind($prefillData);
?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form1'); ?>"
method="post" name="sampleForm" id="adminForm" enctype="multipart/form-data">

<?php echo $form->renderField('message'); ?>

<?php echo $form->renderField('email'); ?>

<?php echo $form->renderField('telephone'); ?>

<button type="submit">Submit</button>
</form>
</syntaxhighlight>

Once installed navigate to your site and add the following parameter to the URL:
''?option=com_sample_form1''. You should then see the form displayed with 3 required fields:
* a general text input field for a message
* an email input field, pre-populated with the string ".@."
* a telephone number input field.
and using your browser's development tools you can compare the HTML attributes with the attributes in your XML form definition.

Note that modern browsers will do some validation on the values you enter, specifically they will validate the email address and will force you to enter something into fields with the "required" attribute set, but don't (currently) do validation on telephone number fields.

Once you enter valid data into the fields and press Submit, then the data will be sent to the server and the POST leg of the sample code will be run. This runs the filtering and validation routines. If there are validation errors then the code outputs the error messages, and prefills the form with the data which the user entered before redisplaying it.

== MVC and Other Considerations ==
The way that the code above is written isn't the best approach if you are developing a genuine Joomla component. Instead you should follow the way that the Joomla core code is designed, in particular splitting your component into controllers, models, views and layouts, and the revised component code in the section after this follows this approach. The remainder of this section describes these and other design decisions, which should make the sample code easier to understand.

=== Joomla MVC Split ===
In general terms Joomla splits components into separate types of functionality:
* the controller contains the "business logic" of the application, including deciding what view and model to use
* the model provides access to the data
* the view decides what data is necessary for outputting on the web page and obtains this data from the model
* the layout outputs the HTML, and includes in the output the data which has been collated by the view. The layout runs within the context of the view, and so has direct access to the variables of the view code.

=== Post/Request/Get Pattern ===
In Joomla all of the HTML output (such as the display of a form) is performed in response to an HTTP GET, following the https://en.wikipedia.org/wiki/Post/Redirect/Get pattern. The sample code above doesn't follow this pattern, but instead outputs the validation errors and re-displays the form in the response to the HTTP POST request.

To follow the Joomla pattern, in the code which handles the POST we should include a HTTP GET redirect to the form URL. As that GET will then be a new HTTP request/response we must store in the user session the data to be shown when the form is redisplayed:
* the validation error messages are stored and output using the ''enqueueMessage()'' method (which stores data in the user session automatically for us)
* the user-entered data is stored using ''setUserState()'' and retrieved using ''getUserState()'', and keyed by a ''context'' which should be unique to this form. The code which provides the data for the form ''bind()'' operation must first check using ''getUserState()'' if there is any prefill data in the session. And if the user enters data which successfully passes validation then ''setUserState()'' should be called to clear this prefill data in the session, otherwise it will appear whenever the user next displays the form.

=== Separate Controllers ===
In response to a GET or POST, Joomla always runs the same component file, sample_form1.php in the sample component example above and the top-level sample_form2.php in the example below. The sample_form2.php code below follows the example of the core Joomla components, and has code which passes control to different methods in different controllers based on the value of the HTTP parameter ''task''. This parameter is set by Joomla core javascript based on the submit button, e.g. in the example below:

onclick="Joomla.submitbutton('myform.submit')"

The task parameter is in this example set to "myform.submit". In general the task parameter is of the form "firstpart.secondpart" and for a component called "com_example" Joomla will try to run an instance method called ''secondpart()'' of a controller class ''ExampleControllerFirstpart'' in a file ''firstpart.php'' in the ''controllers'' directory.

If the task parameter is not set then Joomla will try to run the ''display()'' method of the ''ExampleController'' class which it will expect to find in ''controller.php''.

In terms of code:

''$controller = JControllerLegacy::getInstance('Sample_form2');''

uses the ''task'' parameter to identify the appropriate controller file to include, and then creates an instance of that controller class.

''$controller->execute($input->getCmd('task'));''

executes the appropriate method (''secondpart()'' - or in the case below, ''submit()'' - or ''display()'') of that class.

In this way controller functionality handling GETs (generally in the file ''controller.php'') is separated from that handling POSTs (generally in the files in the ''controllers'' folder).

=== Joomla MVC Classes ===

Joomla provides feature-rich controller, view and model classes from which your component controllers, views and models can inherit. The model code below inherits from ''FormModel'' which shields somewhat the Joomla ''Form'' API. In this case our model calls ''FormModel::loadForm()'', and this then executes a callback to our ''loadFormData()'' to provide the data to ''bind()'' to the form.

You can also use ''FormController'' and ''AdminController'' classes, but these assume that your component is using a database table to store the data. The Joomla MVC Component Development tutorial takes this approach in [[J3.x:Developing an MVC Component/Adding backend actions]].

=== Security Token ===
Joomla uses a security token on forms to prevent CSRF attacks (see https://en.wikipedia.org/wiki/Cross-site_request_forgery). The token is output in the layout file

''<?php echo JHtml::_('form.token'); ?>''

and checked within the controller handling the POST:

''$this->checkToken();''

If the token is found to be invalid then ''checkToken()'' outputs a warning and redirects the user back to the previous page.

=== Client-side Validation ===
In addition to the server-side validation included through the form XML definition, Joomla also provides a way of including JavaScript which performs client-side validation on the browser. This is NOT included below, as it's deemed beyond the scope of this tutorial, but you can find details of it in [[J3.x:Developing an MVC Component/Adding verifications]] and [[Client-side_form_validation|Client-side form validation]].

== Sample Form 2 ==
This second sample component incorporates the design decisions described above and structures the code according to the Joomla paradigm. The overall file structure is shown in the diagram below.

[[File:Sample-form-files.jpg|Sample Form 2 file structure]].

Starting at the bottom of this diagram and going upwards the file contents are:

''com_sample_form2/sample_form2.php'' Entry point for the component. This is the first file which Joomla runs.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');
// Load the appropriate controller class
$controller = JControllerLegacy::getInstance('Sample_form2');

$input = JFactory::getApplication()->input;
// Run the task method, or display() if no task parameter
$controller->execute($input->getCmd('task'));

$controller->redirect();
</syntaxhighlight>

''com_sample_form2/controller.php'' The controller for handling HTTP GET requests
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');
use Joomla\CMS\MVC\Controller\BaseController;

class Sample_form2Controller extends BaseController
{
// Joomla will look for this class within the controller.php file
// It will (usually) call the display() method, and will find this is in the BaseController class
}
</syntaxhighlight>

''com_sample_form2/sample_form2.xml'' Manifest file for the component.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

<name>com_sample_form2</name>
<version>1.0.0</version>
<description>Sample form 2</description>

<administration>
</administration>

<files folder="site">
<filename>sample_form2.php</filename>
<filename>controller.php</filename>
<folder>controllers</folder>
<folder>views</folder>
<folder>models</folder>
</files>
</extension>
</syntaxhighlight>

''com_sample_form2/views/form/view.html.php'' View file for displaying the form. The controller ''display()'' function will create instances of the model and view, and call the view ''display()'' function below.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\View\HtmlView;
use Joomla\CMS\Factory;

class Sample_form2ViewForm extends HtmlView
{
public function display($tpl = null)
{
if (!$this->form = $this->get('form'))
{
echo "Can't load form<br>";
return;
}
parent::display($tpl); // this will include the layout file edit.php
}
}
</syntaxhighlight>

''com_sample_form2/views/form/tmpl/edit.php'' Layout file for displaying the form
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');
?>
<form action="<?php echo JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit'); ?>"
method="post" name="adminForm" id="adminForm" enctype="multipart/form-data">

<?php echo $this->form->renderField('message'); ?>

<?php echo $this->form->renderField('email'); ?>

<?php echo $this->form->renderField('telephone'); ?>

<button type="button" class="btn btn-primary" onclick="Joomla.submitbutton('myform.submit')">Submit</button>

<input type="hidden" name="task" />
<?php echo JHtml::_('form.token'); ?>
</form>
</syntaxhighlight>

''com_sample_form2/models/form.php'' Model associated with displaying the form. The view ''get('form')'' gets mapped to the model ''getForm()'' method call.
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\Model\FormModel;

class Sample_form2ModelForm extends FormModel
{

public function getForm($data = array(), $loadData = true)
{
$form = $this->loadForm(
'com_sample_form2.sample', // just a unique name to identify the form
'sample_form', // the filename of the XML form definition
// Joomla will look in the models/forms folder for this file
array(
'control' => 'jform', // the name of the array for the POST parameters
'load_data' => $loadData // will be TRUE
)
);

if (empty($form))
{
$errors = $this->getErrors();
throw new Exception(implode("\n", $errors), 500);
}

return $form;
}

protected function loadFormData()
{
// Check the session for previously entered form data.
$data = JFactory::getApplication()->getUserState(
'com_sample_form2.sample', // a unique name to identify the data in the session
array("telephone" => "0") // prefill data if no data found in session
);

return $data;
}

}
</syntaxhighlight>

''com_sample_form2/models/forms/sample_form.xml'' XML file containing the form definition
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<field
name="message"
type="text"
label="Enter message"
size="40"
class="inputbox"
required="true" />
<field name="email"
type="email"
label="Enter email"
required="true"
size="40"
class="inputbox" />
<field name="telephone"
type="tel"
label="Enter telephone number"
required="true"
size="40"
class="inputbox"
validate="tel" />
</form>
</syntaxhighlight>

''com_sample_form2/controllers/Myform.php'' Controller which handles the HTTP POST
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\MVC\Controller\BaseController;
use Joomla\CMS\Factory;

class Sample_form2ControllerMyform extends BaseController
{
public function submit($key = null, $urlVar = null)
{
$this->checkToken();

$app = JFactory::getApplication();
$model = $this->getModel('form');
$form = $model->getForm($data, false);
if (!$form)
{
$app->enqueueMessage($model->getError(), 'error');
return false;
}

// name of array 'jform' must match 'control' => 'jform' line in the model code
$data = $this->input->post->get('jform', array(), 'array');

// This is validate() from the FormModel class, not the Form class
// FormModel::validate() calls both Form::filter() and Form::validate() methods
$validData = $model->validate($form, $data);

if ($validData === false)
{
$errors = $model->getErrors();

foreach ($errors as $error)
{
if ($error instanceof \Exception)
{
$app->enqueueMessage($error->getMessage(), 'warning');
}
else
{
$app->enqueueMessage($error, 'warning');
}
}

// Save the form data in the session, using a unique identifier
$app->setUserState('com_sample_form2.sample', $data);
}
else
{
$app->enqueueMessage("Data successfully validated", 'notice');
// Clear the form data in the session
$app->setUserState('com_sample_form2.sample', null);
}

// Redirect back to the form in all cases
$this->setRedirect(JRoute::_('index.php?option=com_sample_form2&view=form&layout=edit', false));
}
}
</syntaxhighlight>

After creating the files as described above, zip up the ''com_sample_form2'' folder to create com_sample_form2.zip and install this component. Then navigate to your Joomla site and add into the URL the parameters ''&option=com_sample_form2&view=form&layout=edit''. This should display the form, and should work in a similar fashion to previous sample form, except that errors etc. will appear in the message part of the Joomla display.

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]

Inserting, Updating and Removing data using JDatabase

2024-11-27T10:38:50Z

Robbiej: Added deprecation notice and link to Joomla Manual

Selecting data using JDatabase

2024-11-27T10:37:15Z

Robbiej: Added deprecation notice and link to Joomla Manual

J3.x:Adding JavaScript and CSS to the page

2024-11-27T10:34:13Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/javascript/adding-javascript/ Joomla Manual ] instead}}

<noinclude><languages /></noinclude>
<translate>

This is one of a series of [[API Guides]], which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.</translate>

<translate>
== Inserting from a File == 
</translate>

<translate>

Joomla allows you to add JavaScript and CSS files to your HTML document, and it puts the associated ''<script>'' and ''<link>'' elements within the HTML ''<head>'' section. To do this you call the ''addScript'' and ''addStyleSheet'' methods of the Joomla object which represents the HTML document. Since Joomla! buffers all the HTML-related data that makes up a page before output, it is possible to call these methods anywhere within your code. </translate>

<translate>
First, get a reference to the current document object:</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
$document = Factory::getDocument();
// above 2 lines are equivalent to the older form: $document = JFactory::getDocument();
</syntaxhighlight>

<translate>
Then for a style sheet, use this code:</translate>

<syntaxhighlight lang="php">
$document->addStyleSheet($url);
</syntaxhighlight>

<translate>
To add a JavaScript file, use this code:</translate>

<syntaxhighlight lang="php">
$document->addScript($url);
</syntaxhighlight>

<translate>
where ''$url'' is the variable containing the full path to the JavaScript or CSS file. For example:</translate>
''JUri::base() . 'templates/custom/js/sample.js'''

<translate>
Note this will '''not''' include Mootools or jQuery. If your script requires Mootools or jQuery see [[S:MyLanguage/Javascript_Frameworks|JavaScript Frameworks]] for full details on how to include them. (Note that jQuery can only be included natively on Joomla! 3.0+.)</translate>
<translate>
It used to be possible to do this with JHTML, however, this was deprecated in Joomla 2.5 and removed in Joomla 3.x.
</translate>

<translate>
=== $options and $attributes Parameters === </translate>
<translate>

You can add ''$options'' and ''$attributes'' parameters to the above methods. The ''$options'' control overall how the ''<script>'' and ''<link>'' elements are output while the ''$attributes'' get set as HTML attributes within those tags. (Note that although there are Deprecated markers against the addScript and addStyleSheet methods of the [https://api.joomla.org/cms-3/classes/Joomla.CMS.Document.Document.html#method_addScript Joomla Document API], these markers refer just to the signature of these methods; the form of the signature using ''$options'' and ''$attributes'' parameters is not deprecated).</translate>
<translate>

The ''$options'' parameter should be an array and 2 different options are currently supported:</translate>
<translate>

* ''version => auto'' If this is set then a 'media version' is appended as a query parameter to the CSS or JavaScript URL within the ''<script>'' or ''<link>'' element. This is a string (an md5 hash) that is generated from factors including the Joomla version, your Joomla instance ''secret'' and the date/time at which the media version was generated. The media version is regenerated whenever anything is installed on the Joomla instance. Its purpose is to force browsers to reload the CSS and JavaScript files instead of using possibly outdated versions from cache.</translate>
<translate>

For example</translate>
<syntaxhighlight lang="php">
$document->addStyleSheet("...demo.css", array('version'=>'auto'));
// leads to something like
// <link href="...demo.css?37e343bbb4073e0dfe5b1eb40b6" rel="stylesheet">
</syntaxhighlight>
<translate>

The string of characters after the ''?'' is the md5 hash, which will change when extensions or Joomla itself are installed/upgraded/uninstalled. </translate>
<translate>

* '''conditional' => 'lt IE 9''' (as an example). This outputs the ''<script>'' or ''<link>'' within a [https://en.wikipedia.org/wiki/Conditional_comment Conditional Comment] which earlier versions of Internet Explorer interpreted.</translate>
<translate>

For example</translate>
<syntaxhighlight lang="php">
$document->addScript("...demo.js", array('conditional'=>'lt IE 9'));
// leads to
// 
</syntaxhighlight>
<translate>

The ''$attributes'' parameter should also be an array, and these are mapped to be HTML attributes of the ''<script>'' or ''<link>'' element. For example,</translate>

<syntaxhighlight lang="php">
$document->addScript("...demo.js", array(), array('async'=>'async'));
// leads to
// <script src="...demo.js" async></script>
</syntaxhighlight>
<translate>
== Adding the Options to Your JavaScript Code == 
</translate>
{{Joomla version|version=3.7|time=and after|comment=<translate>
Only available in Joomla! 3.7 and higher</translate>|align=left}}
<translate>

(Note that these Options are different from the ''$options'' parameter described above).</translate>

<translate>
Beside adding inline scripts, Joomla! provides a mechanism to store the options in the "optionsStorage".
This allows you to nicely manage existing options on the server side and on the client side. It also allows you to place all JavaScript logic into the JavaScript file, which will be cached by browser.</translate>

<translate>
Joomla! uses a special mechanism for "lazy loading" the options on the client side. It doesn't use inline JavaScript, which is good for page rendering speed, and makes your site more friendly to the Speed Testers (e.g. Google).</translate>

<translate>
The use of "optionsStorage" is preferred over inline JavaScript for adding the script options.</translate>

<translate>
'''Example of Use'''</translate>

<translate>
Add the script options to your module:</translate>
<syntaxhighlight lang="php">
$document = JFactory::getDocument();
$document->addScriptOptions('mod_example', array(
'colors' => array('selector' => 'body', 'color' => 'orange'),
'sliderOptions' => array('selector' => '.my-slider', 'timeout' => 300, 'fx' => 'fade')
));
</syntaxhighlight>

<translate>
Access your options on the client side:</translate>
<syntaxhighlight lang="javascript">
var myOptions = Joomla.getOptions('mod_example');
console.log(myOptions.colors); // Print your options in the browser console.
console.log(myOptions.sliderOptions);
</syntaxhighlight>

<translate>
Override the options on server side. (Possible until the head rendering.):</translate>
<syntaxhighlight lang="php">
$document = JFactory::getDocument();
// Get existing options
$myOptions = $document->getScriptOptions('mod_example');
// Change the value
$myOptions['colors'] = array('selector' => 'body', 'color' => 'green');
// Set new options
$document->addScriptOptions('mod_example', $myOptions);
</syntaxhighlight>

<translate>
== Passing Language Strings to JavaScript == </translate>
<translate>

There are cases when you may want to output an error message in your JavaScript code and want to use the Joomla mechanism of language strings. You could manage this by using addScriptOptions to pass down each language string you need, but Joomla provides a more succinct solution. </translate>
<translate>

To pass a language string to JavaScript do in your PHP code, for example,</translate>

''JText::script('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN');''
<translate>

Then in your JavaScript code you can do:</translate>

''var message = Joomla.JText._('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN');''
<translate>

to obtain in the user's language the text message associated with the language constant.</translate>
<translate>

Obviously certain language strings have embedded %s characters, so in your JavaScript code you will have to handle that, eg using an external JavaScript sprintf library or string replace, etc.</translate>

<translate>
== Inserting Inline Scripts from Within a PHP File == 
</translate>
<translate>
If your JavaScript or CSS are generated using PHP, you can add the script or style sheet directly into the head of your document:</translate>

<syntaxhighlight lang="php">
$document = JFactory::getDocument();

// Add Javascript
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');

// Add styles
$style = 'body {'
. 'background: #00ff00;'
. 'color: rgb(0,0,255);'
. '}';
$document->addStyleDeclaration($style);
</syntaxhighlight>

<translate>
=== JavaScript Example === </translate>
<translate>

For example, the following code is used to define a custom tool tip that takes advantage of Mootools.</translate>

<syntaxhighlight lang="php">
function getToolTipJS($toolTipVarName, $toolTipClassName){
$javascript = 'window.addEvent(\"domready\", function(){' ."\n";
$javascript .= "\t" .'var $toolTipVarName = new Tips($$("' . $toolTipVarName .'"), {' ."\n";
$javascript .= "\t\t" .'className: "' .$toolTipClassName .'",' ."\n";
$javascript .= "\t\t" .'initialize: function(){' ."\n";
$javascript .= "\t\t\t" .'this.fx = new Fx.Style(this.toolTip, "opacity", {duration: 500, wait: false}).set(0);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onShow: function(toolTip){' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(1);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onHide: function(toolTip) {' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(0);' ."\n";
$javascript .= "\t\t" .'}' ."\n";
$javascript .= "\t" .'});' ."\n";
$javascript .= '});' ."\n\n";
return $javascript;
}

$document = JFactory::getDocument();
$document->addStyleSheet("/joomla/components/com_mycustomcomponent/css/mytooltip.css",'text/css',"screen");
$document->addScriptDeclaration(getToolTipJS("mytool","MyToolTip"));
</syntaxhighlight>

<translate>
Note that in order for this JavaScript to be useful, it is necessary to include the appropriate class name in the HTML, as well as providing the ''mytooltip.css'' file. Both are outside the scope of this article.</translate>

<translate>
=== CSS Examples === 
</translate>
<translate>
This is also useful if you are inserting a form field of CSS into your code. For example, in a module you might want a user to choose the colour of the border. Call the form field's value and assign it a variable $bordercolor in mod_example.php. Then in tmpl/default.php you can include the following:</translate>

<syntaxhighlight lang="php">
$document = JFactory::getDocument();
$document->addStyleSheet('mod_example/mod_example.css');
$style = '#example {
border-color:#' . $bordercolor . ';
}';
$document->addStyleDeclaration( $style );
</syntaxhighlight>
<translate>
Here mod_example.css contains the CSS file of any non-parameter based styles. Then the ''bordercolor'' parameter/form field is added in separately.</translate>
<translate>
==Add Custom Tag== 
</translate>
<translate>
There will be some occasions where even these functions are not flexible enough, as they are limited to writing the contents of ''<script />'' or ''<style />'' tags, and cannot add anything outside those tags. One example would be the inclusion of a style sheet link within conditional comments, so that it is picked up only by Internet Explorer 6 and earlier. To do this, use ''$document->addCustomTag'':</translate>

<syntaxhighlight lang="php">
$stylelink = '' ."\n";

$document = JFactory::getDocument();
$document->addCustomTag($stylelink);
</syntaxhighlight>
<translate>
If it was necessary to include other conditional CSS, always include the ''addCustomTag'' method after it is declared.</translate>

<translate>
== Sample Module Code == </translate>
<translate>

Below is the code for a simple Joomla module which you can install and run to demonstrate adding CSS and JavaScript, and can adapt to experiment with the concepts above. If you are unsure about development and installing a Joomla module then following the tutorial at [[S:MyLanguage/J3.x:Creating a simple module/Introduction| Creating a simple module ]] will help.</translate>
<translate>

In a folder mod_css_js_demo create the following 4 files:</translate>

''mod_css_js_demo.xml''
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>css js demo</name>
<version>1.0.1</version>
<description>Code for including JS and CSS links</description>
<files>
<filename module="mod_css_js_demo">mod_css_js_demo.php</filename>
<filename>demo.css</filename>
<filename>demo.js</filename>
</files>
</extension>
</syntaxhighlight>

''mod_css_js_demo.php''
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;

$document = Factory::getDocument();

$options = array("version" => "auto");
$attributes = array("defer" => "defer");
$document->addScript(JURI::root() . "modules/mod_css_js_demo/demo.js", $options, $attributes);
$document->addStyleSheet(JURI::root() . "modules/mod_css_js_demo/demo.css", $options);

$document->addScriptOptions('my_vars', array('id' => "css-js-demo-id2"));

JText::script('JLIB_HTML_EDIT_MENU_ITEM_ID');

echo '<h1 id="css-js-demo-id1">Hello World!</h3>';
echo '<button id="css-js-demo-id2">Click here!</button>';
</syntaxhighlight>

''demo.css''
<syntaxhighlight lang="css">
#css-js-demo-id1 {
color: red;
}
</syntaxhighlight>

''demo.js''

<syntaxhighlight lang="javascript">
jQuery(document).ready(function() {

const params = Joomla.getOptions('my_vars');
console.log(params);
console.log("JS language constant: " + Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID'));

var message = Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID');
message = message.replace("%s", params.id);
document.getElementById(params.id).addEventListener("click", function() {alert(message);});
});
</syntaxhighlight>
<translate>

Zip up the mod_css_js_demo directory to create ''mod_css_js_demo.zip''.</translate>
<translate>

Within your Joomla Administrator go to Install Extensions and via the Upload Package File tab, select this zip file to install this sample mod_css_js_demo module.</translate>
<translate>

Make this module visible by editing it (click on it within the Modules page) then:
# making its status Published
# selecting a position on the page for it to be shown
# on the menu assignment tab specify the pages it should appear on</translate>
<translate>

When you visit the web page, you should see the module in your selected position. It should display:
* a message ''Hello World!'' which the CSS file should change to display in red
* a button which when you click it will execute an ''alert()'' showing the language string and variable which were passed down from the PHP code.</translate>
<translate>

Using your browser's development tools you can also view the ''<script>'' and ''<link>'' elements within the HTML and see the JavaScript output on the console. </translate>

<noinclude>
<translate>

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Module Development]]
[[Category:JavaScript]]
[[Category:CSS]]
</translate>
</noinclude>

Using Joomla Ajax Interface

2024-11-27T10:30:03Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/javascript/com-ajax/ Joomla Manual ] instead}}

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.2|time=and after|comment=<translate>
series</translate>}}</noinclude>
{{-}}
<translate>==What is The Joomla Ajax Interface (''com_ajax'')== </translate>
<translate>
A slim, extensible component to act as an entry point for HTTP requests for stand alone modules and plugins, thus allowing for the potential of Ajax functionality in them. ''com_ajax ''is generally used when you are not the developer of the component that the module or plugin is interacting with.</translate>

<translate>
'''NOTE''' If you are a component developer, you do not need to use ''com_ajax'' to implement Ajax functionality in it. You can do so directly in your component.</translate>

<translate>
Examples of use cases include, but are not limited to:
*A module that retrieves data from an external API
*A module that interacts with a component that you did not develop
*A plugin that implement API like functionality to allow consumption of data from your site</translate>

<translate>==Anatomy of an Ajax Request== </translate>

<translate>===Required=== </translate>

*''option=com_ajax''
*''[module|plugin]=name''
*''format=[json|debug|raw]''

<translate>===Optional=== </translate>
*''method=[custom fragment]'' <translate>
defaults to ''get'' if omitted.</translate>

<translate>===Overview=== </translate>
<translate>
All requests begin with ''?option=com_ajax'', which calls this extension, and must indicate the type of extension to call, and the data format to be returned.


Additional variables and values used by your extension may also be included in the URL.</translate>

<translate>
For example, a request to ''?option=com_ajax&module=session'' would call ''mod_session'' with results returned in the default format. In contrast,''?option=com_ajax&plugin=session&format=json'' would trigger the ''onAjaxSession'' plugin group with results returned in JSON.</translate>

<translate>==Module Support== </translate>

<translate>===Summary=== </translate>

<translate>
Module support is accomplished by calling a method in the module's ''helper.php'' file.</translate>

<translate>===Details=== </translate>

<translate>
Module requests must include the ''module'' variable in the URL, paired with the name of the module (i.e. ''module=session'' for ''mod_session'').</translate>

<translate>
This value is also used for:


*The name of the directory to check for the helper file, e.g. ''/modules/mod_session/helper.php''


*The class name to call, e.g. ''modSessionHelper''</translate>

<translate>
Optionally, the ''method'' variable may be included to override the default method prefix of ''get''.</translate>

:<translate>
'''NOTE''' All methods must end in ''Ajax''. For example:</translate>
:''method=mySuperAwesomeMethodToTrigger'' <translate>
will call</translate> ''mySuperAwesomeMethodToTriggerAjax''

<translate>
The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality.</translate>

<translate>==Plugin Response== </translate>

<translate>===Summary=== 


Plugin support is accomplished by triggering the ''onAjax[Name]'' plugin event.</translate>

<translate>===Details=== 


Plugin requests must include the ''plugin'' variable in the URL, paired with the name of the plugin event, e.g. ''plugin=session'' for ''onAjaxSession''.</translate>

<translate>
This value is also used for:


*The plugin class name following the ''plgAjax[Name]'' convention.
*The plugin function name following the ''onAjax[Name]'' convention.
*The default plugin group is ''ajax''. You can change it specifying the ''group'' request parameter. (From Joomla! 3.4)


The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality.</translate>

<translate>==Response Format== </translate>

<translate>
''format=[json|debug]'' is an optional argument for the results format:


*''json'' for JSON format
*''debug'' for human-readable output of the results.</translate>

<translate>
[[Category:AJAX]]
[[Category:JavaScript]]
[[Category:Development]]</translate>

JSON Responses with JResponseJson

2024-11-27T10:27:47Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/javascript/ajax/ Joomla Manual ] instead}}

{{version/tutor|3.x}}
== Overview ==
This is one of a series of [[API Guides]], which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

A new class, JResponseJson, was added to Joomla! 3 that is able to simplify Ajax requests. As of Joomla! 3.8, the core code was namespaced and aliases were added. (See the ''/libraries/classmap.php'' file at or near line 131.) The JResponseJson class was replaced by the JsonResponse class in the Joomla/CMS/Response namespace.

With that class it is now possible to prepare responses to Ajax requests in a standardized and easy manner.

Have a look at the revised file on [https://github.com/joomla/joomla-cms/blob/staging/libraries/src/Response/JsonResponse.php Github] or in your own site's files at ''/libraries/src/Response/JsonResponse.php''.

The JsonResponse class will mostly be used in controllers of components where you get the following advantages:

* Using the flag ''success'' the JavaScript code (whether Mootools JRequest.JSON or jQuery.getJSON) can check whether the task was successful or not and react accordingly. (If the request itself fails, the error event of the JavaScript API can be used.)
* Then the actual response data, if any, can be retrieved from ''data'' in the JSON object, and
* Optionally a main response message from ''message''.
* Additionally, all gathered messages in the JApplication message queue are automatically sent back in ''messages''. This can be turned off.

Another advantage is that no ''$app->close();'' is necessary if the Ajax request is done with ''format=json''. The existing API handles the rest. Just echo the response object at the end of the task.

== How to Use ==
=== Most Common Cases ===
Here is an example controller file:

<source lang="php">
class MyController extends JControllerLegacy
{
public function execute()
{
try
{
$anyParam = JFactory::getApplication()->input->get('anyparam');

$result = $this->getModel('example')->createSomething($anyParam);

echo new JsonResponse($result);
}
catch(Exception $e)
{
echo new JsonResponse($e);
}
}
}</source>

In the default case, the return value of something that has been calculated by the model is simply pushed into a new JsonResponse object and written to the output. This will automatically create a JSON-encoded string as follows:

<source lang="json">
{"success":true,"message":null,"messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}
</source>

In the ''data'' field, you can send any array, object or value you want and the ''success'' flag is automatically set to ''true''.

If any exception occurred in the model, this exception is simply passed directly to a new JsonResponse object which would create the following output:

<source lang="json">
{"success":false,"message":"This is the message of the exception","messages":null,"data":null}
</source>

Since it is an exception the ''success'' flag is automatically set to ''false'' and the message of the exception becomes the main response message.

=== Additional Options ===
If no exception is passed as the first argument of the JsonResponse constructor, you can specify an arbitrary main response message by passing a string as the second argument:
<source lang="php">
echo new JsonResponse($result, JText::_('COM_COMPONENT_MY_TASK_SUCCESS'));
</source>
which creates, for example:
<source lang="json">
{"success":true,"message":"The request was successful.","messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}
</source>

You can also set the error flag to ''true'' with the help of the third argument (''$error''):
<source lang="php">
echo new JsonResponse($result, JText::_('COM_COMPONENT_MY_TASK_ERROR'), true);
</source>
which creates, for example:
<source lang="json">
{"success":false,"message":"There was an error.","messages":null,"data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}
</source>
In this way you can also send some data back.

Regardless of having an error response or a success response, JsonResponse sends all messages back to the client that have been gathered in the application object:
<source lang="php">
$app = JFactory::getApplication();
// Some code ($result = ...)
$app->enqueueMessage('This part was successful');
// Some more code
$app->enqueueMessage('Here was a small warning'. 'warning');

echo new JsonResponse($result, 'Main response message');
</source>

This results in:
<source lang="json">
{"success":true,"message":"Main response message","messages":"<<all the encoded messages of $app>>","data":{"myfirstcustomparam":1,"mysecondcustomparam":42, ...}}
</source>

You can see the advantage of that below in the JavaScript section.

If you don't want to send the messages back (rather they stay in the session), set the fourth argument (''$ignoreMessages'') of the constructor to ''true''.

=== Corresponding JavaScript Code ===
Here is some sample JavaScript that can be used on the client side together with JsonResponse on the server side.
The example is written with Mootools code. Something similar can also be done with jQuery or any other JavaScript library for Ajax requests.

<source lang="javascript">
var req = new Request.JSON({
method: 'post',
url: 'index.php?option=com_component&task=mycontroller.execute&format=json',
onSuccess: function(r)
{
if (!r.success && r.message)
{
// Success flag is set to 'false' and main response message given
// so you can alert it or insert it into some HTML element
alert(r.message);
}

if (r.messages)
{
// All the enqueued messages of the $app object can simple be
// rendered by the respective helper function of Joomla!
// They will automatically be displayed at the messages section of the template
Joomla.renderMessages(r.messages);
}

if (r.data)
{
// Here you can access all the data of your response
alert(r.data.myfirstcustomparam);
alert(r.data.mysecondcustomparam);
}
}.bind(this),
onFailure: function(xhr)
{
// Reaching this point means that the Ajax request itself was not successful
// So JsonResponse was never called
alert('Ajax error');
}.bind(this),
onError: function(text, error)
{
// Reaching this point means that the Ajax request was answered by the server, but
// the response was not valid JSON. (This happens sometimes if there were PHP errors,
// warnings or notices during the development process of a new Ajax request.)
alert(error + "\n\n" + text);
}.bind(this)
});
req.post('anyparam=myvalue');
</source>

== Best Practice ==
As seen above, controller code can be kept simple using JsonResponse. The model is calculating the data which can be passed to JsonResponse afterwards. (You can still modify it in the controller.) If you are developing an MVC component, save such a controller in a file called ''mycontroller.json.php'' and place it inside your ''controllers'' folder. That controller is automatically executed if your request URL contains ''format=json''.

Note that there is no need for closing the application (''$app->close();'') because the architecture of Joomla! handles that for you.

<source lang="php">
class MyController extends JControllerLegacy
{
public function execute()
{
try
{
$anyParam = JFactory::getApplication()->input->get('anyparam');

$count = $this->getModel('example')->countSomething($anyParam);

echo new JsonResponse($count);
}
catch(Exception $e)
{
echo new JsonResponse($e);
}
}
}</source>

===Additional Note===
If you want to support users without JavaScript by doing the same task with a normal request and a final redirect back to the page, there is not much you have do additionally. Just create another controller (with a name such as ''mycontroller.php'') and code like this:

<source lang="php">
class MyController extends JControllerLegacy
{
public function execute()
{
$app = JFactory::getApplication();
$app->setRedirect(JRoute::_('index.php?option=com_mycomponent&view=myview', false));

try
{
$anyParam = JFactory::getApplication()->input->get('anyparam');

$count = $this->getModel('example')->countSomething($anyParam);

$app->setMessage(JText::plural('COM_COMPONENT_COUNT_TASK', $count));
}
catch(Exception $e)
{
$app->setMessage(JText::sprintf('COM_COMPONENT_COUNT_TASK_ERROR', $e->getMessage()), 'error');
}
}
}</source>

No changes are necessary in the model!

Depending on whether you do the request with ''format=json'' (Ajax-Request) or via normal request (without the ''format'' parameter), the correct controller is executed automatically and the response is prepared accordingly.

== Sample Component Code ==
Below is the code for a simple Joomla component which you can install and run to demonstrate use of the JReponseJson functionality. Place the following 3 files into a folder called "com_jresponse_json_demo". Then zip up the folder to create <tt>com_jresponse_json_demo.zip</tt> and install this as a component on your Joomla instance.

<tt>com_jresponse_json_demo.xml</tt> Manifest file for the component
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.1.0" method="upgrade">

<name>com_jresponse_json_demo</name>
<version>1.0.0</version>
<description>Demo of jresponse_json</description>

<administration>
</administration>

<files folder="site">
<filename>jresponse_json_demo.php</filename>
<filename>calc.js</filename>
</files>
</extension>
</source>

<tt>jresponse_json_demo.php</tt> PHP file which displays the form and handles the Ajax request.
<source lang="php">
<?php
defined('_JEXEC') or die('Restricted access');

use Joomla\CMS\Factory;

$app = Factory::getApplication();
$input = $app->input;

$task = $input->get("task", "", "cmd");

function divide($a, $b)
{
if ($b == 0)
{
throw new Exception('Division by zero!');
}
return $a/$b;
}

if ($task == "divide") { // respond to Ajax
$x = $input->get("x", 0, "float");
$y = $input->get("y", 0, "float");
$app->enqueueMessage("Enqueued notice", "notice");
$app->enqueueMessage("Enqueued warning", "warning");
try
{
$result = divide($x, $y);
echo new JResponseJson($result, "It worked!");
}
catch (Exception $e)
{
echo new JResponseJson($e);
}
} else { // normal HTTP GET - display the form
JHtml::_('jquery.framework'); // use JQuery for Ajax call
$document = JFactory::getDocument();
$document->addScript(JUri::root() . "components/com_jresponse_json_demo/calc.js");

echo '<label>x</label><input id="x" type="number" step="any">';
echo '<label>y</label><input id="y" type="number" step="any"><br>';
echo '<button onclick="calculate();">Divide!</button><br>';
echo '<label>answer</label><input id="answer" type="text" readonly><br>';
}
</source>

<tt>calc.js</tt> Javascript file which initiates the Ajax request and handles the response.
<source lang="javascript">
function calculate() {
x = document.getElementById("x").value;
y = document.getElementById("y").value;
jQuery.ajax({ // by default jQuery sends Ajax requests to the same URL as the current page
data: { task: "divide", format: "json", x: x, y: y },
})
.done(function(result, textStatus, jqXHR)
{
if (result.success)
{
jQuery("#answer").val(result.data);
console.log("Message from server was " + result.message);
}
else
{
alert(result.message);
}
// display the enqueued messages in the message area
Joomla.renderMessages(result.messages);
})
.fail(function(jqXHR, textStatus, errorThrown)
{
console.log('ajax call failed' + textStatus);
});
}
</source>

Once the component is installed, navigate to your site home page and add the following parameter to the URL <tt>?option="com_jresponse_json_demo"</tt> to navigate to this component. The component prompts for 2 values, x and y, and when you click on the Divide button it makes an Ajax call to the server. The server performs the calculation, including checking for division by zero, and then returns the answer using JReponseJson.

The server also includes 2 enqueued messages in the response, which the javascript displays in the message area by calling <tt>Joomla.renderMessages()</tt> (which is a javascript function found in the Joomla core.js file).

(The server code has been designed to focus on the JResponseJson API. If you are developing a genuine Joomla component then you should use the Joomla Form API and MVC approach as outlined in [[Basic form guide]].)

== Further Reading ==
Another example of using JReponseJson can be found in [[J3.x:Developing_an_MVC_Component/Adding_AJAX]].

Ajax can also be used in Joomla Modules and Plugins, as described in [[Using Joomla Ajax Interface]].

[[Category:AJAX]]
[[Category:Component Development]]
[[Category:Extension development]]

Accessing the current user object

2024-11-27T10:19:01Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/user/ Joomla Manual ] instead}}

{{version/tutor|2.5,3.x}}
== Overview ==
This is one of a series of [[API Guides]] that aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code that you can easily install and run.

This page describes the functionality associated with the Joomla <tt>User</tt> class, accessible via the <tt>User</tt> API. At the bottom of the page there is also the code of a module that you can install to demonstrate some of this functionality.

In general, the "user" represents the identity of someone who can log on to a Joomla instance, whether that be the Frontend, Backend (Administrator functionality) or both. Associated with the user is
# static information such as username and email address, as well as user preferences regarding language, preferred editor, etc.
# dynamic information such as the last logon date/time
# privileges data, specifying the privileges that each user has, which allow him/her to perform actions on items within the Joomla instance.

The Joomla user APIs allow you to view the user account attributes, modify those attributes, check user privileges, delete user accounts and perform user account management functions such as block an account.

Setting some of the user attributes impacts the user's ability to log on – e.g. blocking the account or changing the password. However, the User API code won't include other actions that you may need to take in conjunction with that – e.g. sending users an email to warn them that they're blocked.

== Basic Operations ==
To get the user object for the currently logged-on user:

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
$user = Factory::getUser();
</syntaxhighlight>

These two lines are equivalent to the following in the old class naming convention:
<syntaxhighlight lang="php">
$user = JFactory::getUser();
</syntaxhighlight>

If no user is logged on then Factory::getUser() returns a "blank" user object, with the id field set to 0 (zero).

To get information about any other registered user you can call the function with a user <tt>id</tt> or <tt>username</tt>, e.g. for user with <tt>id</tt> 99;

<syntaxhighlight lang="php">
$user = JFactory::getUser(99);
</syntaxhighlight>

Once you have the user object, you can display information about the user. For example, this code displays the current user's name, email and user name:

<syntaxhighlight lang="php">
echo "<p>This user's name is {$user->name}, email is {$user->email}, and username is {$user->username}</p>";
</syntaxhighlight>

== User Object Properties ==
Joomla stores some of the data items associated with a user in fixed fields in the users table, and other data items in a params field within the users table. This is then reflected in what data items you have available as properties of the user object, and what data items you must use the params property to access.

With regard to the admin Users functionality, generally the data items in the fixed fields are in the first tab in the admin Users / Edit form (currently named "Account Details"), and the attributes stored in the params are visible in a subsidiary tab (currently named "Basic Settings").

These are the properties automatically generated on a call to getUser(), in the order defined in the API documentation
* id - The unique, numerical user id. (In other Joomla database tables this id is used as the foreign key to point to the associated user record).
* name - The name of the user. (e.g. Vint Cerf)
* username - The login/screen name of the user. (e.g. shmuffin1979)
* email - The email address of the user. (e.g. crashoverride@hackers.com)
* password - The encrypted version of the user's password
* password_clear - Set to the user's password only when it is being changed. Otherwise, remains blank.
* block - Set to '1' when the user is set to 'blocked' in Joomla (i.e. prevented from logging on)
* sendEmail - Specifies whether this user should receive system emails or not
* registerDate - Set to the date when the user was first registered.
* lastvisitDate - Set to the date the user last visited the site.
* activation - an activation token. This is used when the site allows users to self-register. To complete account setup, an email is sent to the person who has self-registered, and the link embedded in the email contains this activation token.
* params - a json string of name/value pairs for the subsidiary user attributes (see below).
* groups - an associative array of group id => (string) group id for the user groups that this user is a member of
* guest - If the user is not logged in, this variable will be set to '1'. The other variables will be unset or default values.
* lastResetTime - Set to the last time the password was reset.
* resetCount - Counts the number of password resets.
* requireReset - indicates that this user will be forced to reset the password the next time they log in.

The user attributes that are stored in the params field in the database, and that are available via <tt>$user->getParam()</tt> are the following.
* admin_style – the id of the template on the Backend.
* admin_language – the language tag of the language on the Backend
* language – the language tag of the language on the Frontend
* editor – the preferred editor
* timezone – the user's selected timezone (one of the standard PHP time zones). The timezone is also available via <tt>getTimezone()</tt>.

For example, to get the user's preferred Frontend language call the <tt>getParam()</tt> member function of the user object, passing in the name of the parameter you want (i.e. 'language') along with a default value in case it is blank.

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
$user = Factory::getUser();
$language = $user->getParam('language', 'the default');

echo "<p>Your Frontend language is set to {$language}.</p>";
</syntaxhighlight>

== Determining Status ==
Frequently, you will just want to make sure the user is logged in before continuing. The 'guest' property will be set to '1' when the current user is not logged in. When the user is authenticated, 'guest' will be set to '0'.

<syntaxhighlight lang="php">
$user = JFactory::getUser();

if ($user->guest) {
echo "<p>You must login to see the content. I want your email address.</p>";
} else {
echo "<p>You are logged in, you can see the content.</p>";
}
</syntaxhighlight>

(If you've passed a userid/username to getUser() to find the user object of another user on the system, then note that guest does not indicate whether this user is "logged on" or not (in the sense of there being a current session cookie for that user); guest set to 0 is more an indication that a valid user record has been loaded.)

== Privileges ==
Not all users are given equal rights. For instance, a Super Administrator may be able to edit anyone's content, while a Publisher may only be able to edit their own. Certain articles may be confidential and may be viewed only by users who have permission to view them.

There are 4 method calls in the User API relating to privileges

=== authorise() ===
The <tt>authorise()</tt> member function can be used to determine if the current user has permission to do a certain task. The first parameter is used to identify which task we wish to check being allowed. The second represents the component we wish to retrieve the ACL information from.

<syntaxhighlight lang="php">
$user = JFactory::getUser();

if ($user->authorise('core.edit', 'com_content'))
{
echo "<p>You may edit all content.</p>";
}
else
{
echo "<p>You may not edit all content.</p>";
}

if ($user->authorise('core.edit.own', 'com_content'))
{
echo "<p>You may edit your own content.</p>";
}
else
{
echo "<p>You may not edit your own content.</p>";
}
</syntaxhighlight>

=== getAuthorisedCategories() ===
You call getAuthorisedCategories() passing in the component and the action you want to perform, and the method returns an array of category ids on which this user can perform the action. For example:

<syntaxhighlight lang="php">
$user->getAuthorisedCategories('com_content', 'core.delete')
</syntaxhighlight>
returns an array of category ids of com_content categories which this user can delete.

=== getAuthorisedGroups() ===
<tt>$user->getAuthorisedGroups()</tt> returns an array of User Group ids which this user is within. You can see the User Group ids by navigating to the admin Users / Groups page.

=== getAuthorisedViewLevels() ===
<tt>$user->getAuthorisedViewLevels()</tt> returns an array of Viewing Access Levels ids (which you can see by navigating to the admin Users / Viewing Access Levels page). Generally components that want to restrict viewing pages assign an Access Level to each item – one of the Viewing Access Levels which you see on that admin page – and then store the id of the assigned access level against the item in a database field called Access within the item's database table. Then to check if a given user may view that item you would check if the value in the Access database field was within the array of AuthorisedViewLevels for that user.

For example, if you wanted to restrict an article called "article50" to a Viewing Access Level called Special (with an id of 3), then you would put 3 in the Access field of the Content record for article50, and a user would be allowed to view it if the array returned by getAuthorisedViewLevels() included the element 3.

== Database Operations ==
The diagram below shows how you can use the User API to update user data. Black arrows indicate flow of control: green arrows indicate direction of data.

Note that the editing of user data is managed within the Joomla admin Users functionality (com_users component), where there are many checks performed to ensure that users can perform only operations that they are authorised to perform. For example, general users may not grant themselves additional privileges. '''If you use the User APIs then the vast majority of these validations are not performed, so you will likely have to build in additional validation checks yourself.'''

The User class uses the Joomla Table class to perform CRUD operations at the database level. Operations which change the User record will cause [[Plugin/Events/User|Plugin User Events]] to be raised.

[[File:User_db.jpg|User Database-related methods]]

=== load() ===
Use <tt>load()</tt> to load in from the database the attributes of a user record (identified by id) from the database. The User class code will read the data from the database and (assuming it's a valid user) will store the attributes in the class properties, including the params field which stores the additional attributes. You can then access these properties directly, e.g. <tt>$user->name</tt>.

What <tt>load()</tt> does is thus similar to <tt>Factory::getUser($id)</tt>, except that with <tt>load()</tt> you need to have created the User instance first with <tt>new User()</tt>.

=== bind() ===
Use <tt>bind()</tt> if you have an associative array $data of property names to property values, e.g. <tt>array('name' => 'Vint Cerf', 'username' => 'shmuffin1979')</tt>. The <tt>bind()</tt> method will then update the local properties with the values passed in.

You can similarly set the values of the properties directly <tt>$user->name = 'Vint Cerf'</tt> or the params property via <tt>setParams()</tt>.

=== save() ===
Use <tt>save()</tt> to write to the database the updated properties that you have set. The <tt>save()</tt> code copies the property values into its 'table' structure and calls the Table class <tt>bind()</tt> and <tt>store()</tt> methods to write them to the database.

=== Inserting Records ===
You can similarly use the above mechanism to insert new user records, the only difference being that you don't load an existing record from the database first.

=== Deleting Records ===
To delete a user record you first load it from the database then use the <tt>delete()</tt> method:
<syntaxhighlight lang="php">
$user = Factory::getUser($userid);
$user->delete();
</syntaxhighlight>
Related records in other user tables (such as in #__user_usergroup_map that holds the mapping to user groups and in #__messages which holds user-user messages) are deleted as well, and this operation triggers the events [[Plugin/Events/User#onUserBeforeDelete|onUserBeforeDelete]] and [[Plugin/Events/User#onUserAfterDelete|onUserAfterDelete]] so that plugins can also delete any related user data. However, if the user has, for example, created articles or is associated with a contact record then the references to the user's id in those records will remain.

== Sample Module Code ==
Below is the code for a simple Joomla module that you can install and run to demonstrate use of the Joomla User API functionality. If you are unsure about development and installing a Joomla module, following the tutorial at [[S:MyLanguage/J3.x:Creating a simple module/Introduction| Creating a simple module ]] will help.

In a folder mod_sample_user create the following two files:

<tt>mod_sample_user.xml</tt>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>User demo</name>
<version>1.0.1</version>
<description>Code demonstrating use of Joomla User class</description>
<files>
<filename module="mod_sample_user">mod_sample_user.php</filename>
</files>
</extension>
</syntaxhighlight>

<tt>mod_sample_user.php</tt>
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;
use Joomla\CMS\Language\LanguageHelper;

$input = Factory::getApplication()->input;

// find the user - either from username=xxx parameter or current user
if ($input->exists('username'))
{
$username = $input->get('username', "", "STRING");
echo "Getting details for {$username}<br>";
$user = Factory::getUser($username);
}
else
{
$user = Factory::getUser();
}
if ($user->id == 0)
{
echo "Please logon or provide a valid username as URL parameter";
return;
}

// output the user's email address and Frontend language
$language = $user->getParam('language', 'the default');
echo "Email address of {$user->name} is {$user->email}, Frontend language is {$language}<br>";

// Set new Frontend language of this user if userlanguage=xxx parameter set
// This will fail if you try to change the language of a Super User, and you're not logged on as a Super User
if ($new_language = $input->get('userlanguage', "", "STRING"))
{
if (array_key_exists($new_language, LanguageHelper::getContentLanguages()))
{
$user->setParam('language', $new_language);
if ($user->save())
{
echo "Language successfully set to {$new_language}<br>";
}
else
{
echo "Setting language to {$new_language} failed<br>{$user->getError()}<br>";
}
}
else
{
echo "Setting language to {$new_language} failed - language doesn't exist<br>";
}
}

// if we're on a single article page, then check if the user can edit the article
$option = $input->get('option', "", "cmd");
$view = $input->get('view', "", "string");
$id = $input->get('id', 0, "int");

if ($option == "com_content" && $view == "article")
{
if ($user->authorise('core.edit', "com_content.article.{$id}"))
{
echo "{$user->name} may edit this article<br>";
}
else
{
echo "{$user->name} may not edit this article<br>";
}
}
</syntaxhighlight>

Zip up the mod_sample_user directory to create <tt>mod_sample_user.zip</tt>.

Within your Joomla Administrator go to Install Extensions and via the Upload Package File tab select this zip file to install this sample user module.

Make this module visible by editing it (click on it within the Modules page) then:
# making its status Published
# selecting a position on the page for it to be shown
# on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position. The module does the following:
* gets the user object, and displays the user's name, email address and preferred Frontend language. You define the user to select by either logging in, or by specifying a parameter to the URL <tt>username=XXX</tt> (replacing XXX by a valid username on the system).
* if you specify a URL parameter e.g. <tt>userlanguage=es-ES</tt> the code will set this language (Peninsular Spanish in this instance) as the preferred Frontend language of the user (provided this language is installed on the system as a Content Language).
* if you navigate to a page which displays a single article, then the code will output whether this user may edit that article or not.

You can easily adapt the module code to experiment with some of the other API calls described above.

== External Links ==
[https://api.joomla.org/cms-3/classes/Joomla.CMS.Factory.html#method_getUser Joomla 3.9 API reference]
[[Category:Development]]
[[Category:Tutorials]][[Category:Framework]]
[[Category:Module Development]]
[[Category:Plugin Development]][[Category:Component Development]]

Plugin/Events/Content

2024-08-13T08:54:47Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{version/tutor|2.5,3.x|alt=1.5|altlink=J1.5:Plugin/Events/Content|alttitle=this guide for old event names}}

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/building-extensions/plugins/plugin-events/content Joomla Manual ] instead}}

Content events are triggered during the content creation process. The majority of these events are called in many views many components and modules - they are generally not specific for the com_content component. This list gives a brief description of each event, what their parameters are, and some examples of their use in core plugins.

==onContentPrepare==
===Description===
This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work. Since the article and related parameters are passed by reference, event handlers can modify them prior to display.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> A reference to the article that is being rendered by the view (For example: the text of a com_content article can be found with $article->text).
*<code>&params</code> A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
*<code>page</code> An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===Return Value===
None. Results are returned by modifying the referenced arguments. Sometimes a boolean might be returned to check for success or failure of the event.

===Example===
*<tt>[https://github.com/joomla/joomla-cms/blob/staging/plugins/content/emailcloak/emailcloak.php plugins/content/emailcloak/emailcloak.php]</tt>

==onContentAfterTitle==
===Description===
This event only exists in Joomla {{JVer|3.x}}. This is a request for information that should be placed between the content title and the content body. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose. Note this event has special purpose in com_content for use in handling the introtext.

===Parameters===
See the onContentPrepare event for additional discussion of these parameters.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> An associative array of relevant parameters.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

==onContentBeforeDisplay==
===Description===
This is a request for information that should be placed immediately before the generated content. For views that generate HTML, this might include the use of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose.

===Parameters===
See the onContentPrepare event for additional discussion of these parameters. Note that unlike onContentPrepare, these parameters are passed by value.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> An associative array of relevant parameters.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

===Example===
*<tt>[https://github.com/joomla/joomla-cms/blob/staging/plugins/content/vote/vote.php#L17 plugins/content/vote/vote.php]</tt>

==onContentAfterDisplay==
===Description===
This is a request for information that should be placed immediately after the generated content. For views that generate HTML, this might include the closure of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onContentPrepare for that purpose.

===Parameters===
See the onContentPrepare event for additional discussion of these parameters. Note that unlike onContentPrepare, these parameters are passed by value.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> A JRegistry object of merged article and menu item params.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

==onContentBeforeSave==
===Description===
This is an event that is called right before the content is saved into the database. You can abort the save by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data.
*<code>isNew</code> A boolean which is set to true if the content is about to be created.
*<code>data</code> The data to save. Note this data should be already validated by the extension. Since {{JVer|3.7}}. Required to be set by extensions as of {{JVer|4.0}} as the core joomla content plugin uses this property

===Return Value===
Boolean. Result will affect the saving process. See description for details.

==onContentAfterSave==
===Description===
This is an event that is called after the content is saved into the database. Even though article object is passed by reference, changes will not be saved since storing data into database phase is past. An example use case would be redirecting user to the appropriate place after saving.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data.
*<code>isNew</code> A boolean which is set to true if the content is about to be created.

===Return Value===
None. Result will be omitted.

==onContentPrepareForm==
===Description===
Called before a JForm is rendered. It can be used to modify the JForm object in memory before rendering. For example, use JForm->loadFile() to add fields or JForm->removeField() to remove fields. Or use JForm->setFieldAttribute() or other JForm methods to modify fields for the form.

===Parameters===
*<code>form</code> The JForm object to be displayed. Use the $form->getName() method to check whether this is the form you want to work with.
*<code>data</code> An object containing the data for the form.

===Return Value===
*<code>boolean</code> True if method succeeds.

===Example===
*[https://github.com/joomla/joomla-cms/blob/staging/plugins/user/profile/profile.php#L234 plugins/user/profile/profile.php]

==onContentPrepareData==
===Description===
Called after the data for a JForm has been retrieved. It can be used to modify the data for a JForm object in memory before rendering. This is usually used in tandem with the onContentPrepareForm method - this event adds the data to the already altered JForm.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>data</code> An object containing the data for the form.

===Return Value===
*<code>boolean</code> True if method succeeds.

===Example===
*[https://github.com/joomla/joomla-cms/blob/staging/plugins/user/profile/profile.php#L68 plugins/user/profile/profile.php]

==onContentBeforeDelete==
===Description===
This is an event that is called right before the content is deleted from the database. You can abort the delete by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>data</code> A reference to the JTableContent object that is being deleted which holds the article data.

===Return Value===
Boolean. Result will affect the saving process. See description for details.

===Example===
*[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/joomla/joomla.php#L89 plugins/content/joomla/joomla.php]

==onContentAfterDelete==
===Description===
This is an event that is called after the content is deleted from the database. An example use case would be redirecting user to the appropriate place after deleting.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that has been deleted which holds the article data.

===Return Value===
None. Result will be omitted.

===Example===
[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L61 content/finder/finder.php]

==onContentChangeState==
===Description===
This is an event that is called after content has its state change (e.g. Published to Unpublished).

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>$pks</code> An array of primary key ids of the content that has changed state.
*<code>$value</code> The value of the state that the content has been changed to.

===Return Value===
None. Result will be omitted.

===Example===
[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L80 content/finder/finder.php]

==onContentSearch==
===Description===

This event is triggered by a variety of search related operations. It is a request for a
plugin to return the result of a search request. The rows must return the following fields, which are used in a common display routine:

* browsernav
* catslug
* created
* href
* section
* slug
* text
* title

===Parameters===

* <code>$text</code> The target search string.
* <code>$phrase</code> A string matching option (exact|any|all). Default is "any".
* <code>$ordering</code> A string ordering option (newest|oldest|popular|alpha|category). Default is "newest".
* <code>$areas</code> An array if restricted to areas, null if search all.

===Return Value===

Array of stdClass objects with members as described above.

===Used in files===

* <tt>[https://github.com/joomla/joomla-cms/blob/master/administrator/components/com_search/models/searches.php#L158 administrator/components/com_search/models/searches.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/components/com_search/models/search.php#L154 components/com_search/models/search.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/categories/categories.php#L62 plugins/search/categories/categories.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/contacts/contacts.php#L60 plugins/search/contacts/contacts.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/content/content.php#L53 plugins/search/content/content.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/newsfeeds/newsfeeds.php#L60 plugins/search/newsfeeds/newsfeeds.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/tags/tags.php#L60 plugins/search/tags/tags.php]</tt>
* <tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/search/weblinks/weblinks.php#L62 plugins/search/weblinks/weblinks.php]</tt>

==onContentSearchAreas==
===Description===

This appears to be a request for plugins to identify which "areas" they provide
search facilities for.

===Parameters===

None.

===Return Value===

An associative array of area names, indexed by the area identifier. For example, array( 'categories' => 'Categories' ).

===Used in files===

* <tt>components/com_search/models/search.php</tt>
* <tt>plugins/search/categories.php</tt>
* <tt>plugins/search/contacts.php</tt>
* <tt>plugins/search/content.php</tt>
* <tt>plugins/search/newsfeeds.php</tt>
* <tt>plugins/search/tags/tags.php</tt>
* <tt>plugins/search/weblinks.php</tt>

<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude>

User Group List form field type

2024-07-16T15:49:24Z

Robbiej: Added deprecation notice and link to Joomla Manual

Usergroup form field type

2024-07-16T15:48:05Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|Since Joomla 4 this field is no longer available. Please see [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/usergrouplist Joomla Manual Usergrouplist Field] instead}}

<translate>
The '''usergroup''' form field type provides a dropdown select box of user groups.</translate>

<translate>
* '''type''' (mandatory) must be ''usergroup''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the ''value_field'' attribute.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field.</translate>
<translate>
* '''size''' (optional) is the width of the text box in characters. If omitted the width is determined by the browser. The value of size does not limit the number of characters that may be entered.</translate>
<translate>
* '''multiple''' (optional) If set to ''multiple'' then allows more than one usergroup to be selected.</translate>

<translate>
Implemented by:</translate> <tt>libraries/joomla/form/fields/usergroup.php</tt>

<translate>
Example usergroup form field definition:</translate>

<source lang="xml">
<field name="guest_usergroup" type="usergroup"
label="COM_USERS_CONFIG_FIELD_GUEST_USER_GROUP_LABEL"
description="COM_USERS_CONFIG_FIELD_GUEST_USER_GROUP_DESC"
multiple="true" />
</source>

<translate>=== See also === </translate>
<translate>
* [[S:MyLanguage/Standard form field types|List of standard form field types]]</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

User form field type

2024-07-16T15:44:54Z

Robbiej: Added deprecation notice and link to Joomla Manual

URL form field type

2024-07-16T15:43:43Z

Robbiej: Added deprecation notice and link to Joomla Manual

Timezone form field type

2024-07-16T15:41:23Z

Robbiej: Added deprecation notice and link to Joomla Manual

Textarea form field type

2024-07-16T15:40:06Z

Robbiej: Added deprecation notice and link to Joomla Manual

Text form field type

2024-07-16T15:38:48Z

Robbiej: Added deprecation notice and link to Joomla Manual

Templatestyle form field type

2024-07-16T15:37:41Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/templatestyle Joomla Manual Templatestyle Field] instead}}

<translate>
Provides a dropdown list of style options.</translate>

<translate>
* '''name''' (mandatory) is the unique name of the parameter.</translate>
<translate>
* '''type''' (mandatory) must be ''templatestyle''.</translate>
<translate>
* '''client''' (optional) administrator, defaults to site.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' description text for the form field.</translate>
<translate>
* '''class''' (optional) for styling.</translate>
* '''multiple''' <translate>(optional) is whether multiple items can be selected at the same time (''true'' or ''false''). In Joomla 4 it is recommended to use additionally <code>layout="joomla.form.field.groupedlist-fancy-select"</code> in the field declaration (= <code>chosen</code> replacement).</translate>

<translate>
Example XML Definition :</translate>
<source lang="xml">
<field name="admin_style" type="templatestyle"
client="administrator"
description="COM_ADMIN_USER_FIELD_BACKEND_TEMPLATE_DESC"
label="COM_ADMIN_USER_FIELD_BACKEND_TEMPLATE_LABEL" >
<option value="">JOPTION_USE_DEFAULT</option>
</field></source>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Tel form field type

2024-07-16T15:36:29Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|Since Joomla 4 this field is not supported. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/telephone Joomla Manual Telephone Field] instead}}

The tel field type is an alias for a [[Text_form_field_type | text field]].

Telephone numbers can be validated using the tel rule and filtered using the tel input filter.

Tag form field type

2024-07-16T15:34:23Z

Robbiej: Added deprecation notice and link to Joomla Manual

Subform form field type

2024-07-16T15:32:42Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/subform Joomla Manual Subform Field] instead}}

<translate>
The '''subform''' form field type provides a method for using XML forms inside one another or reuse forms inside an existing form.</translate>
<translate>
If attribute '''multiple''' is set to '''true''' then the included form will be '''repeatable'''.</translate>

<translate>
The Field has two "predefined" layouts for displaying the subform as either a '''table''' or as a '''div''' container, as well as support for custom layouts.</translate>

<translate>
An example XML '''field''' definition for '''single''' mode:</translate>

<source lang="xml"><field name="field-name" type="subform"
formsource="path/to/exampleform.xml"
label="Subform Field" description="Subform Field Description" /></source>

<translate>
An example XML '''field''' definition for '''multiple''' mode:</translate>

<source lang="xml"><field name="field-name" type="subform"
formsource="path/to/exampleform.xml" multiple="true"
label="Subform Field" description="Subform Field Description" /></source>

<translate>
Example XML of ''exampleform.xml''</translate>

<source lang="xml"><?xml version="1.0" encoding="UTF-8"?>
<form>
<field name="example_text" type="text" label="Example Text" />
<field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</form></source>

<translate>
An example XML of ''exampleform.xml'' with ''fieldsets''</translate>

<source lang="xml"><?xml version="1.0" encoding="UTF-8"?>
<form>
<fieldset name="section1" label="Section1">
<field name="example_text" type="text" label="Example Text" />
<field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</fieldset>
<fieldset name="section2" label="Section2">
<field name="example_list" type="list" default="1" class="advancedSelect" label="Example List">
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>
</form></source>

<translate> The subform XML may also be specified inline as an alternative to placing the subform XML in a separate file. The following example illustrates this:</translate>

<source lang="xml"><?xml version="1.0" encoding="UTF-8"?>
<field
name="field-name"
type="subform"
label="Subform Field"
description="Subform Field Description"
multiple="true"
min="1"
max="10"
>
<form>
<field
name="example_text"
type="text"
label="Example Text"
/>
<field
name="example_textarea"
type="textarea"
label="Example Textarea"
cols="40"
rows="8"
/>
</form>
</field></source>

<translate>

Field attributes:</translate>
<translate>

* '''type''' (mandatory) must be ''subform''.</translate>
<translate>

* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>

* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>

* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>

* '''required''' (optional) The field must be filled before submitting the form.</translate>
<translate>

* '''message''' (optional) The error message that will be displayed instead of the default message.</translate>
<translate>

* '''default''' (optional) is the default value, JSON string.</translate>
<translate>

* '''formsource''' (mandatory) the form source to be included. A relative path to the xml file (relative to the root folder for the installed Joomla site) or a valid form name which can be found by ''JForm::getInstance()''.</translate>
<translate>

* '''multiple''' (optional) whether the subform fields are repeatable or not.</translate>
<translate>

* '''min''' (optional) count of minimum repeating in multiple mode. Default: ''0''.</translate>
<translate>

* '''max''' (optional) count of maximum repeating in multiple mode. Default: ''1000''.</translate>
<translate>

* '''groupByFieldset''' (optional) whether to group the subform fields by its fieldset (''true'' or ''false''). Default: ''false''.</translate>
<translate>

* '''buttons''' (optional) which buttons to show in multiple mode. Default: ''add,remove,move''.</translate>
<translate>

* '''layout''' (optional) the name of the layout to use when displaying '''subform''' fields.</translate>
<translate>

* '''validate''' (optional) should be set to ''Subform'' (note that this is case-sensitive!) to ensure that fields in the subform are individually validated. Default: Fields in the subform are not validated, even if validation rules are specified.
</translate>

<translate>

Available layouts:</translate>
<translate>

* '''joomla.form.field.subform.default''' render the subform in a div container, without support of repeating. Default for single mode.</translate>
<translate>

* '''joomla.form.field.subform.repeatable''' render the subform in a div container, used for multiple mode. Support groupByFieldset.</translate>
<translate>

* '''joomla.form.field.subform.repeatable-table''' render the subform as a table, used for multiple mode. Supports groupByFieldset. By default each field is rendered as a table column, but if ''groupByFieldset=true'' then each fieldset is rendered as a table column.</translate>

<translate>

'''Be aware'''</translate>

<translate>

If your field in the subform has additional JavaScript logic then it may not work in '''multiple''' mode, because do not see the fields which added by the subform field dynamically. If it happened then you need to adjust your field to support it.</translate>
<translate>

Next example may help:</translate>

<source lang="javascript">jQuery(document).ready(function(){
... here the code for setup your field as usual...

jQuery(document).on('subform-row-add', function(event, row){
... here is the code to set up the fields in the new row ...
})
});
</source>
<translate>


Because of this some extra Joomla! fields may not work for now.</translate>

<translate>
==Fields Validation and Filters== 
</translate>
<translate> The subform form field does not provide the Validation and Filters for child fields.</translate>

<translate>Addition: Since a security fix in Joomla 3.9.7 the <code>filter="example"</code> attributes in subform child fields are supported and the fields will be validated; '''but NOT''' in custom form fields that extend the <code>JFormFieldSubform</code> class. You have to adapt such custom fields yourself!
===Beware!=== 
'''All extensions that use subform fields MUST add an attribute <code>filter</code> to their subform child fields of type <code>editor</code>, <code>textarea</code>, <code>text</code> (maybe others, too) since Joomla 3.9.7 like it's common for "normal" JForm fields, if you want to allow HTML input. Otherwise the validation falls back to STRING, which is the common behavior for "normal" JForm fields.'''
Examples:
</translate>
<source lang="xml">
filter="safehtml"
filter="JComponentHelper::filterText"
filter="raw" (bad decision in most cases)
</source>
<translate>

== Example == 
</translate>

<translate>
'''Problem '''</translate>

<translate>
After adding new rows selects are not "chosen".</translate>

<translate>

'''Solution '''
</translate>

<translate>
Here is an example how to reinit jQuery Chosen on newly added repeated rows:</translate>

<source lang="javascript">jQuery(document).ready(function(){
jQuery(document).on('subform-row-add', function(event, row){
jQuery(row).find('select').chosen();
})
});
</source>

<translate>
Or a PHP snippet to be used in e.g. your plugin in **onBeforeCompileHead** method or in your component view.</translate>

<source lang="php">
$doc = JFactory::getDocument();
$js = '
jQuery(document).on(\'subform-row-add\', function(event, row){
jQuery(row).find(\'select\').chosen();
})
';
$doc->addScriptDeclaration($js);
</source>

<translate>
So newly added rows now are "chosen" now </translate>

'''Problem'''

Subform data not getting stored to database on custom component.

'''Solution'''

Add the following line to the beginning of your corresponding table class:

<source lang="php">
protected $_jsonEncode = array('fieldnamehere');
</source>

More information [https://joomla.stackexchange.com/questions/19163/subform-multiple-data-not-saving Here].

<translate>
== See also == </translate>
<translate>

* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
[[Category:Standard form field types{{#translation:}}]]
</noinclude>

SQL form field type

2024-07-16T15:31:21Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/sql Joomla Manual SQL Field] instead}}

{{Warning|<translate>
Using this generic form field type forces you to write SQL in an XML file and is rather limited. For more flexibility, consider creating your own, specific form field type by subclassing the JFormField class.</translate>}}

<translate>
The '''sql''' form field type provides a drop down list of entries obtained by running a query on the Joomla database. If the field has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.</translate>
[[Image:Params.sql.jpg|right]]
<translate>
* '''type''' (mandatory) must be ''sql''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field. This must match the name of the query results column that contains the values that will be shown to the user in the drop-down list, unless a different name is specified in the '''value_field''' attribute.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''query''' (mandatory if not using the sql_* attributes) is the SQL query which will provide the data for the drop-down list. The query must return two columns; one called ''<nowiki>'value'</nowiki>'' (unless overridden by the '''key_field''' attribute) which will hold the values of the list items; the other called the same as the value of the name attribute (unless overridden by the '''value_field''' attribute) containing the text to be shown in the drop-down list.</translate>
<translate>
* '''default''' (optional) is the default value. This is the value of the ''<nowiki>'value'</nowiki>'' column, unless overridden by the '''key_field''' attribute.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
* '''multiple''' (optional) turns the field into a multi-selector. Use multiple="multiple".
<translate>
* '''key_field''' (optional) is the name of the column that will contain values for the parameter. If omitted then the column called ''<nowiki>'value'</nowiki>'' will be used, if it exists.</translate>
<translate>
* '''value_field''' (optional) is the name of the column that will contain values to be shown to the user in the drop-down list. If omitted then the column with the same name as the name attribute will be used, if it exists.</translate>
<translate>
* '''translate''' (optional) will translate the output of the '''value_field''' if set to true. It defaults to false.</translate>
* '''header''' (optional) (translatable) will add an entry, with an empty value, at the top of the list of options. This is usually used to add a ''"- Select something -"'' entry to the list. See the examples for an alternative way of achieving this.
* '''sql_select''' (mandatory if not using the '''query''' attribute) is the SELECT clause of the SQL statement. Only one such clause is permitted.
* '''sql_from''' (mandatory if not using the '''query''' attribute) is the FROM clause of the SQL statement.
* '''sql_join''' (optional) is the LEFT JOIN clause of the SQL statement. Only one such clause is permitted.
* '''sql_where''' (optional) is the WHERE clause of the SQL statement. Only one such clause is permitted.
* '''sql_group''' (optional) is the GROUP BY clause of the SQL statement.
* '''sql_order''' (optional) is the ORDER BY clause of the SQL statement.
* '''sql_filter''' (optional) filters the list by the value of another field. A field name or a comma-separated list of field names can be given. The field names must correspond to column names in the database table being queried. See the examples for further explanation.
* '''sql_default_{FIELD_NAME}''' (optional) is the default value used by the '''sql_filter''' attribute when the value of the ''{FIELD_NAME}'' filter has not been set. See the examples for further explanation.

<translate>
Example XML parameter definition:</translate>
<source lang="xml">
<field
name="title"
type="sql"
default="10"
label="Select an article"
query="SELECT id AS value, title AS text FROM #__content"
/>
</source>

<translate>
Notice that an AS clause has been used in this example because the ''jos_content'' table does not have a column called ''<nowiki>'value'</nowiki>''. In fact very few tables in the Joomla database have a column called ''<nowiki>'value'</nowiki>''.</translate>
<translate>
Alternatively, you can use a '''key_field''' attribute to define the column to be used instead of ''<nowiki>'value'</nowiki>'':</translate>
<source lang="xml">
<field
name="title"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
/>
</source>
<translate>
This will give identical results to the previous example.</translate>

<translate>
Both column names may need to be aliased. For example, suppose you want your field to be called ''<nowiki>'myfield'</nowiki>'' instead of ''<nowiki>'title'</nowiki>'' in the previous example. Then you can do this:</translate>
<source lang="xml">
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id AS value, title AS myfield FROM #__content"
/>
</source>
<translate>
Or alternatively:</translate>
<source lang="xml">
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
/>
</source>
<translate>
You can also assemble or calculate fields in the SQL statement. For example, suppose you wanted to append the created date/time of each article to the article title in the list. Then you could use this SQL statement:</translate>
<source lang="sql">
SELECT id, concat( title, ' (', created, ')') AS title FROM #__content
</source>
<translate>
You can also specify a static option in the XML using <option></option> tag. Please look at the following example.</translate>
<source lang="xml">
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
required="true"
>
<option value="">Please select your option</option>
</field>
</source>
Alternatively, you can achieve the same result using the '''header''' attribute as follows:
<source lang="xml">
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
required="true"
header="Please select your option"
/>
</source>
==== Alternative query syntax ====
Starting with Joomla 3.5, an alternative to the '''query''' attribute allows some additional features. These features are not available if the '''query''' attribute is present. For example, this field definition:
<source lang="xml">
<field
name="example_group"
type="sql"
label="COM_EXAMPLE_GROUP"
query="SELECT e.* FROM #__example AS e GROUP BY name ORDER e.id ASC"
key_field="id"
value_field="name"
/>
</source>
can be expressed as:
<source lang="xml">
<field
name="example_group"
type="sql"
label="COM_EXAMPLE_GROUP"
sql_select="e.*"
sql_from="#__example AS e"
sql_group="name"
sql_order="e.id ASC"
key_field="id"
value_field="name"
/>
</source>
{{warning|<translate> The following feature ''linked fields as filters'' is currently not working! See [https://github.com/joomla/joomla-cms/issues/22241 Github issue 22241]</translate>}}
One advantage to using this syntax is that it allows the use of linked fields as filters. For example, suppose you have a form containing two select lists, one called ''groups'' and the other called ''subgroups''. The ''groups'' field is straightforward:
<source lang="xml">
<field name="groups"
type="sql"
label="COM_EXAMPLE_GROUPS"
sql_select="e.*"
sql_from="#__example_groups AS e"
sql_group="name"
sql_order="e.id ASC"
key_field="id"
value_field="name"
/>
</source>
but the ''subgroups'' field includes an '''sql_filter''' attribute which refers to the ''groups'' field by name:
<source lang="xml">
<field name="subgroups"
type="sql"
label="COM_EXAMPLE_SUBGROUPS"
sql_select="e.*"
sql_from="#__example_subgroups AS e"
sql_group="name"
sql_order="e.id ASC"
sql_filter="groups"
key_field="id"
value_field="name"
/>
</source>
Then if the ''groups'' field has the value ''99'', the following SQL statement will be executed for the ''subgroups'' field:
<source lang="sql">
SELECT e.* FROM jos_example_subgroups AS e WHERE `groups` = 99 GROUP BY `name` ORDER BY e.id ASC
</source>
To filter on multiple fields, you can use a comma-separated list of filter names in the '''sql_filter''' clause. For example, if there is a filter called ''groups'' with the value ''99'' and a filter called ''categories'' with the value ''12'', then
<source lang="xml">
sql_filter="groups,categories"
</source>
will produce the SQL WHERE clause:
<source lang="sql">
WHERE `groups` = 99 AND `categories` = 12
</source>
You can also define a default value for any filter that might not have a value when the field is evaluated by adding '''sql_default_{FIELD_NAME}''' attributes. For example, suppose that the default value for the ''groups'' filter is 0 and the default value for the ''categories'' filter is 0, then this definition:
<source lang="xml">
<field name="subgroups"
type="sql"
label="COM_EXAMPLE_SUBGROUPS"
sql_select="e.*"
sql_from="#__example_subgroups AS e"
sql_group="name"
sql_order="e.id ASC"
sql_filter="groups,categories"
sql_default_groups="0"
sql_default_categories="1"
key_field="id"
value_field="name"
/>
</source>
will produce this SQL statement when initially evaluated with no filters:
<source lang="sql">
SELECT e.* FROM jos_example_subgroups AS e WHERE `groups` = 0 AND `categories` = 1 GROUP BY `name` ORDER BY e.id ASC
</source>
<translate>
Note: The SQL statements will need to be correct for the type and version of the underlying database that Joomla is running on. This will most likely be a version of MySQL, but it could be something else. There is no capability to query databases other than the one Joomla itself is running on.</translate>

<translate>
Note: As shown in these examples, the database prefix (often <code>jos</code>) should be entered in the form <code>#__</code> (hash-underscore-underscore). It will automatically be replaced by the actual database prefix used by Joomla.</translate>

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

Spacer form field type

2024-07-16T15:29:14Z

Robbiej: Added deprecation notice and link to Joomla Manual

Sessionhandler form field type

2024-07-16T15:27:55Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/sessionhandler Joomla Manual Sessionhandler Field] instead}}

<translate>
Provides a dropdown list of session handler options.</translate>

<translate>
* '''name''' (mandatory) is the unique name of the parameter.</translate>
<translate>
* '''type''' (mandatory) must be ''sessionhandler''.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' description text for the form field.</translate>
<translate>
* '''default''' (optional) provides a default value.</translate>
<translate>
* '''required''' (optional) "true" to enforce a value.</translate>
<translate>
* '''filter''' (optional) cleans the input.</translate>

<translate>
Example XML Definition:</translate>
<source lang="xml">
<field name="session_handler" type="sessionhandler"
default="none"
label="COM_CONFIG_FIELD_SESSION_HANDLER_LABEL"
description="COM_CONFIG_FIELD_SESSION_HANDLER_DESC"
required="true"
filter="word" />
</source>

<noinclude><translate>
[[Category:Standard form field types]]</translate></noinclude>

Rules form field type

2024-07-16T15:26:28Z

Robbiej: Added deprecation notice and link to Joomla Manual

Repeatable form field type

2024-07-16T15:25:06Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|Since Joomla 4 this field is no longer available. Please use the [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/subform Subform Field] instead}}

{{tip|<translate>
Please use the [[S:MyLanguage/Subform form field type|Subform form field type]] (in multiple mode) instead.</translate>|title=<translate>
This field is '''deprecated'''</translate>}}

<translate>
Provides a modal with rows of formfields that you specify. As many options can be added as desired. Note this form field has a jQuery based javascript file as a dependency.</translate>

<translate>
* '''name''' (mandatory) is the unique name of the parameter.</translate>
<translate>
* '''type''' (mandatory) must be ''repeatable''.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' description text for the form field. Displays at the top of the modal with the name as well as in the usual position in the form.</translate>
<translate>
* '''default''' The default value for the form field if the field is left empty. Note this has to be a json string compatible with the contents of the form field.</translate>
<translate>
* '''id''' id of the hidden form field. (the modal will have this id with an added suffix of "_modal" and the table within the modal will have this id with a suffix of "_modal_table").</translate>
<translate>
* '''class''' class of the table.</translate>
<translate>
* '''select''' (translatable) The text to show on the modal button.</translate>
<translate>
* '''icon''' the icon to show on the select button (is prefixed with "icon-").</translate>
<translate>
* '''maximum''' the maximum number of rows of fields allowed (by default 999 to be effectively infinite).</translate>

<translate>
To create a form field you must first of all create a repeatable form field as usual.</translate>
<source lang="php">
<fields></source>
<translate>
Within this you place open and close tag (if not already in one - if there is an existing fields tag for params etc. this is not needed.) and within this a tag.</translate>
<source lang="php">
<fieldset></source>
<translate>
The fieldset tag MUST have a name the same as your repeatable field name with "_modal" appended to the end of it - it should also have the in the fieldset tag.</translate>
<source lang="php">
repeat="true"</source>
<translate>
Within this fieldset you then include the form fields that you wish to have repeating (as with any form field).</translate>

<translate>
Example XML Definition</translate>
<source lang="xml">
<field name="list_templates"
type="repeatable"
icon="list"
description="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_DESC"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_ELEMENTS_LABEL"
default='{"template":["Layout","Simple snippet"],
"location":["layout1.html","snippet1.html"],
"description":["HTMLLayout","Simple HTML snippet"]}'>
<fieldset hidden="true" name="list_templates_modal" repeat="true">
<field name="template"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_NAME_LABEL"
size="30"
type="text" />
<field name="location"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_LOCATION_LABEL"
description="PLG_TINY_FIELD_TEMPLATE_LOCATION_DESC"
size="30"
type="filelist"
directory="media/editors/tinymce/templates"
exclude="index.html"
hide_default="true"
hide_none="true" />
<field name="description"
label="PLG_TINY_FIELD_TEMPLATE_FIELD_DESCRIPTION_LABEL"
size="30"
type="textarea" />
</fieldset>
</field>
</source>
<translate>
===Considerations for the default value === 
</translate>
<translate>
* The default may contain spaces tabs and new lines <ref>https://tools.ietf.org/html/rfc7158</ref> (makes for better readability)</translate>
<translate>
* The data elements within the string must be quoted using " instead of '. Failure to do so will cause the json decode to fail on the default values.</translate>

<translate>
===Retrieving your data=== 
</translate>
<translate>
The settings of a repeatable form field are returned as a json encoded array (same as the default)</translate>

<source lang="php">
// get the repeatable field value and decode it
$list_hosts = json_decode( $params->get('list_templates'),true);
// loop your result
foreach( $list_templates as $list_templates_idx => $list_template ) {
// do something clever for each of the templates
}
</source>
<translate>

===References=== 
</translate>
<references>
</references>
<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Range form field type

2024-07-16T15:22:33Z

Robbiej: Added deprecation notice and link to Joomla Manual

{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/range Joomla Manual Range Field] instead}}

The ‘''range''' form field type provides a horizontal slider for numeric input. While the default value can be set, there is no indication of the actual value being chosen, just the position of the slider’s thumb. Available from {{JVer|3.2}}

* '''type''' (mandatory) must be ''range''.

* '''name''' (mandatory) is the unique name of the field.

* '''label''' (optional) (translatable) is the descriptive title of the field, and will appear in the pop-up when hovering over label as well.

* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the label.

* '''default''' (optional) (translatable) is the initial default value.

* '''class''' (optional) is a CSS class name for the HTML form field.

* '''min''' (optional) this value is the lowest that can be chosen.

* '''max''' (optional) this value is the highest that can be chosen.

* '''step''' (optional) if user click up/down arrow current value will change by this attribute (this attribute value will be added or subtracted to current field value).

* '''required''' (optional) should the user be required to enter data in this field?

Example XML field definition which would create a slider having the initial value of 0, with possibility to choose values between -0.5 and 0.5. The slider’s value changes by 0.1 as the slider is moved left or right.
<source lang="xml"><field name="myrange" type="range" default="0" label="Range from -0.5 to 0.5 step 0.1" description="" min="-0.5" max="0.5" step="0.1" /></source>

=== See also ===

<noinclude>
[[Category:Standard form field types]]
</noinclude>

Radio form field type

2024-07-16T15:21:00Z

Robbiej: Added deprecation notice and link to Joomla Manual

Predefined List form field type

2024-07-15T21:33:08Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/predefinedlist Joomla Manual PredefinedList Field] instead}}

The '''PredefinedList''' form field type provides a drop down list of pre-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

Largely the configuration options are the same as that of the list field however the values for the field are created by the <source lang="php" inline>predefinedOptions</source> class variable. So the following variables have the same meaning as the list field:

[[Image:Params.list.jpg|right]]
* '''type''' (mandatory) must be ''PredefinedList''.
* '''name''' (mandatory) is the unique name of the field.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''default''' (optional) is the default list item 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 'inputbox'.
* '''multiple''' (optional) is whether multiple items can be selected at the same time (''true'' or ''false'').
* '''required''' (optional) if set to true, the first field option should be empty, see last example.
* '''useglobal''' (optional) if set to true, it will show the value that is set in the global configuration if found in the database.

Example XML field definition:
<source lang="xml"><field name="mylistvalue" type="Myextension.Mycustompredefinedlist" default="" label="Select an option" description="">
</field>
</source>

this would be accompanied by your field defined in PHP which would look like:

<source lang="php">
class MyextensionFormFieldMycustompredefinedlist extends JFormFieldPredefinedList
{
public $type = 'Mycustompredefinedlist';

protected $predefinedOptions = array(
'1' => 'COM_FOO_LABEL_FOR_TRANSLATION',
'0' => 'COM_FOO_ANOTHER_LABEL_FOR_TRANSLATION',
);
}
</source>

Additionally in PHP you can set the `translate` class variable to false which will cause the values of your predefined option to not pass through JText for translation before being shown to the user.

<noinclude>
[[Category:Standard form field types{{#translation:}}]]
</noinclude>

Plugins form field type

2024-07-15T21:29:35Z

Robbiej: Added deprecation notice and link to Joomla Manual

Password form field type

2024-07-15T21:28:17Z

Robbiej: Added deprecation notice and link to Joomla Manual

Number form field type

2024-07-15T21:21:51Z

Robbiej: Added deprecation notice and link to Joomla Manual

Note form field type

2024-07-15T21:20:43Z

Robbiej: Added deprecation notice and link to Joomla Manual

ModuleTag form field type

2024-07-15T21:19:04Z

Robbiej: Added deprecation notice and link to Joomla Manual

ModulePosition form field type

2024-07-15T21:17:52Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/moduleposition Joomla Manual ModulePosition Field] instead}}

<translate>

Provides a text input and button to set the position of a module.
</translate>

* '''type''' <translate>
(mandatory) must be ''moduleposition''.</translate>
* '''name''' <translate>
(mandatory) is the unique name of the field.</translate>
* '''label''' <translate>
(mandatory) (translatable) is the descriptive title of the field.</translate>
* '''description''' <translate>
(optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>

<translate>
Example XML Definition</translate>

<source lang="xml">
<field name="position" type="moduleposition"
description="COM_MODULES_FIELD_POSITION_DESC"
label="COM_MODULES_FIELD_POSITION_LABEL"
default=""
maxlength="50" />
</source>

<translate>

If adding this field to a fieldset outside of the com_modules scope you will have to include '''addfieldpath="administrator/components/com_modules/models/fields"''' in your '''<fieldset>''' tag
</translate>

<source lang="xml">
<fieldset name="fieldsetname" label="myfield"
addfieldpath="administrator/components/com_modules/models/fields"
>
</source>

<translate>

If set up properly, you will see a button displayed next to the textbox (with Joomla standard language text that you can set up to say what you wish in your language file) which when clicked, brings up the standard module position selection window you're used to seeing in the Module Manager.
</translate>

<translate>

[[Category:Standard form field types]]
</translate>

ModuleOrder form field type

2024-07-15T21:16:31Z

Robbiej: Added deprecation notice and link to Joomla Manual

Modulelayout form field type

2024-07-15T21:15:09Z

Robbiej: Added deprecation notice and link to Joomla Manual

Meter form field type

2024-07-15T21:13:52Z

Robbiej: Added deprecation notice and link to Joomla Manual

Menuitem form field type

2024-07-15T21:12:40Z

Robbiej: Added deprecation notice and link to Joomla Manual

Menu form field type

2024-07-15T21:11:22Z

Robbiej: Added deprecation notice and link to Joomla Manual

Media form field type

2024-07-15T21:10:04Z

Robbiej: Added deprecation notice and link to Joomla Manual

<noinclude><languages /></noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/media Joomla Manual Media Field] instead}}

<translate>
The '''media''' form field type provides modal access to the media manager for the choice of an image or other kind of media, e.g. video. Users with appropriate permissions will be able to upload files.</translate>

<translate>
* '''type''' (mandatory) must be ''media''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''directory''' (optional) is the directory from which the user will be able to choose a file. This attribute should be relative to the top level <code>/images/</code> folder. The default is that the user will be confined to the top level <code>/images/</code> folder.</translate>
<translate>
* '''preview''' (optional) shows or hides the preview of the currently chosen image. ("true": Show always, "tooltip": Show as tooltip, "false": Show never). Default is "tooltip". (since Joomla! 2.5.5)</translate>
<translate>
* '''preview_width''' (optional) sets the max-width of preview image (default: "200").</translate>
<translate>
* '''preview_height''' (optional) sets the max-height of preview image (default: "200").</translate>
<translate>
* '''types''' (optional) is a comma-separated list of file types ("images", "audios", "videos" and "documents"). Default is "images". This list decides which of the allowed file extensions from Media Manager configuration are used. E.g. "images,documents" means only files with an allowed images extension or an allowed documents extension are available for selection. (since Joomla! 4.0.0)</translate>

<translate>
Example XML field definition:</translate>
<source lang="xml">
<field name="myimage" type="media" directory="stories" />
</source>

<translate>
This will open the media manager with the directory <code>/images/stories/</code> already selected.</translate>

<translate> Note that if you are using this field on the frontend then permissions restrictions are likely to be in force. If the user is not authorised to view or add media they will see an error page in the modal popup ("403 You are not authorised to view this resource.").</translate>

<translate>=== See also === </translate>
<translate>

* [[S:MyLanguage/File form field type|File form field type]]
* [[S:MyLanguage/Imagelist form field type|Imagelist form field type]]
* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
[[Category:Standard form field types{{#translation:}}]]
</noinclude>

List form field type

2024-07-15T21:08:37Z

Robbiej: Added deprecation notice and link to Joomla Manual

Language form field type

2024-07-15T21:07:14Z

Robbiej: Added deprecation notice and link to Joomla Manual

Integer form field type

2024-07-15T21:05:42Z

Robbiej: Added deprecation notice and link to Joomla Manual

Imagelist form field type

2024-07-15T21:04:19Z

Robbiej: Added deprecation notice and link to Joomla Manual

Hidden form field type

2024-07-15T18:48:11Z

Robbiej: Added deprecation notice and link to Joomla Manual

Helpsite form field type

2024-07-15T18:46:51Z

Robbiej: marked as obsolete

<noinclude><languages /></noinclude>
{{Warning|Since Joomla 4 the Helpsite Form Field type is no longer available}}

<translate>
The '''helpsite''' form field type provides a drop down list of the help sites in your Joomla installation. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected. With the exception of the “Local” entry, which is always added, the list of help sites is generated from the file:</translate>
[[Image:Params.helpsites.jpg|right]]

<translate>
The 'local' string is translatable. The 'local' URL returned is an empty string.</translate>

<translate>
* '''type''' (mandatory) must be ''helpsite''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default help site URL (not the visible help site name).</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>

<translate>
Example XML parameter definition:</translate>

<source lang="xml"><field name="myhelpsite" type="helpsite" default="" label="Select a help site" description="" /></source>

<translate>=== See also === </translate>
<translate>
* [[S:MyLanguage/Standard form field types|List of standard form field types]]</translate>

<noinclude><translate>
[[Category:Standard form field types]]</translate></noinclude>