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 plug-in de contenu et une substitution 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 de courriel supplémentaire dans com_contact. Si vous avez besoin d'ajouter des champs personnalisés au com_content pour vos articles Joomla, il vous suffit de modifier les références contact par content dans le code ci-dessous. Veuillez noter que com_content utilise attribs et non pas params pour les champs de valeur ainsi que pour les overrides.

Ajout d'un champ personnalisé

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

Pour ajouter un champ à un composant du système, vous devez créer un plug-in 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.

<?php
// no direct access
defined ('_JEXEC') or die;
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 <your version>
	 */
	protected $autoloadLanguage = true;

	/**
	 * Prepare form and add my field.
	 *
	 * @param   JForm  $form  The form to be altered.
	 * @param   mixed  $data  The associated data for the form.
	 *
	 * @return  boolean
	 *
	 * @since   <your version>
	 */
	function onContentPrepareForm($form, $data)
	{
		$app    = JFactory::getApplication();
		$option = $app->input->get('option');

		switch($option)
		{
			case 'com_contact' :
				if ($app->isClient('administrator'))
				{
					JForm::addFormPath(__DIR__ . '/forms');
					$form->loadFile('contact', false);
				}

				return true;
		}

		return true;
	}
}
?>

Activation de l'édition des champs personnalisés en frontend

Activer l'édition en frontend de vos champs personnalisés est assez facile. Pour ajouter des champs à votre formulaire d'édition de contenu en frontend, il suffit d'ajouter le bloc de code suivant :

case 'com_contact':
	if ($app->isClient('site'))
	{
		JForm::addFormPath(__DIR__ . '/forms');
		$form->loadFile('contact', false);
	}
	return true;

Ajoutez ceci immédiatement au-dessous de l'instance existante.

Une fois que vous avez fait cela, créez une substitution de template pour le fichier formulaire de contenu edit.php. Si vous souhaitez la création d'un ensemble de champs personnalisés pour le com_contact, vous devez copier /components/com_contact/views/form/tmpl/edit.php vers /templates/your-template-name/html/com_contact/form/edit.php.

À l'intérieur de votre substitution de rendu, ajoutez les nouveaux champs de formulaire que vous souhaitez à l'emplacement où vous désirez qu'ils s'affichent (par exemple, en dessous du titre ou en dessous de la description), en vous assurant que les noms des champs correspondent bien à ceux du fichier XML de votre plugin fichier que nous allons créer maintenant.

<?php // Checking if this is an existing item or not ?>
<?php if ($this->item->id) : ?>
  <?php // If it is an existing item, get the attribs part of the existing record ?>
  <?php $attribs = json_decode($this->item->attribs); ?>
  <?php // Set the value of the custom field to what is already saved. ?>
  <?php // Duplicate for the number of fields you need, changing the field_name as needed. ?>
  <?php echo $this->form->setValue('field_name', 'attribs', $attribs->field_name); ?>
<?php endif; ?>
<?php // This line needs added to the file right where you want to display it. So, if you want it to show right after the description field, find the description field and place this right after it. Duplicate for the number of fields you need, changing the field_name as needed. ?>
<?php // Now we display the field. If we are editing an existing item, the previously saved data will be populated already ?>
<?php echo $this->form->renderField('field_name', 'attribs'); ?>

Ceci fait, vos champs apparaîtront et seront stockés via l'interface d'édition en frontend.

Les champs supplémentaires sont chargés à partir du fichier forms/contact.xml dans le répertoire de plug-in. Il est important que ces champs soient dans un élément "fields" avec la propriété "name" définie sur "params". Si vous ne définissez pas cela ainsi, les champs s'afficheront dans l'administration du site mais les valeurs ne seront pas enregistrées. Remarque : dans com_content, votre champ doit être nommé <fields name="attribs"> sinon les champs apparaitront dans l'admin du site mais les valeurs ne seront pas enregistrées.

Dans ce cas, nous ajoutons un champ pour une étiquette afin de décrire le champ courriel sur la partie public du site web et un deuxième champ pour la valeur de l'adresse.

<?xml version="1.0" encoding="UTF-8"?>
<form>
	<fields name="params">
		<fieldset name="params" label="PLG_CONTENT_EXAMPLE_FIELDSET_LABEL">
			<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>

Enfin, nous avons besoin d'un fichier de langue de sorte que les paramètres soient présentés correctement dans l'administration du site et soient traduisibles dans d'autres langues. Ce fichier doit être nommé quelque chose comme en-GB.plg_content_example.ini.

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

Cela permet d'ajouter le champ au com_contact. Si vous installez ce plug-in, vous aurez un onglet supplémentaire dans l'édition du formulaire de contact formulaire nommé "Additional Information" comprenant les nouveaux champs. Si vous remplissez les nouveaux champs d'étiquette et d'adresse de courriel pour un contact, vous verrez que le com_contact va stocker et récupérer les informations pour vous.

Le même plug-in peut être utilisé pour ajouter des champs supplémentaires à d'autres composants, il suffit d'ajouter le code à la fonction onContentPrepareForm et de créer les fichiers de formulaire XML appropriés.

Afficher le champ personnalisé

Pour afficher le champ personnalisé, vous devez créer une subsitution de mise en page (layout) dans votre template pour le composant concerné. Pour plus d'informations sur la création de templates, voir création d'un template de base pour Joomla. Pour plus d'informations sur les substitutions de mise en page (layout), voir comprendre les substitutions de sortie.

Copiez le fichier <Joomla>/components/com_contact/views/contact/tmpl/default.php dans <template>/html/com_contact/contact/default.php, créez les dossiers dans votre template si nécessaire. Nous allons modifier ce fichier pour inclure les informations supplémentaires. Le composant com_contact va automatiquement charger les champs supplémentaires et ce, dans une variable nommée $this->params. Tout ce que nous avons à faire est de vérifier que les données sont définies et le cas échéant, de les afficher.

Pour afficher le champ, trouvez dans <template>/html/com_contact/contact/default.php l'emplacement où vous souhaitez que l'adresse de courriel s'affiche et ajoutez le code suivant :

<?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; ?>

Si vous ajoutez ce code et installez votre template, alors le champ personnalisé s'affichera sur la partie publique de votre site.