Joomla! Documentation - User contributions [en]

Archived:Adding custom fields to the article component

2012-06-29T21:17:33Z

Znarf: /* Extension Files */

This tutorial is for Joomla {{JVer|2.5}}

== Intro ==
This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article component (com_content), without the need to change core files. Capabilities that are implemented in this demo package include:

# Adding extra fields to the back-end article manager.
# Adding extra fields to the front-end article editor.
# Storing the values of the custom fields into a database table.
# Converting the field values into a HTML table which is injected into the displayed article.

A capability which is present but not demonstrated, is integrating the values of the custom fields into other components and views, such as article lists or category blogs.

== This example ==
This example adds food ratings to articles. These ratings consist of texture, temperature and taste. When present, they will be displayed as a simple table. This table is positioned before the article content.
[[File:Plg_content_rating-1.png|thumb|frame|none|alt=example of rendered article|An example of how the plugin places the table at the beginning of an article]]

Setting the values of these fields can be done in both the backend and frontend.
[[File:Plg_content_rating-frontend.png|thumb|frame|left|alt=edit article frontend|Accessing the additional fields through the frontend]]
[[File:Plg_content_rating-backend.png|thumb|frame|none|alt=edit article backend|... and the backend]]

== Framework ==
Within Joomla, the article manager is basically a form driven component. Both in the backend as the frontend. When handling a form, the framework performs the following actions.

# Loads the form description. This is a XML structure.
# Loads the data from the user state if present, and if not from the database.
# Injects the data into the form
# Renders/displays the form for the user to work on.

When the user is finished and issues a <code>SAVE</code>, the framework will:

# Captures the submitted data
# Loads the form description.
# Validates the data against the form description.
# If validation fails, stores the data in the user state and starts from the beginning.
# Updates the database accordingly

The framework has placeholders for all these moments. This example plugin will hook into these placeholders, expanding the form and data with additional custom fields.

The hooks are:
*<code>onContentPrepareForm()</code>
*:Called after loading the form description. It will add an extra form group containing the additional fields
*<code>onContentPrepareData()</code>
*:Called after loading the article from the database. It will inject the additional fields and their value into the article.
*<code>onContentAfterSave()</code>
*:Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.
*<code>onContentAfterDelete()</code>
*:Called after an article has been deleted (emptying of trash). It will delete the additional fields.
*<code>onContentPrepare()</code>
*:Called before the article will be rendered/displayed. It will inject the rating values as a table at the beginning of the article, if values have been entered.

== Database ==
The contents of the extra custom fields need to be stored in the database. Ideally would be if they have their own dedicated database table. This however, requires considerable extension overhead. With Joomla 2.5 is is possible to extend the user profile. The extra fields are stored in the table <code>#__user_profiles</code>. That table is constructed and used in such a manner that it can also hold the extra article fields. [I would like to spark the discussion to evolve <code>#__user_profiles</code> into a generic table for expanding core tables.]

This plugin example will use table <code>#__user_profiles</code> to store the extra fields. It will use the tables <code>user_id</code> as <code>article_id</code>

== Extension files ==
The example plugin contains the following files. It has an extra directory <code>rating</code>. The primary reason is that it contains a XML file that is not a manifest. If it were located in the plugin top-level directory, the installer would find it and mistakenly identify it as an orphaned plugin. This would result in the form showing up when 'Discovering' lost extensions.

<pre>
── plugins/content/rating
├── language
│ └── en-GB
│ ├── en-GB.plg_content_rating.ini [language file]
│ └── en-GB.plg_content_rating.sys.ini [language file]
├── rating
│ ├── rating.css [CSS for the rendered rating table]
│ └── rating.xml [Form description]
├── rating.php [Plugin hooks]
└── rating.xml [Manifest]
</pre>

=== Manifest ===
A regular plugin manifest which takes an extra configuration argument, a CSS name that is tagged onto the rendered rating table.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="content" method="upgrade">
<name>plg_content_rating</name>
<author>Joomla! Project</author>
<creationDate>June 2012</creationDate>
<copyright>(C) 2005 - 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>2.5.0</version>
<description>PLG_CONTENT_RATING_XML_DESCRIPTION</description>

<files>
<folder>language</folder>
<folder>rating</folder>
<filename plugin="rating">rating.php</filename>
<filename>index.html</filename>
</files>

<config>
<fields name="params">
<fieldset name="basic">
<field
name="ratingclass_sfx"
type="text"
label="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL"
description="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC"
/>
</fieldset>
</fields>
</config>
</extension>
</source>

=== language files ===

<source>
; Joomla! Project
; Copyright (C) 2005 - 2012 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php

PLG_CONTENT_RATING="Content - Rating"
PLG_CONTENT_RATING_XML_DESCRIPTION="[plg_content_rating] Example plugin on how to add custom fields (texture/temperature/taste) to articles (com_content). Adds ratings to an article, and display them as a table before the article content."
PLG_CONTENT_RATING_SLIDER_LABEL="Rating Options"
PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL="Texture"
PLG_CONTENT_RATING_FIELD_TEXTURE_DESC="What does the sample feel like"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL="Temperature"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC="What is the temperature of the sample"
PLG_CONTENT_RATING_FIELD_TASTE_LABEL="Taste"
PLG_CONTENT_RATING_FIELD_TASTE_DESC="How does the sample taste"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL="Rating Class"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC="Optional CSS class to add to the rating. This allows CSS styling specific to the page."
</source>

=== CSS ===
The CSS file for the rendered table.

<source lang="css">
div.rating {
display: block;
float: left;
padding-right: 10px;
}
div.rating table tr td {
margin: 1px !important;
padding: 2px !important;
}
div.rating table tr.row0 {
background-color:#efefef;
}
div.rating table tr.row1 {
background-color:#ffffff;
}
</source>

=== Form description ===
The form containing the custom fields.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="rating">
<fieldset name="rating" label="PLG_CONTENT_RATING_SLIDER_LABEL">
<field
name="texture"
type="text"
id="texture"
description="PLG_CONTENT_RATING_FIELD_TEXTURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEXTURE_MESSAGE"
size="30"
/>
<field
name="temperature"
type="text"
id="temperature"
description="PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEMPERATURE_MESSAGE"
size="30"
/>
<field
name="taste"
type="text"
id="taste"
description="PLG_CONTENT_RATING_FIELD_TASTE_DESC"
label="PLG_CONTENT_RATING_FIELD_TASTE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TASTE_MESSAGE"
size="30"
/>
</fieldset>
</fields>
</form>
</source>

== Plugin hooks ==
The main file 'rating.php' contains the hooks which are called by the Joomla framework.

For all calls:
*The <code>$context</code> parameter is a string identifying the calling placeholder.
*The <code>$data</code> parameter is an object containing the form values
*The <code>$article</code> parameter is an object (<code>JTableContent</code>) representing the article.

=== <code>__construct</code> ===
The constructor. It loads the language file.

<source lang="php">
public function __construct(& $subject, $config)
{
parent::__construct($subject, $config);
$this->loadLanguage();
}
</source>

=== <code>onContentPrepareForm</code> ===
<code>onContentPrepareForm</code> extends the article manager form in both the front-end as the back-end. It loads the form fragment as described in <code>rating/rating.xml</code> and merges that into the framework form.

<source lang="php">
public public function onContentPrepareForm($form, $data)
{
if (!($form instanceof JForm))
{
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}

// Add the extra fields to the form.
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form->loadFile('rating', false);
return true;
}
</source>

=== <code>onContentPrepareData</code> ===
<code>onContentPrepareData()</code> is executed after an article is loaded from the <code>#__content</code> table. It will gather and merge the values of the custom fields, which are located in the table <code>#__user_profiles</code>.

The field <code>articleId</code> in <code>$data</code> contains the article record number. That number is used to retrieve the values of the custom fields. If no record number is present, or it is zero, then a new record is being create. When this occurs, <code>$data</code> gets populated with the default values from the form description xml.

It is important that when <code>onContentPrepareData()</code> returns, <code>$data</code> contains the custom fields. This is due to how the framework uses them as place holders. When a user saves a newly created article, and an error situation occurs (like some values are missing) the form data is temporarily stored in the user state. If the place holders are not present, their values will not be preserved. The user will notice this because the custom fields will get erased.

<source lang="php">
public function onContentPrepareData($context, $data)
{
if (is_object($data))
{
$articleId = isset($data->id) ? $data->id : 0;
if ($articleId > 0)
{
// Load the data from the database.
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('profile_key, profile_value');
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$query->order('ordering');
$db->setQuery($query);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum())
{
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the data.
$data->rating = array();

foreach ($results as $v)
{
$k = str_replace('rating.', '', $v[0]);
$data->rating[$k] = json_decode($v[1], true);
if ($data->rating[$k] === null)
{
$data->rating[$k] = $v[1];
}
}
} else {
// load the form
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form = new JForm('com_content.article');
$form->loadFile('rating', false);

// Merge the default values
$data->rating = array();
foreach ($form->getFieldset('rating') as $field) {
$data->rating[] = array($field->fieldname, $field->value);
}
}
}

return true;
}
</source>

