{{version/tutor|2.5}}{{page|needs technical review|Please check and see if this article is complete. If so, please remove the from the beginning of the article. See [[Talk:Adding_custom_fields_to_the_article_component#Doesn.27t_work_with_newer_joomla_2.5_versions_.282.5_and_above.29|Discussion page]] for more information.}}

== Intro ==

== 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:

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:

Revision as of 20:55, 4 February 2014

This tutorial is for Joomla! CMS Version(s)

This Article Needs Your Help

This article is tagged because itNEEDS TECHNICAL REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.More pages that need help similar to this one are here.NOTE-If you feel the need is satistified, please remove this notice.Reason: Please check and see if this article is complete. If so, please remove the from the beginning of the article. See Discussion page for more information.

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.

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.

Accessing the additional fields through the frontend

... 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 SAVE, 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:

onContentPrepareForm()

Called after loading the form description. It will add an extra form group containing the additional fields

onContentPrepareData()

Called after loading the article from the database. It will inject the additional fields and their value into the article.

onContentAfterSave()

Called after an article has been successfully stored in database. It will store the additional fields in their designated database table.

onContentAfterDelete()

Called after an article has been deleted (emptying of trash). It will delete the additional fields.

onContentPrepare()

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 #__user_profiles. 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 #__user_profiles into a generic table for expanding core tables.]

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

Extension files

The example plugin contains the following files. It has an extra directory rating. 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.

Manifest

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

<?xmlversion="1.0"encoding="utf-8"?><extensionversion="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><filenameplugin="rating">rating.php</filename><filename>index.html</filename></files><config><fieldsname="params"><fieldsetname="basic"><fieldname="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>

language files

; 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."

onContentPrepareData

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

The field articleId in $data 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, $data gets populated with the default values from the form description xml.

It is important that when onContentPrepareData() returns, $data 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.