Adding custom fields to core components using a plugin/fr

Avez-vous jamais souhaité ajouter un champ pour un numéro de téléphone supplémentaire dans com_contact ou eu besoin d'un champ supplémentaire pour les articles dans com_content ? Joomla! propose une méthode simple pour intégrer de nouveaux champs aux composants du noyau. Tout ce qu'il faut pour atteindre cet objectif, c'est un simple plugin de contenu et un override de votre template.

Cet article montre comment ajouter un champ supplémentaire à un composant natif en utilisant l'exemple de l'ajout aux contacts d'une adresse e-mail supplémentaire dans com_contact.

Ajout d'un champ personnalisé

Il est recommandé de lire au préalable Création d'un plugin pour Joomla! pour plus d'informations sur la façon de créer et installer un plugin, ce qui n'est pas abordé ici.

Pour ajouter un champ à un composant du système, vous devez créer un plugin de contenu qui reprend l'événement onContentPrepareForm et insère ses propres champs au JForm donné. Le code suivant est pour Joomla! 3.1 et versions ultérieures. Pour Joomla! 2.5, les fichiers de langue doivent être chargés dans le constructeur (voir J2.5:création d'un plugin pour Joomla).

<?php
// no direct access
defined ( '_JEXEC' ) or die ( 'Restricted access' );
class plgContentExample extends JPlugin {
	/**
	 * Load the language file on instantiation.
	 * Note this is only available in Joomla 3.1 and higher.
	 * If you want to support 3.0 series you must override the constructor
	 *
	 * @var boolean
	 * @since 3.1
	 */
	protected $autoloadLanguage = true;
	function onContentPrepareForm($form, $data) {
		$app = JFactory::getApplication();
		$option = $app->input->get('option');
		switch($option) {
			case 'com_contact':
				if ($app->isAdmin()) {
					JForm::addFormPath(__DIR__ . '/forms');
					$form->loadFile('contact', false);
				}
				return true;
		}
		return true;
	}
}
?>

The additional fields are loaded from the file forms/contact.xml in the plugin directory. It's important that these fields are in a fields element with the name property set to "params". If you don't set this property name, the fields will appear in the admin site but the values will not be saved.

In this case we are adding a field for a label to describe the email field in the public website and a second field for the value of the email address.

<?xml version="1.0" encoding="UTF-8"?>
<form>
	<fields name="params" >
		<fieldset name="params" >
			<field
				name="contact_emaillabel2"
				type="text"
				label="PLG_CONTENT_EXAMPLE_CONTACT_EMAILLABEL2"
				/>
			<field
				name="contact_email2"
				type="text"
				label="PLG_CONTENT_EXAMPLE_CONTACT_EMAIL2"
				filter="email"
			/>
		</fieldset>
	</fields>
</form>

Finally we need a language file so that the parameters are presented nicely in the admin site and are translatable into different languages. This file needs to be called something like en-GB.plg_content_example.ini.

COM_CONTACT_PARAMS_FIELDSET_LABEL="Additional Information"
PLG_CONTENT_EXAMPLE_CONTACT_EMAIL2="Additional email address"
PLG_CONTENT_EXAMPLE_CONTACT_EMAILLABEL2="Additional email label"

That's it for adding the field to com_contact. If you install this plugin, you'll have an additional tab in the contact editing form called "Additional Information" with the new fields included. If you fill in the new label and email address fields for a contact, you'll see that com_contact will store and retrieve the information for you.

The same plugin can be used to add more fields to different components; just add the relevant code into the onContentPrepareForm function and create the appropriate XML form files.

Displaying the Custom Field

To display the custom field you need to create a layout override for the relevant component in your template. For more details on creating templates see Creating a basic Joomla! template. For details on layout overrides, see Understanding Output Overrides.

Copy the file <Joomla>/components/com_contact/views/contact/tmpl/default.php to <template>/html/com_contact/contact/default.php, creating the folders in your template as necessary. We're going to edit this file to include the additional information. The com_contact component will automatically load the additional fields for us and load it into a variable called $this->params. All we need to do is check that the data is set and, if so, display it.

To display the field, find the location in <template>/html/com_contact/contact/default.php that corresponds to where you'd like the additional email address to be displayed and add the following code:

<?php if ($this->params->get('contact_emaillabel2', false)) : ?>
	<div>
		<span class="contact-additionalemail"><?php echo $this->params->get('contact_emaillabel2');?>:&emsp;<a href="mailto:<?php echo $this->params->get('contact_email2'); ?>"><?php echo $this->params->get('contact_email2'); ?></a><br/></span>
	</div>
<?php endif; ?>

If you add this code and install your template, you will now have the custom field displaying in your public Website.