=== <code>onContentAfterSave</code> ===
<code>onContentAfterSave()</code> is called after the article is stored into the database <code>#__content</code> table. It will extract the values of the custom fields and store them into a separate table.

<source lang="php">
public function onContentAfterSave($context, &$article, $isNew)
{
$articleId = $article->id;
if ($articleId && isset($article->rating) && (count($article->rating)))
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$query->clear();
$query->insert('#__user_profiles');
$order = 1;
foreach ($article->rating as $k => $v)
{
$query->values($articleId.', '.$db->quote('rating.'.$k).', '.$db->quote(json_encode($v)).', '.$order++);
}
$db->setQuery($query);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentAfterDelete</code> ===
<code>onContentAfterDelete()</code> is called after the article is deleted from the database <code>#__content</code> table. It will delete the linked custom fields which are stored in a separate table.

<source lang="php">
public function onContentAfterDelete($context, $article)
{
$articleId = $article->id;
if ($articleId)
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete();
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);

if (!$db->query())
{
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentPrepare</code> ===
<code>onContentPrepare()</code> is called when the article is being prepared for display. This is the moment where HTML can be injected into what will be displayed.

<code>$params</code> are the article params, <code>$this->params</code> are the plugin configuration parameters as described in the manifest.

<source lang="php">
public function onContentPrepare($context, &$article, &$params, $page = 0)
{
if (!isset($article->rating) || !count($article->rating))
return;

// add extra css for table
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::base(true).'/plugins/content/rating/rating/rating.css');

// construct a result table on the fly
jimport('joomla.html.grid');
$table = new JGrid();

// Create columns
$table->addColumn('attr')
->addColumn('value');

// populate
$rownr = 0;
foreach ($article->rating as $attr => $value) {
$table->addRow(array('class' => 'row'.($rownr % 2)));
$table->setRowCell('attr', $attr);
$table->setRowCell('value', $value);
$rownr++;
}

// wrap table in a classed <div>
$suffix = $this->params->get('ratingclass_sfx', 'rating');
$html = '<div class="'.$suffix.'">'.(string)$table.'</div>';

$article->text = $html.$article->text;
}
</source>

== Prerequisites ==
This tutorial requires at least Joomla 2.5.x [to be determined] as the framework for previous versions misses a number of plugin hook place holders.

For Joomla 2.5 a patch file and for Joomla 2.5.6 a patch extension is available.

This patch has been submitted as [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 Joomla patch #28871].

== Extension Files ==

The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/trackeritem/28771/75015/patch_28771-2.5.6.patch.gz <code>patch_28771-2.5.6.patch.gz</code>] Joomla 2.5.6 unified diff patch
* [http://joomlacode.org/gf/download/trackeritem/28771/75012/patch_28771-2.5.6.zip <code>patch_28771-2.5.6.zip</code>] Patch as Joomla 2.5.6 installable component
* [http://joomlacode.org/gf/download/trackeritem/28771/75013/plg_content_rating-2.5.0.zip <code>plg_content_rating-2.5.0.zip</code>] The plugin as described in this tutorial

The tracker page for the patch. [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 <code>#28771</code>]. Patch [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28770 <code>#28770</code>] is also related.

== Contributors ==
*[[User:znarf|Franz Korntner]]

[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Development]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Adding custom fields to the article component

2012-06-29T21:12:22Z

Znarf: /* language files */

This tutorial is for Joomla {{JVer|2.5}}

== Intro ==
This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article component (com_content), without the need to change core files. Capabilities that are implemented in this demo package include:

# Adding extra fields to the back-end article manager.
# Adding extra fields to the front-end article editor.
# Storing the values of the custom fields into a database table.
# Converting the field values into a HTML table which is injected into the displayed article.

A capability which is present but not demonstrated, is integrating the values of the custom fields into other components and views, such as article lists or category blogs.

== This example ==
This example adds food ratings to articles. These ratings consist of texture, temperature and taste. When present, they will be displayed as a simple table. This table is positioned before the article content.
[[File:Plg_content_rating-1.png|thumb|frame|none|alt=example of rendered article|An example of how the plugin places the table at the beginning of an article]]

Setting the values of these fields can be done in both the backend and frontend.
[[File:Plg_content_rating-frontend.png|thumb|frame|left|alt=edit article frontend|Accessing the additional fields through the frontend]]
[[File:Plg_content_rating-backend.png|thumb|frame|none|alt=edit article backend|... and the backend]]

== Framework ==
Within Joomla, the article manager is basically a form driven component. Both in the backend as the frontend. When handling a form, the framework performs the following actions.

# Loads the form description. This is a XML structure.
# Loads the data from the user state if present, and if not from the database.
# Injects the data into the form
# Renders/displays the form for the user to work on.

When the user is finished and issues a <code>SAVE</code>, the framework will:

# Captures the submitted data
# Loads the form description.
# Validates the data against the form description.
# If validation fails, stores the data in the user state and starts from the beginning.
# Updates the database accordingly

The framework has placeholders for all these moments. This example plugin will hook into these placeholders, expanding the form and data with additional custom fields.

The hooks are:
*<code>onContentPrepareForm()</code>
*:Called after loading the form description. It will add an extra form group containing the additional fields
*<code>onContentPrepareData()</code>
*:Called after loading the article from the database. It will inject the additional fields and their value into the article.
*<code>onContentAfterSave()</code>
*:Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.
*<code>onContentAfterDelete()</code>
*:Called after an article has been deleted (emptying of trash). It will delete the additional fields.
*<code>onContentPrepare()</code>
*:Called before the article will be rendered/displayed. It will inject the rating values as a table at the beginning of the article, if values have been entered.

== Database ==
The contents of the extra custom fields need to be stored in the database. Ideally would be if they have their own dedicated database table. This however, requires considerable extension overhead. With Joomla 2.5 is is possible to extend the user profile. The extra fields are stored in the table <code>#__user_profiles</code>. That table is constructed and used in such a manner that it can also hold the extra article fields. [I would like to spark the discussion to evolve <code>#__user_profiles</code> into a generic table for expanding core tables.]

This plugin example will use table <code>#__user_profiles</code> to store the extra fields. It will use the tables <code>user_id</code> as <code>article_id</code>

== Extension files ==
The example plugin contains the following files. It has an extra directory <code>rating</code>. The primary reason is that it contains a XML file that is not a manifest. If it were located in the plugin top-level directory, the installer would find it and mistakenly identify it as an orphaned plugin. This would result in the form showing up when 'Discovering' lost extensions.

<pre>
── plugins/content/rating
├── language
│ └── en-GB
│ ├── en-GB.plg_content_rating.ini [language file]
│ └── en-GB.plg_content_rating.sys.ini [language file]
├── rating
│ ├── rating.css [CSS for the rendered rating table]
│ └── rating.xml [Form description]
├── rating.php [Plugin hooks]
└── rating.xml [Manifest]
</pre>

=== Manifest ===
A regular plugin manifest which takes an extra configuration argument, a CSS name that is tagged onto the rendered rating table.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="content" method="upgrade">
<name>plg_content_rating</name>
<author>Joomla! Project</author>
<creationDate>June 2012</creationDate>
<copyright>(C) 2005 - 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>2.5.0</version>
<description>PLG_CONTENT_RATING_XML_DESCRIPTION</description>

<files>
<folder>language</folder>
<folder>rating</folder>
<filename plugin="rating">rating.php</filename>
<filename>index.html</filename>
</files>

<config>
<fields name="params">
<fieldset name="basic">
<field
name="ratingclass_sfx"
type="text"
label="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL"
description="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC"
/>
</fieldset>
</fields>
</config>
</extension>
</source>

=== language files ===

<source>
; Joomla! Project
; Copyright (C) 2005 - 2012 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php

PLG_CONTENT_RATING="Content - Rating"
PLG_CONTENT_RATING_XML_DESCRIPTION="[plg_content_rating] Example plugin on how to add custom fields (texture/temperature/taste) to articles (com_content). Adds ratings to an article, and display them as a table before the article content."
PLG_CONTENT_RATING_SLIDER_LABEL="Rating Options"
PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL="Texture"
PLG_CONTENT_RATING_FIELD_TEXTURE_DESC="What does the sample feel like"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL="Temperature"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC="What is the temperature of the sample"
PLG_CONTENT_RATING_FIELD_TASTE_LABEL="Taste"
PLG_CONTENT_RATING_FIELD_TASTE_DESC="How does the sample taste"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL="Rating Class"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC="Optional CSS class to add to the rating. This allows CSS styling specific to the page."
</source>

=== CSS ===
The CSS file for the rendered table.

<source lang="css">
div.rating {
display: block;
float: left;
padding-right: 10px;
}
div.rating table tr td {
margin: 1px !important;
padding: 2px !important;
}
div.rating table tr.row0 {
background-color:#efefef;
}
div.rating table tr.row1 {
background-color:#ffffff;
}
</source>

=== Form description ===
The form containing the custom fields.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="rating">
<fieldset name="rating" label="PLG_CONTENT_RATING_SLIDER_LABEL">
<field
name="texture"
type="text"
id="texture"
description="PLG_CONTENT_RATING_FIELD_TEXTURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEXTURE_MESSAGE"
size="30"
/>
<field
name="temperature"
type="text"
id="temperature"
description="PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEMPERATURE_MESSAGE"
size="30"
/>
<field
name="taste"
type="text"
id="taste"
description="PLG_CONTENT_RATING_FIELD_TASTE_DESC"
label="PLG_CONTENT_RATING_FIELD_TASTE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TASTE_MESSAGE"
size="30"
/>
</fieldset>
</fields>
</form>
</source>

== Plugin hooks ==
The main file 'rating.php' contains the hooks which are called by the Joomla framework.

For all calls:
*The <code>$context</code> parameter is a string identifying the calling placeholder.
*The <code>$data</code> parameter is an object containing the form values
*The <code>$article</code> parameter is an object (<code>JTableContent</code>) representing the article.

=== <code>__construct</code> ===
The constructor. It loads the language file.

<source lang="php">
public function __construct(& $subject, $config)
{
parent::__construct($subject, $config);
$this->loadLanguage();
}
</source>

=== <code>onContentPrepareForm</code> ===
<code>onContentPrepareForm</code> extends the article manager form in both the front-end as the back-end. It loads the form fragment as described in <code>rating/rating.xml</code> and merges that into the framework form.

<source lang="php">
public public function onContentPrepareForm($form, $data)
{
if (!($form instanceof JForm))
{
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}

// Add the extra fields to the form.
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form->loadFile('rating', false);
return true;
}
</source>

=== <code>onContentPrepareData</code> ===
<code>onContentPrepareData()</code> is executed after an article is loaded from the <code>#__content</code> table. It will gather and merge the values of the custom fields, which are located in the table <code>#__user_profiles</code>.

The field <code>articleId</code> in <code>$data</code> contains the article record number. That number is used to retrieve the values of the custom fields. If no record number is present, or it is zero, then a new record is being create. When this occurs, <code>$data</code> gets populated with the default values from the form description xml.

It is important that when <code>onContentPrepareData()</code> returns, <code>$data</code> contains the custom fields. This is due to how the framework uses them as place holders. When a user saves a newly created article, and an error situation occurs (like some values are missing) the form data is temporarily stored in the user state. If the place holders are not present, their values will not be preserved. The user will notice this because the custom fields will get erased.

<source lang="php">
public function onContentPrepareData($context, $data)
{
if (is_object($data))
{
$articleId = isset($data->id) ? $data->id : 0;
if ($articleId > 0)
{
// Load the data from the database.
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('profile_key, profile_value');
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$query->order('ordering');
$db->setQuery($query);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum())
{
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the data.
$data->rating = array();

foreach ($results as $v)
{
$k = str_replace('rating.', '', $v[0]);
$data->rating[$k] = json_decode($v[1], true);
if ($data->rating[$k] === null)
{
$data->rating[$k] = $v[1];
}
}
} else {
// load the form
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form = new JForm('com_content.article');
$form->loadFile('rating', false);

// Merge the default values
$data->rating = array();
foreach ($form->getFieldset('rating') as $field) {
$data->rating[] = array($field->fieldname, $field->value);
}
}
}

return true;
}
</source>

=== <code>onContentAfterSave</code> ===
<code>onContentAfterSave()</code> is called after the article is stored into the database <code>#__content</code> table. It will extract the values of the custom fields and store them into a separate table.

<source lang="php">
public function onContentAfterSave($context, &$article, $isNew)
{
$articleId = $article->id;
if ($articleId && isset($article->rating) && (count($article->rating)))
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$query->clear();
$query->insert('#__user_profiles');
$order = 1;
foreach ($article->rating as $k => $v)
{
$query->values($articleId.', '.$db->quote('rating.'.$k).', '.$db->quote(json_encode($v)).', '.$order++);
}
$db->setQuery($query);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentAfterDelete</code> ===
<code>onContentAfterDelete()</code> is called after the article is deleted from the database <code>#__content</code> table. It will delete the linked custom fields which are stored in a separate table.

<source lang="php">
public function onContentAfterDelete($context, $article)
{
$articleId = $article->id;
if ($articleId)
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete();
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);

if (!$db->query())
{
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentPrepare</code> ===
<code>onContentPrepare()</code> is called when the article is being prepared for display. This is the moment where HTML can be injected into what will be displayed.

<code>$params</code> are the article params, <code>$this->params</code> are the plugin configuration parameters as described in the manifest.

<source lang="php">
public function onContentPrepare($context, &$article, &$params, $page = 0)
{
if (!isset($article->rating) || !count($article->rating))
return;

// add extra css for table
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::base(true).'/plugins/content/rating/rating/rating.css');

// construct a result table on the fly
jimport('joomla.html.grid');
$table = new JGrid();

// Create columns
$table->addColumn('attr')
->addColumn('value');

// populate
$rownr = 0;
foreach ($article->rating as $attr => $value) {
$table->addRow(array('class' => 'row'.($rownr % 2)));
$table->setRowCell('attr', $attr);
$table->setRowCell('value', $value);
$rownr++;
}

// wrap table in a classed <div>
$suffix = $this->params->get('ratingclass_sfx', 'rating');
$html = '<div class="'.$suffix.'">'.(string)$table.'</div>';

$article->text = $html.$article->text;
}
</source>

== Prerequisites ==
This tutorial requires at least Joomla 2.5.x [to be determined] as the framework for previous versions misses a number of plugin hook place holders.

For Joomla 2.5 a patch file and for Joomla 2.5.6 a patch extension is available.

This patch has been submitted as [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 Joomla patch #28871].

== Extension Files ==

The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/trackeritem/28771/75015/patch_28771-2.5.6.patch.gz <code>jpatch_28771-2.5.6.patch.gz</code>] Joomla 2.5.6 unified diff patch
* [http://joomlacode.org/gf/download/trackeritem/28771/75012/patch_28771-2.5.6.zip <code>patch_28771-2.5.6.zip</code>] Patch as Joomla 2.5.6 installable component
* [http://joomlacode.org/gf/download/trackeritem/28771/75013/plg_content_rating-2.5.0.zip <code>plg_content_rating-2.5.0.zip</code>] The plugin as described in this tutorial

The tracker page for the patch. [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 <code>#28771</code>]. Patch [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28770 <code>#28770</code>] is also related.

== Contributors ==
*[[User:znarf|Franz Korntner]]

[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Development]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Adding custom fields to the article component

2012-06-29T21:10:46Z

Znarf: /* Intro */

This tutorial is for Joomla {{JVer|2.5}}

== Intro ==
This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article component (com_content), without the need to change core files. Capabilities that are implemented in this demo package include:

# Adding extra fields to the back-end article manager.
# Adding extra fields to the front-end article editor.
# Storing the values of the custom fields into a database table.
# Converting the field values into a HTML table which is injected into the displayed article.

A capability which is present but not demonstrated, is integrating the values of the custom fields into other components and views, such as article lists or category blogs.

== This example ==
This example adds food ratings to articles. These ratings consist of texture, temperature and taste. When present, they will be displayed as a simple table. This table is positioned before the article content.
[[File:Plg_content_rating-1.png|thumb|frame|none|alt=example of rendered article|An example of how the plugin places the table at the beginning of an article]]

Setting the values of these fields can be done in both the backend and frontend.
[[File:Plg_content_rating-frontend.png|thumb|frame|left|alt=edit article frontend|Accessing the additional fields through the frontend]]
[[File:Plg_content_rating-backend.png|thumb|frame|none|alt=edit article backend|... and the backend]]

== Framework ==
Within Joomla, the article manager is basically a form driven component. Both in the backend as the frontend. When handling a form, the framework performs the following actions.

# Loads the form description. This is a XML structure.
# Loads the data from the user state if present, and if not from the database.
# Injects the data into the form
# Renders/displays the form for the user to work on.

When the user is finished and issues a <code>SAVE</code>, the framework will:

# Captures the submitted data
# Loads the form description.
# Validates the data against the form description.
# If validation fails, stores the data in the user state and starts from the beginning.
# Updates the database accordingly

The framework has placeholders for all these moments. This example plugin will hook into these placeholders, expanding the form and data with additional custom fields.

The hooks are:
*<code>onContentPrepareForm()</code>
*:Called after loading the form description. It will add an extra form group containing the additional fields
*<code>onContentPrepareData()</code>
*:Called after loading the article from the database. It will inject the additional fields and their value into the article.
*<code>onContentAfterSave()</code>
*:Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.
*<code>onContentAfterDelete()</code>
*:Called after an article has been deleted (emptying of trash). It will delete the additional fields.
*<code>onContentPrepare()</code>
*:Called before the article will be rendered/displayed. It will inject the rating values as a table at the beginning of the article, if values have been entered.

== Database ==
The contents of the extra custom fields need to be stored in the database. Ideally would be if they have their own dedicated database table. This however, requires considerable extension overhead. With Joomla 2.5 is is possible to extend the user profile. The extra fields are stored in the table <code>#__user_profiles</code>. That table is constructed and used in such a manner that it can also hold the extra article fields. [I would like to spark the discussion to evolve <code>#__user_profiles</code> into a generic table for expanding core tables.]

This plugin example will use table <code>#__user_profiles</code> to store the extra fields. It will use the tables <code>user_id</code> as <code>article_id</code>

== Extension files ==
The example plugin contains the following files. It has an extra directory <code>rating</code>. The primary reason is that it contains a XML file that is not a manifest. If it were located in the plugin top-level directory, the installer would find it and mistakenly identify it as an orphaned plugin. This would result in the form showing up when 'Discovering' lost extensions.

<pre>
── plugins/content/rating
├── language
│ └── en-GB
│ ├── en-GB.plg_content_rating.ini [language file]
│ └── en-GB.plg_content_rating.sys.ini [language file]
├── rating
│ ├── rating.css [CSS for the rendered rating table]
│ └── rating.xml [Form description]
├── rating.php [Plugin hooks]
└── rating.xml [Manifest]
</pre>

=== Manifest ===
A regular plugin manifest which takes an extra configuration argument, a CSS name that is tagged onto the rendered rating table.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="content" method="upgrade">
<name>plg_content_rating</name>
<author>Joomla! Project</author>
<creationDate>June 2012</creationDate>
<copyright>(C) 2005 - 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>2.5.0</version>
<description>PLG_CONTENT_RATING_XML_DESCRIPTION</description>

<files>
<folder>language</folder>
<folder>rating</folder>
<filename plugin="rating">rating.php</filename>
<filename>index.html</filename>
</files>

<config>
<fields name="params">
<fieldset name="basic">
<field
name="ratingclass_sfx"
type="text"
label="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL"
description="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC"
/>
</fieldset>
</fields>
</config>
</extension>
</source>

=== language files ===

<source>
; Joomla! Project
; Copyright (C) 2005 - 2012 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php

PLG_CONTENT_RATING="Content - Rating"
PLG_CONTENT_RATING_XML_DESCRIPTION="[plg_content_rating] Example plugin on how to add custom fields (texture/temperature/taste) to articles (com_content). Adds ratings to an article, and display them as a table before the article content."
PLG_CONTENT_RATING_SLIDER_LABEL="Showcase Options"
PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL="Texture"
PLG_CONTENT_RATING_FIELD_TEXTURE_DESC="What does the sample feel like"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL="Temperature"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC="What is the temperature of the sample"
PLG_CONTENT_RATING_FIELD_TASTE_LABEL="Taste"
PLG_CONTENT_RATING_FIELD_TASTE_DESC="How does the sample taste"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL="Rating Class"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC="Optional CSS class to add to the rating. This allows CSS styling specific to the page."
</source>

=== CSS ===
The CSS file for the rendered table.

<source lang="css">
div.rating {
display: block;
float: left;
padding-right: 10px;
}
div.rating table tr td {
margin: 1px !important;
padding: 2px !important;
}
div.rating table tr.row0 {
background-color:#efefef;
}
div.rating table tr.row1 {
background-color:#ffffff;
}
</source>

=== Form description ===
The form containing the custom fields.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="rating">
<fieldset name="rating" label="PLG_CONTENT_RATING_SLIDER_LABEL">
<field
name="texture"
type="text"
id="texture"
description="PLG_CONTENT_RATING_FIELD_TEXTURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEXTURE_MESSAGE"
size="30"
/>
<field
name="temperature"
type="text"
id="temperature"
description="PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEMPERATURE_MESSAGE"
size="30"
/>
<field
name="taste"
type="text"
id="taste"
description="PLG_CONTENT_RATING_FIELD_TASTE_DESC"
label="PLG_CONTENT_RATING_FIELD_TASTE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TASTE_MESSAGE"
size="30"
/>
</fieldset>
</fields>
</form>
</source>

== Plugin hooks ==
The main file 'rating.php' contains the hooks which are called by the Joomla framework.

For all calls:
*The <code>$context</code> parameter is a string identifying the calling placeholder.
*The <code>$data</code> parameter is an object containing the form values
*The <code>$article</code> parameter is an object (<code>JTableContent</code>) representing the article.

=== <code>__construct</code> ===
The constructor. It loads the language file.

<source lang="php">
public function __construct(& $subject, $config)
{
parent::__construct($subject, $config);
$this->loadLanguage();
}
</source>

=== <code>onContentPrepareForm</code> ===
<code>onContentPrepareForm</code> extends the article manager form in both the front-end as the back-end. It loads the form fragment as described in <code>rating/rating.xml</code> and merges that into the framework form.

<source lang="php">
public public function onContentPrepareForm($form, $data)
{
if (!($form instanceof JForm))
{
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}

// Add the extra fields to the form.
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form->loadFile('rating', false);
return true;
}
</source>

=== <code>onContentPrepareData</code> ===
<code>onContentPrepareData()</code> is executed after an article is loaded from the <code>#__content</code> table. It will gather and merge the values of the custom fields, which are located in the table <code>#__user_profiles</code>.

The field <code>articleId</code> in <code>$data</code> contains the article record number. That number is used to retrieve the values of the custom fields. If no record number is present, or it is zero, then a new record is being create. When this occurs, <code>$data</code> gets populated with the default values from the form description xml.

It is important that when <code>onContentPrepareData()</code> returns, <code>$data</code> contains the custom fields. This is due to how the framework uses them as place holders. When a user saves a newly created article, and an error situation occurs (like some values are missing) the form data is temporarily stored in the user state. If the place holders are not present, their values will not be preserved. The user will notice this because the custom fields will get erased.

<source lang="php">
public function onContentPrepareData($context, $data)
{
if (is_object($data))
{
$articleId = isset($data->id) ? $data->id : 0;
if ($articleId > 0)
{
// Load the data from the database.
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('profile_key, profile_value');
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$query->order('ordering');
$db->setQuery($query);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum())
{
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the data.
$data->rating = array();

foreach ($results as $v)
{
$k = str_replace('rating.', '', $v[0]);
$data->rating[$k] = json_decode($v[1], true);
if ($data->rating[$k] === null)
{
$data->rating[$k] = $v[1];
}
}
} else {
// load the form
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form = new JForm('com_content.article');
$form->loadFile('rating', false);

// Merge the default values
$data->rating = array();
foreach ($form->getFieldset('rating') as $field) {
$data->rating[] = array($field->fieldname, $field->value);
}
}
}

return true;
}
</source>

=== <code>onContentAfterSave</code> ===
<code>onContentAfterSave()</code> is called after the article is stored into the database <code>#__content</code> table. It will extract the values of the custom fields and store them into a separate table.

<source lang="php">
public function onContentAfterSave($context, &$article, $isNew)
{
$articleId = $article->id;
if ($articleId && isset($article->rating) && (count($article->rating)))
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$query->clear();
$query->insert('#__user_profiles');
$order = 1;
foreach ($article->rating as $k => $v)
{
$query->values($articleId.', '.$db->quote('rating.'.$k).', '.$db->quote(json_encode($v)).', '.$order++);
}
$db->setQuery($query);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentAfterDelete</code> ===
<code>onContentAfterDelete()</code> is called after the article is deleted from the database <code>#__content</code> table. It will delete the linked custom fields which are stored in a separate table.

<source lang="php">
public function onContentAfterDelete($context, $article)
{
$articleId = $article->id;
if ($articleId)
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete();
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);

if (!$db->query())
{
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentPrepare</code> ===
<code>onContentPrepare()</code> is called when the article is being prepared for display. This is the moment where HTML can be injected into what will be displayed.

<code>$params</code> are the article params, <code>$this->params</code> are the plugin configuration parameters as described in the manifest.

<source lang="php">
public function onContentPrepare($context, &$article, &$params, $page = 0)
{
if (!isset($article->rating) || !count($article->rating))
return;

// add extra css for table
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::base(true).'/plugins/content/rating/rating/rating.css');

// construct a result table on the fly
jimport('joomla.html.grid');
$table = new JGrid();

// Create columns
$table->addColumn('attr')
->addColumn('value');

// populate
$rownr = 0;
foreach ($article->rating as $attr => $value) {
$table->addRow(array('class' => 'row'.($rownr % 2)));
$table->setRowCell('attr', $attr);
$table->setRowCell('value', $value);
$rownr++;
}

// wrap table in a classed <div>
$suffix = $this->params->get('ratingclass_sfx', 'rating');
$html = '<div class="'.$suffix.'">'.(string)$table.'</div>';

$article->text = $html.$article->text;
}
</source>

== Prerequisites ==
This tutorial requires at least Joomla 2.5.x [to be determined] as the framework for previous versions misses a number of plugin hook place holders.

For Joomla 2.5 a patch file and for Joomla 2.5.6 a patch extension is available.

This patch has been submitted as [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 Joomla patch #28871].

== Extension Files ==

The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/trackeritem/28771/75015/patch_28771-2.5.6.patch.gz <code>jpatch_28771-2.5.6.patch.gz</code>] Joomla 2.5.6 unified diff patch
* [http://joomlacode.org/gf/download/trackeritem/28771/75012/patch_28771-2.5.6.zip <code>patch_28771-2.5.6.zip</code>] Patch as Joomla 2.5.6 installable component
* [http://joomlacode.org/gf/download/trackeritem/28771/75013/plg_content_rating-2.5.0.zip <code>plg_content_rating-2.5.0.zip</code>] The plugin as described in this tutorial

The tracker page for the patch. [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 <code>#28771</code>]. Patch [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28770 <code>#28770</code>] is also related.

== Contributors ==
*[[User:znarf|Franz Korntner]]

[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Development]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Adding custom fields to the article component

2012-06-29T21:05:29Z

Znarf: /* Prerequisites */

This tutorial is for Joomla {{JVer|2.5}}

== Intro ==
This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article component (com_content), without the need to change core files. Capabilities that are implemented in this demo package include:
# Adding extra fields to the back-end article manager.
# Adding extra fields to the front-end article editor.
# Storing the editor supplied field values into a database table.
# Converting the field values into HTML which is injected into the displayed article.
A capability which is present but not demonstrated, is integrating the values of the custom fields into other components and views, such as article lists or category blogs.

== This example ==
This example adds food ratings to articles. These ratings consist of texture, temperature and taste. When present, they will be displayed as a simple table. This table is positioned before the article content.
[[File:Plg_content_rating-1.png|thumb|frame|none|alt=example of rendered article|An example of how the plugin places the table at the beginning of an article]]

Setting the values of these fields can be done in both the backend and frontend.
[[File:Plg_content_rating-frontend.png|thumb|frame|left|alt=edit article frontend|Accessing the additional fields through the frontend]]
[[File:Plg_content_rating-backend.png|thumb|frame|none|alt=edit article backend|... and the backend]]

== Framework ==
Within Joomla, the article manager is basically a form driven component. Both in the backend as the frontend. When handling a form, the framework performs the following actions.

# Loads the form description. This is a XML structure.
# Loads the data from the user state if present, and if not from the database.
# Injects the data into the form
# Renders/displays the form for the user to work on.

When the user is finished and issues a <code>SAVE</code>, the framework will:

# Captures the submitted data
# Loads the form description.
# Validates the data against the form description.
# If validation fails, stores the data in the user state and starts from the beginning.
# Updates the database accordingly

The framework has placeholders for all these moments. This example plugin will hook into these placeholders, expanding the form and data with additional custom fields.

The hooks are:
*<code>onContentPrepareForm()</code>
*:Called after loading the form description. It will add an extra form group containing the additional fields
*<code>onContentPrepareData()</code>
*:Called after loading the article from the database. It will inject the additional fields and their value into the article.
*<code>onContentAfterSave()</code>
*:Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.
*<code>onContentAfterDelete()</code>
*:Called after an article has been deleted (emptying of trash). It will delete the additional fields.
*<code>onContentPrepare()</code>
*:Called before the article will be rendered/displayed. It will inject the rating values as a table at the beginning of the article, if values have been entered.

== Database ==
The contents of the extra custom fields need to be stored in the database. Ideally would be if they have their own dedicated database table. This however, requires considerable extension overhead. With Joomla 2.5 is is possible to extend the user profile. The extra fields are stored in the table <code>#__user_profiles</code>. That table is constructed and used in such a manner that it can also hold the extra article fields. [I would like to spark the discussion to evolve <code>#__user_profiles</code> into a generic table for expanding core tables.]

This plugin example will use table <code>#__user_profiles</code> to store the extra fields. It will use the tables <code>user_id</code> as <code>article_id</code>

== Extension files ==
The example plugin contains the following files. It has an extra directory <code>rating</code>. The primary reason is that it contains a XML file that is not a manifest. If it were located in the plugin top-level directory, the installer would find it and mistakenly identify it as an orphaned plugin. This would result in the form showing up when 'Discovering' lost extensions.

<pre>
── plugins/content/rating
├── language
│ └── en-GB
│ ├── en-GB.plg_content_rating.ini [language file]
│ └── en-GB.plg_content_rating.sys.ini [language file]
├── rating
│ ├── rating.css [CSS for the rendered rating table]
│ └── rating.xml [Form description]
├── rating.php [Plugin hooks]
└── rating.xml [Manifest]
</pre>

=== Manifest ===
A regular plugin manifest which takes an extra configuration argument, a CSS name that is tagged onto the rendered rating table.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="content" method="upgrade">
<name>plg_content_rating</name>
<author>Joomla! Project</author>
<creationDate>June 2012</creationDate>
<copyright>(C) 2005 - 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>2.5.0</version>
<description>PLG_CONTENT_RATING_XML_DESCRIPTION</description>

<files>
<folder>language</folder>
<folder>rating</folder>
<filename plugin="rating">rating.php</filename>
<filename>index.html</filename>
</files>

<config>
<fields name="params">
<fieldset name="basic">
<field
name="ratingclass_sfx"
type="text"
label="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL"
description="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC"
/>
</fieldset>
</fields>
</config>
</extension>
</source>

=== language files ===

<source>
; Joomla! Project
; Copyright (C) 2005 - 2012 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php

PLG_CONTENT_RATING="Content - Rating"
PLG_CONTENT_RATING_XML_DESCRIPTION="[plg_content_rating] Example plugin on how to add custom fields (texture/temperature/taste) to articles (com_content). Adds ratings to an article, and display them as a table before the article content."
PLG_CONTENT_RATING_SLIDER_LABEL="Showcase Options"
PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL="Texture"
PLG_CONTENT_RATING_FIELD_TEXTURE_DESC="What does the sample feel like"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL="Temperature"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC="What is the temperature of the sample"
PLG_CONTENT_RATING_FIELD_TASTE_LABEL="Taste"
PLG_CONTENT_RATING_FIELD_TASTE_DESC="How does the sample taste"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL="Rating Class"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC="Optional CSS class to add to the rating. This allows CSS styling specific to the page."
</source>

=== CSS ===
The CSS file for the rendered table.

<source lang="css">
div.rating {
display: block;
float: left;
padding-right: 10px;
}
div.rating table tr td {
margin: 1px !important;
padding: 2px !important;
}
div.rating table tr.row0 {
background-color:#efefef;
}
div.rating table tr.row1 {
background-color:#ffffff;
}
</source>

=== Form description ===
The form containing the custom fields.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="rating">
<fieldset name="rating" label="PLG_CONTENT_RATING_SLIDER_LABEL">
<field
name="texture"
type="text"
id="texture"
description="PLG_CONTENT_RATING_FIELD_TEXTURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEXTURE_MESSAGE"
size="30"
/>
<field
name="temperature"
type="text"
id="temperature"
description="PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEMPERATURE_MESSAGE"
size="30"
/>
<field
name="taste"
type="text"
id="taste"
description="PLG_CONTENT_RATING_FIELD_TASTE_DESC"
label="PLG_CONTENT_RATING_FIELD_TASTE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TASTE_MESSAGE"
size="30"
/>
</fieldset>
</fields>
</form>
</source>

== Plugin hooks ==
The main file 'rating.php' contains the hooks which are called by the Joomla framework.

For all calls:
*The <code>$context</code> parameter is a string identifying the calling placeholder.
*The <code>$data</code> parameter is an object containing the form values
*The <code>$article</code> parameter is an object (<code>JTableContent</code>) representing the article.

=== <code>__construct</code> ===
The constructor. It loads the language file.

<source lang="php">
public function __construct(& $subject, $config)
{
parent::__construct($subject, $config);
$this->loadLanguage();
}
</source>

=== <code>onContentPrepareForm</code> ===
<code>onContentPrepareForm</code> extends the article manager form in both the front-end as the back-end. It loads the form fragment as described in <code>rating/rating.xml</code> and merges that into the framework form.

<source lang="php">
public public function onContentPrepareForm($form, $data)
{
if (!($form instanceof JForm))
{
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}

// Add the extra fields to the form.
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form->loadFile('rating', false);
return true;
}
</source>

=== <code>onContentPrepareData</code> ===
<code>onContentPrepareData()</code> is executed after an article is loaded from the <code>#__content</code> table. It will gather and merge the values of the custom fields, which are located in the table <code>#__user_profiles</code>.

The field <code>articleId</code> in <code>$data</code> contains the article record number. That number is used to retrieve the values of the custom fields. If no record number is present, or it is zero, then a new record is being create. When this occurs, <code>$data</code> gets populated with the default values from the form description xml.

It is important that when <code>onContentPrepareData()</code> returns, <code>$data</code> contains the custom fields. This is due to how the framework uses them as place holders. When a user saves a newly created article, and an error situation occurs (like some values are missing) the form data is temporarily stored in the user state. If the place holders are not present, their values will not be preserved. The user will notice this because the custom fields will get erased.

<source lang="php">
public function onContentPrepareData($context, $data)
{
if (is_object($data))
{
$articleId = isset($data->id) ? $data->id : 0;
if ($articleId > 0)
{
// Load the data from the database.
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('profile_key, profile_value');
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$query->order('ordering');
$db->setQuery($query);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum())
{
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the data.
$data->rating = array();

foreach ($results as $v)
{
$k = str_replace('rating.', '', $v[0]);
$data->rating[$k] = json_decode($v[1], true);
if ($data->rating[$k] === null)
{
$data->rating[$k] = $v[1];
}
}
} else {
// load the form
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form = new JForm('com_content.article');
$form->loadFile('rating', false);

// Merge the default values
$data->rating = array();
foreach ($form->getFieldset('rating') as $field) {
$data->rating[] = array($field->fieldname, $field->value);
}
}
}

return true;
}
</source>

=== <code>onContentAfterSave</code> ===
<code>onContentAfterSave()</code> is called after the article is stored into the database <code>#__content</code> table. It will extract the values of the custom fields and store them into a separate table.

<source lang="php">
public function onContentAfterSave($context, &$article, $isNew)
{
$articleId = $article->id;
if ($articleId && isset($article->rating) && (count($article->rating)))
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$query->clear();
$query->insert('#__user_profiles');
$order = 1;
foreach ($article->rating as $k => $v)
{
$query->values($articleId.', '.$db->quote('rating.'.$k).', '.$db->quote(json_encode($v)).', '.$order++);
}
$db->setQuery($query);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentAfterDelete</code> ===
<code>onContentAfterDelete()</code> is called after the article is deleted from the database <code>#__content</code> table. It will delete the linked custom fields which are stored in a separate table.

<source lang="php">
public function onContentAfterDelete($context, $article)
{
$articleId = $article->id;
if ($articleId)
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete();
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);

if (!$db->query())
{
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentPrepare</code> ===
<code>onContentPrepare()</code> is called when the article is being prepared for display. This is the moment where HTML can be injected into what will be displayed.

<code>$params</code> are the article params, <code>$this->params</code> are the plugin configuration parameters as described in the manifest.

<source lang="php">
public function onContentPrepare($context, &$article, &$params, $page = 0)
{
if (!isset($article->rating) || !count($article->rating))
return;

// add extra css for table
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::base(true).'/plugins/content/rating/rating/rating.css');

// construct a result table on the fly
jimport('joomla.html.grid');
$table = new JGrid();

// Create columns
$table->addColumn('attr')
->addColumn('value');

// populate
$rownr = 0;
foreach ($article->rating as $attr => $value) {
$table->addRow(array('class' => 'row'.($rownr % 2)));
$table->setRowCell('attr', $attr);
$table->setRowCell('value', $value);
$rownr++;
}

// wrap table in a classed <div>
$suffix = $this->params->get('ratingclass_sfx', 'rating');
$html = '<div class="'.$suffix.'">'.(string)$table.'</div>';

$article->text = $html.$article->text;
}
</source>

== Prerequisites ==
This tutorial requires at least Joomla 2.5.x [to be determined] as the framework for previous versions misses a number of plugin hook place holders.

For Joomla 2.5 a patch file and for Joomla 2.5.6 a patch extension is available.

This patch has been submitted as [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 Joomla patch #28871].

== Extension Files ==

The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/trackeritem/28771/75015/patch_28771-2.5.6.patch.gz <code>jpatch_28771-2.5.6.patch.gz</code>] Joomla 2.5.6 unified diff patch
* [http://joomlacode.org/gf/download/trackeritem/28771/75012/patch_28771-2.5.6.zip <code>patch_28771-2.5.6.zip</code>] Patch as Joomla 2.5.6 installable component
* [http://joomlacode.org/gf/download/trackeritem/28771/75013/plg_content_rating-2.5.0.zip <code>plg_content_rating-2.5.0.zip</code>] The plugin as described in this tutorial

The tracker page for the patch. [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 <code>#28771</code>]. Patch [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28770 <code>#28770</code>] is also related.

== Contributors ==
*[[User:znarf|Franz Korntner]]

[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Development]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Adding custom fields to the article component

2012-06-29T21:03:17Z

Znarf: Created page with "This tutorial is for Joomla {{JVer|2.5}} == Intro == This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article co..."

This tutorial is for Joomla {{JVer|2.5}}

== Intro ==
This plugin demonstrates how a component developer can use the features in Joomla 2.5 to add custom fields to the article component (com_content), without the need to change core files. Capabilities that are implemented in this demo package include:
# Adding extra fields to the back-end article manager.
# Adding extra fields to the front-end article editor.
# Storing the editor supplied field values into a database table.
# Converting the field values into HTML which is injected into the displayed article.
A capability which is present but not demonstrated, is integrating the values of the custom fields into other components and views, such as article lists or category blogs.

== This example ==
This example adds food ratings to articles. These ratings consist of texture, temperature and taste. When present, they will be displayed as a simple table. This table is positioned before the article content.
[[File:Plg_content_rating-1.png|thumb|frame|none|alt=example of rendered article|An example of how the plugin places the table at the beginning of an article]]

Setting the values of these fields can be done in both the backend and frontend.
[[File:Plg_content_rating-frontend.png|thumb|frame|left|alt=edit article frontend|Accessing the additional fields through the frontend]]
[[File:Plg_content_rating-backend.png|thumb|frame|none|alt=edit article backend|... and the backend]]

== Framework ==
Within Joomla, the article manager is basically a form driven component. Both in the backend as the frontend. When handling a form, the framework performs the following actions.

# Loads the form description. This is a XML structure.
# Loads the data from the user state if present, and if not from the database.
# Injects the data into the form
# Renders/displays the form for the user to work on.

When the user is finished and issues a <code>SAVE</code>, the framework will:

# Captures the submitted data
# Loads the form description.
# Validates the data against the form description.
# If validation fails, stores the data in the user state and starts from the beginning.
# Updates the database accordingly

The framework has placeholders for all these moments. This example plugin will hook into these placeholders, expanding the form and data with additional custom fields.

The hooks are:
*<code>onContentPrepareForm()</code>
*:Called after loading the form description. It will add an extra form group containing the additional fields
*<code>onContentPrepareData()</code>
*:Called after loading the article from the database. It will inject the additional fields and their value into the article.
*<code>onContentAfterSave()</code>
*:Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.
*<code>onContentAfterDelete()</code>
*:Called after an article has been deleted (emptying of trash). It will delete the additional fields.
*<code>onContentPrepare()</code>
*:Called before the article will be rendered/displayed. It will inject the rating values as a table at the beginning of the article, if values have been entered.

== Database ==
The contents of the extra custom fields need to be stored in the database. Ideally would be if they have their own dedicated database table. This however, requires considerable extension overhead. With Joomla 2.5 is is possible to extend the user profile. The extra fields are stored in the table <code>#__user_profiles</code>. That table is constructed and used in such a manner that it can also hold the extra article fields. [I would like to spark the discussion to evolve <code>#__user_profiles</code> into a generic table for expanding core tables.]

This plugin example will use table <code>#__user_profiles</code> to store the extra fields. It will use the tables <code>user_id</code> as <code>article_id</code>

== Extension files ==
The example plugin contains the following files. It has an extra directory <code>rating</code>. The primary reason is that it contains a XML file that is not a manifest. If it were located in the plugin top-level directory, the installer would find it and mistakenly identify it as an orphaned plugin. This would result in the form showing up when 'Discovering' lost extensions.

<pre>
── plugins/content/rating
├── language
│ └── en-GB
│ ├── en-GB.plg_content_rating.ini [language file]
│ └── en-GB.plg_content_rating.sys.ini [language file]
├── rating
│ ├── rating.css [CSS for the rendered rating table]
│ └── rating.xml [Form description]
├── rating.php [Plugin hooks]
└── rating.xml [Manifest]
</pre>

=== Manifest ===
A regular plugin manifest which takes an extra configuration argument, a CSS name that is tagged onto the rendered rating table.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="content" method="upgrade">
<name>plg_content_rating</name>
<author>Joomla! Project</author>
<creationDate>June 2012</creationDate>
<copyright>(C) 2005 - 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>2.5.0</version>
<description>PLG_CONTENT_RATING_XML_DESCRIPTION</description>

<files>
<folder>language</folder>
<folder>rating</folder>
<filename plugin="rating">rating.php</filename>
<filename>index.html</filename>
</files>

<config>
<fields name="params">
<fieldset name="basic">
<field
name="ratingclass_sfx"
type="text"
label="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL"
description="PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC"
/>
</fieldset>
</fields>
</config>
</extension>
</source>

=== language files ===

<source>
; Joomla! Project
; Copyright (C) 2005 - 2012 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php

PLG_CONTENT_RATING="Content - Rating"
PLG_CONTENT_RATING_XML_DESCRIPTION="[plg_content_rating] Example plugin on how to add custom fields (texture/temperature/taste) to articles (com_content). Adds ratings to an article, and display them as a table before the article content."
PLG_CONTENT_RATING_SLIDER_LABEL="Showcase Options"
PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL="Texture"
PLG_CONTENT_RATING_FIELD_TEXTURE_DESC="What does the sample feel like"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL="Temperature"
PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC="What is the temperature of the sample"
PLG_CONTENT_RATING_FIELD_TASTE_LABEL="Taste"
PLG_CONTENT_RATING_FIELD_TASTE_DESC="How does the sample taste"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_LABEL="Rating Class"
PLG_CONTENT_RATING_ITEM_FIELD_RATING_CLASS_DESC="Optional CSS class to add to the rating. This allows CSS styling specific to the page."
</source>

=== CSS ===
The CSS file for the rendered table.

<source lang="css">
div.rating {
display: block;
float: left;
padding-right: 10px;
}
div.rating table tr td {
margin: 1px !important;
padding: 2px !important;
}
div.rating table tr.row0 {
background-color:#efefef;
}
div.rating table tr.row1 {
background-color:#ffffff;
}
</source>

=== Form description ===
The form containing the custom fields.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="rating">
<fieldset name="rating" label="PLG_CONTENT_RATING_SLIDER_LABEL">
<field
name="texture"
type="text"
id="texture"
description="PLG_CONTENT_RATING_FIELD_TEXTURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEXTURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEXTURE_MESSAGE"
size="30"
/>
<field
name="temperature"
type="text"
id="temperature"
description="PLG_CONTENT_RATING_FIELD_TEMPERATURE_DESC"
label="PLG_CONTENT_RATING_FIELD_TEMPERATURE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TEMPERATURE_MESSAGE"
size="30"
/>
<field
name="taste"
type="text"
id="taste"
description="PLG_CONTENT_RATING_FIELD_TASTE_DESC"
label="PLG_CONTENT_RATING_FIELD_TASTE_LABEL"
message="PLG_CONTENT_RATING_FIELD_TASTE_MESSAGE"
size="30"
/>
</fieldset>
</fields>
</form>
</source>

== Plugin hooks ==
The main file 'rating.php' contains the hooks which are called by the Joomla framework.

For all calls:
*The <code>$context</code> parameter is a string identifying the calling placeholder.
*The <code>$data</code> parameter is an object containing the form values
*The <code>$article</code> parameter is an object (<code>JTableContent</code>) representing the article.

=== <code>__construct</code> ===
The constructor. It loads the language file.

<source lang="php">
public function __construct(& $subject, $config)
{
parent::__construct($subject, $config);
$this->loadLanguage();
}
</source>

=== <code>onContentPrepareForm</code> ===
<code>onContentPrepareForm</code> extends the article manager form in both the front-end as the back-end. It loads the form fragment as described in <code>rating/rating.xml</code> and merges that into the framework form.

<source lang="php">
public public function onContentPrepareForm($form, $data)
{
if (!($form instanceof JForm))
{
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}

// Add the extra fields to the form.
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form->loadFile('rating', false);
return true;
}
</source>

=== <code>onContentPrepareData</code> ===
<code>onContentPrepareData()</code> is executed after an article is loaded from the <code>#__content</code> table. It will gather and merge the values of the custom fields, which are located in the table <code>#__user_profiles</code>.

The field <code>articleId</code> in <code>$data</code> contains the article record number. That number is used to retrieve the values of the custom fields. If no record number is present, or it is zero, then a new record is being create. When this occurs, <code>$data</code> gets populated with the default values from the form description xml.

It is important that when <code>onContentPrepareData()</code> returns, <code>$data</code> contains the custom fields. This is due to how the framework uses them as place holders. When a user saves a newly created article, and an error situation occurs (like some values are missing) the form data is temporarily stored in the user state. If the place holders are not present, their values will not be preserved. The user will notice this because the custom fields will get erased.

<source lang="php">
public function onContentPrepareData($context, $data)
{
if (is_object($data))
{
$articleId = isset($data->id) ? $data->id : 0;
if ($articleId > 0)
{
// Load the data from the database.
$db = JFactory::getDbo();
$query = $db->getQuery(true);
$query->select('profile_key, profile_value');
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$query->order('ordering');
$db->setQuery($query);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum())
{
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the data.
$data->rating = array();

foreach ($results as $v)
{
$k = str_replace('rating.', '', $v[0]);
$data->rating[$k] = json_decode($v[1], true);
if ($data->rating[$k] === null)
{
$data->rating[$k] = $v[1];
}
}
} else {
// load the form
JForm::addFormPath(dirname(__FILE__) . '/rating');
$form = new JForm('com_content.article');
$form->loadFile('rating', false);

// Merge the default values
$data->rating = array();
foreach ($form->getFieldset('rating') as $field) {
$data->rating[] = array($field->fieldname, $field->value);
}
}
}

return true;
}
</source>

=== <code>onContentAfterSave</code> ===
<code>onContentAfterSave()</code> is called after the article is stored into the database <code>#__content</code> table. It will extract the values of the custom fields and store them into a separate table.

<source lang="php">
public function onContentAfterSave($context, &$article, $isNew)
{
$articleId = $article->id;
if ($articleId && isset($article->rating) && (count($article->rating)))
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$query->clear();
$query->insert('#__user_profiles');
$order = 1;
foreach ($article->rating as $k => $v)
{
$query->values($articleId.', '.$db->quote('rating.'.$k).', '.$db->quote(json_encode($v)).', '.$order++);
}
$db->setQuery($query);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentAfterDelete</code> ===
<code>onContentAfterDelete()</code> is called after the article is deleted from the database <code>#__content</code> table. It will delete the linked custom fields which are stored in a separate table.

<source lang="php">
public function onContentAfterDelete($context, $article)
{
$articleId = $article->id;
if ($articleId)
{
try
{
$db = JFactory::getDbo();

$query = $db->getQuery(true);
$query->delete();
$query->from('#__user_profiles');
$query->where('user_id = ' . $db->Quote($articleId));
$query->where('profile_key LIKE ' . $db->Quote('rating.%'));
$db->setQuery($query);

if (!$db->query())
{
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}
</source>

=== <code>onContentPrepare</code> ===
<code>onContentPrepare()</code> is called when the article is being prepared for display. This is the moment where HTML can be injected into what will be displayed.

<code>$params</code> are the article params, <code>$this->params</code> are the plugin configuration parameters as described in the manifest.

<source lang="php">
public function onContentPrepare($context, &$article, &$params, $page = 0)
{
if (!isset($article->rating) || !count($article->rating))
return;

// add extra css for table
$doc = JFactory::getDocument();
$doc->addStyleSheet(JURI::base(true).'/plugins/content/rating/rating/rating.css');

// construct a result table on the fly
jimport('joomla.html.grid');
$table = new JGrid();

// Create columns
$table->addColumn('attr')
->addColumn('value');

// populate
$rownr = 0;
foreach ($article->rating as $attr => $value) {
$table->addRow(array('class' => 'row'.($rownr % 2)));
$table->setRowCell('attr', $attr);
$table->setRowCell('value', $value);
$rownr++;
}

// wrap table in a classed <div>
$suffix = $this->params->get('ratingclass_sfx', 'rating');
$html = '<div class="'.$suffix.'">'.(string)$table.'</div>';

$article->text = $html.$article->text;
}
</source>

== Prerequisites ==
This tutorial requires at least Joomla 2.5.x [to be determined] as the framework for previous versions misses a number of plugin hook place holders.

For Joomla 2.5 a patch file and for Joomla 2.5.6 a patch extension is available.

This patch has been submitted as [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=xxxxx Joomla patch #xxxxx].

== Extension Files ==

The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/trackeritem/28771/75015/patch_28771-2.5.6.patch.gz <code>jpatch_28771-2.5.6.patch.gz</code>] Joomla 2.5.6 unified diff patch
* [http://joomlacode.org/gf/download/trackeritem/28771/75012/patch_28771-2.5.6.zip <code>patch_28771-2.5.6.zip</code>] Patch as Joomla 2.5.6 installable component
* [http://joomlacode.org/gf/download/trackeritem/28771/75013/plg_content_rating-2.5.0.zip <code>plg_content_rating-2.5.0.zip</code>] The plugin as described in this tutorial

The tracker page for the patch. [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28771 <code>#28771</code>]. Patch [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=28770 <code>#28770</code>] is also related.

== Contributors ==
*[[User:znarf|Franz Korntner]]

[[Category:Tutorials]]
[[Category:Component Development]]
[[Category:Development]]
[[category:Joomla! 2.5]]
[[category:Manual]]

File:Plg content rating-frontend.png

2012-06-29T12:27:49Z

Znarf: Plugin plg_content_rating adds customs fields to an article. This image shows how these fields are accessable through the frontend.

== Summary ==
Plugin plg_content_rating adds customs fields to an article. This image shows how these fields are accessable through the frontend.
== Licensing ==
{{JEDL}}

File:Plg content rating-backend.png

2012-06-29T12:27:12Z

Znarf: Plugin plg_content_rating adds customs fields to an article. This image shows how these fields are accessable through the backend.

== Summary ==
Plugin plg_content_rating adds customs fields to an article. This image shows how these fields are accessable through the backend.
== Licensing ==
{{JEDL}}

File:Plg content rating-1.png

2012-06-29T12:03:43Z

Znarf: Plugin plg_content_rating adds customs fields to an article. This image shows how these fields get rendered.

== Summary ==
Plugin plg_content_rating adds customs fields to an article. This image shows how these fields get rendered.
== Licensing ==
{{JEDL}}

Deploying an Update Server

2012-02-12T02:45:13Z

Znarf: /* Extension */ it took hours before I discovered that this is required for the auto update to work.

{{RightTOC}}

This tutorial is for all Joomla! versions newer than {{JVer|1.6}}

= Introduction =
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla! 1.6. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the [[Help16:Extensions Extension Manager Update|Extension Manager's Update]] view with only a few clicks.

= Defining an update server =
In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 1.6 and newer compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly. The update server is defined as follows for each type:

<code>
<updateservers>
<server type="collection">http://example.com/list.xml</server>
<server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>
</code>

Multiple servers can be defined within the <updateservers> tag.

= Server types =
== Collection ==
The collection server type allows developers to define an extension's manifest to pull updates from a collection. This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type). The below example is the collection definition used by the updater when processing core Joomla! updates:

<code>
<extensionset name="Joomla Core" description="Joomla! Core">
<extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
</extensionset>
</code>

All definitions must be defined between <extensionset> tags in your collection manifest. The <extensionset> tag has two optional parameters; name and description. For each extension that this collection references, a separate <extension> tag is required. The <extension> tag has the following parameters, all of which are required for updates to properly process:

* '''name''' - The name of the extension
* '''element''' - The untranslated extension name i.e. mod_custom
* '''type''' - The extension type (component, module, plugin, etc.)
* '''version''' - The latest version of the extension
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions

== Extension ==
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest. All collection manifests eventually point to this XML file. All updates in this file must be defined after an <updates> tag at the beginning of the file. The below example is the update definition for the Joomla! 1.7.0 release:

<code>
<update>
<name>Joomla! 1.7</name>
<description>Joomla! 1.7 CMS</description>
<element>joomla</element>
<type>file</type>
<version>1.7.0</version>
<infourl title="Joomla!">http://www.joomla.org/</infourl>
<downloads>
<downloadurl type="full" format="zip">http://joomlacode.org/gf/download/frsrelease/15279/66552/Joomla_1.6.5_to_1.7.0_Package.zip</downloadurl>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Sam Moffatt</maintainer>
<maintainerurl>http://sammoffatt.com.au</maintainerurl>
<section>Testing</section>
<targetplatform name="joomla" version="1.6"/>
</update>
</code>

The following section describes the elements of a single update entity.

* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting. Use single quotes with your HTML entities.
* '''element''' - The installed name of the extension (required)
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
* '''client''' - The client name of the extension ("site" or "administrator") (usually optional, required for J! 1.7.3 due to a regression; but highly encouraged regardless). Plugins are automatically installed with a client of "site", but you will need to specify the client in an update or it will use "administrator". Note that the tag is "client" not "client_id".
* '''version''' - The version of the release (required)
* '''infourl''' - A URL to point users to containing information about the update (optional) (In CMS 2.5, if set, this URL will be displayed in the update view)
* '''downloads''' - The section which lists all download locations
** '''downloadurl''' - The URL to download the extension from; the <downloadurl> tag has two required parameters:
*** '''type''' - The type of package (full or upgrade)
*** '''format''' - The format of the package (zip, tar, etc.)
* '''tags''' - Optional (unknown use)
* '''maintainer''' - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)
* '''maintainerurl''' - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)
* '''section''' - Optional (unknown use)
* '''targetplatform''' - A tag to define platform requirements, requires the following elements
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
** '''version''' - The version of Joomla! the extension supports
*** '''Note:''' If your extension is Joomla! 1.6, 1.7, and/or 2.5 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version

A separate <update> definition will be required for each version of your extension you release.

The values of '''element''', '''type''', '''client_id''' and '''folder''' should match those in the table #__extensions.

= Supporting Tools =
Maintaining your update server files can be difficult depending on the manner in which you set up your files. An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com

= Contributors =
*[[User:mbabker|Michael Babker]]

Deploying an Update Server

2012-02-12T02:31:20Z

Znarf: /* Extension */ client is not an integer (as client_id) but textual.

{{RightTOC}}

This tutorial is for all Joomla! versions newer than {{JVer|1.6}}

= Introduction =
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla! 1.6. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the [[Help16:Extensions Extension Manager Update|Extension Manager's Update]] view with only a few clicks.

= Defining an update server =
In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 1.6 and newer compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly. The update server is defined as follows for each type:

<code>
<updateservers>
<server type="collection">http://example.com/list.xml</server>
<server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>
</code>

Multiple servers can be defined within the <updateservers> tag.

= Server types =
== Collection ==
The collection server type allows developers to define an extension's manifest to pull updates from a collection. This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type). The below example is the collection definition used by the updater when processing core Joomla! updates:

<code>
<extensionset name="Joomla Core" description="Joomla! Core">
<extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
</extensionset>
</code>

All definitions must be defined between <extensionset> tags in your collection manifest. The <extensionset> tag has two optional parameters; name and description. For each extension that this collection references, a separate <extension> tag is required. The <extension> tag has the following parameters, all of which are required for updates to properly process:

* '''name''' - The name of the extension
* '''element''' - The untranslated extension name i.e. mod_custom
* '''type''' - The extension type (component, module, plugin, etc.)
* '''version''' - The latest version of the extension
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions

== Extension ==
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest. All collection manifests eventually point to this XML file. All updates in this file must be defined after an <updates> tag at the beginning of the file. The below example is the update definition for the Joomla! 1.7.0 release:

<code>
<update>
<name>Joomla! 1.7</name>
<description>Joomla! 1.7 CMS</description>
<element>joomla</element>
<type>file</type>
<version>1.7.0</version>
<infourl title="Joomla!">http://www.joomla.org/</infourl>
<downloads>
<downloadurl type="full" format="zip">http://joomlacode.org/gf/download/frsrelease/15279/66552/Joomla_1.6.5_to_1.7.0_Package.zip</downloadurl>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Sam Moffatt</maintainer>
<maintainerurl>http://sammoffatt.com.au</maintainerurl>
<section>Testing</section>
<targetplatform name="joomla" version="1.6"/>
</update>
</code>

The following section describes the elements of a single update entity.

* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting. Use single quotes with your HTML entities.
* '''element''' - The installed name of the extension (required)
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
* '''client''' - The client name of the extension ("site" or "administrator") (usually optional, required for J! 1.7.3 due to a regression; but highly encouraged regardless). Plugins are automatically installed with a client of "site", but you will need to specify the client in an update or it will use "administrator". Note that the tag is "client" not "client_id".
* '''version''' - The version of the release (required)
* '''infourl''' - A URL to point users to containing information about the update (optional) (In CMS 2.5, if set, this URL will be displayed in the update view)
* '''downloads''' - The section which lists all download locations
** '''downloadurl''' - The URL to download the extension from; the <downloadurl> tag has two required parameters:
*** '''type''' - The type of package (full or upgrade)
*** '''format''' - The format of the package (zip, tar, etc.)
* '''tags''' - Optional (unknown use)
* '''maintainer''' - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)
* '''maintainerurl''' - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)
* '''section''' - Optional (unknown use)
* '''targetplatform''' - A tag to define platform requirements, requires the following elements
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
** '''version''' - The version of Joomla! the extension supports
*** '''Note:''' If your extension is Joomla! 1.6, 1.7, and/or 2.5 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version

A separate <update> definition will be required for each version of your extension you release.

= Supporting Tools =
Maintaining your update server files can be difficult depending on the manner in which you set up your files. An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com

= Contributors =
*[[User:mbabker|Michael Babker]]