Ajout de champs personnalisés/Implémentation dans votre composant
From Joomla! Documentation
< J3.x:Adding custom fields
Implémentation dans votre composant
Les articles de cette série
- Introduction
- Paramètres des champs personnalisés
- Champ Calendrier
- Champ Cases à cocher
- Champ Couleur
- Champ Editeur
- Champ Entier relatif
- Champ Liste
- Champ Liste d'images
- Champ Média
- Champ Bouton Radio
- Champ Répétabilité
- Champ Sql
- Champ Texte
- Champ Zone de texte
- Champ URL
- Champ Utilisateur
- Champ Groupe d'utilisateurs
- Comment grouper les champs personnalisés
- Quels sont les composants supportant les champs personnalisés
- Implémentation dans votre composant
- Utiliser les champs personnalisés dans vos substitutions
Intégrer les champs personnalisés dans votre composant
Cet article décrit comment effectuer une implémentation de base de la fonctionnalité des champs personnalisés dans votre propre composant.
Vous souhaiteriez ajouter des paramètres additionnels à vos objets ? Au travers des champs personnalisés, vous avez une manière fluide de les intégrer et de les afficher dans votre site d'administration et dans votre site public.
Les champs personnalisés peuvent avoir 15 types différents, si vous voulez en savoir plus, voyez créer votre propre plugin..
L'extension des champs personnalisés est située dans le noyau et peut être utilisée d'une manière similaire à l'extension des catégories.
De manière basique, seulement 2 fichiers sont nécessaires pour l'extension avec le code suivant pour la partie basique du backend.
A notez ! Dans le code exemple, nous utiliserons comme nom de composant le nom com_example.
La partie backend
Comment ajouter les champs personnalisés dans les listes du backend
De manière similaire à com_categories, il y a juste quelques lignes nécessaires pour ajouter les champs personnalisés dans la vue backend.
Ajoutez simplement les lignes suivantes à la méthode addSubmenu
dans la classe helper de votre composant.
Le contexte utilisé doit correspondre au contexte dans lequel vous voulez implémenter le champ. Un exemple de contexte pourrait être com_content.article ou com_weblinks.weblink. Nous utilisons com_example.item ici comme exemple. Seul le paramètre de contexte doit être modifié.
if (JComponentHelper::isEnabled('com_fields'))
{
JHtmlSidebar::addEntry(
JText::_('JGLOBAL_FIELDS'),
'index.php?option=com_fields&context=com_example.item',
$vName == 'fields.fields'
);
JHtmlSidebar::addEntry(
JText::_('JGLOBAL_FIELD_GROUPS'),
'index.php?option=com_fields&view=groups&context=com_example.item',
$vName == 'fields.groups'
);
}
Implémentation des droits
Maintenant, la partie concernant l'attribution des droits doit être implémentée. Vous devez ajouter les lignes suivantes dans votre fichier access xml juste avant la balise finale </access>
dans ce fichier. Ici, ils sont définis et vont permettre à vos utilisateurs de choisir les paramètres de droits dans votre implémentation de com_fields.
<section name="fieldgroup">
<action name="core.create" title="JACTION_CREATE" description="COM_FIELDS_GROUP_PERMISSION_CREATE_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="COM_FIELDS_GROUP_PERMISSION_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_FIELDS_GROUP_PERMISSION_EDIT_DESC" />
<action name="core.edit.state" title="JACTION_EDITSTATE" description="COM_FIELDS_GROUP_PERMISSION_EDITSTATE_DESC" />
<action name="core.edit.own" title="JACTION_EDITOWN" description="COM_FIELDS_GROUP_PERMISSION_EDITOWN_DESC" />
<action name="core.edit.value" title="JACTION_EDITVALUE" description="COM_FIELDS_GROUP_PERMISSION_EDITVALUE_DESC" />
</section>
<section name="field">
<action name="core.delete" title="JACTION_DELETE" description="COM_FIELDS_FIELD_PERMISSION_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_FIELDS_FIELD_PERMISSION_EDIT_DESC" />
<action name="core.edit.state" title="JACTION_EDITSTATE" description="COM_FIELDS_FIELD_PERMISSION_EDITSTATE_DESC" />
<action name="core.edit.value" title="JACTION_EDITVALUE" description="COM_FIELDS_FIELD_PERMISSION_EDITVALUE_DESC" />
</section>
Voici un paramètre à saisir en plus dans ce fichier :
<action name="core.edit.value" title="JACTION_EDITVALUE" description="JACTION_EDITVALUE_COMPONENT_DESC" />
This entry should be made under the normal settings in your component (and also in the access xml file) as it allows users in the group to edit any value of custom fields submitted in your component.
Result
If you completed these steps, your backend part for fields implementation is done. The users can now create fields and assign them to an item.
The Frontend Part
Now let's go to the frontend part. It is easy as the fields are rendered, through the Plugin/Events/Content events on the frontend.
To display fields on the frontend, you need to implement the content plugin events in your component.
Important here is where you pass the same context that you used in the backend to the events.
See:
After the onContentPrepare event is fired with the context you can find the attached fields in $item->jcfields property if you want to render the fields using in your layouts / views.
Tips, Tricks & Hidden Features
Here you can find some tips and tricks on what can be gone wrong with your implementation as well as some hidden features of com_fields.
The fields tab don’t show up in my component's edit view
In some components the edit views in backend and/or frontend are hardcoded and can't be changed / extended using plugins. But as the fields uses a plugin to add the fields to your component you need to support that in order to support fields. You can make sure that fields are rendered e.g. by implementing the following layout in your component edit view:
<?php $this->ignore_fieldsets = array('general', 'info', 'detail', 'jmetadata', 'item_associations'); ?>
<?php echo JLayoutHelper::render('joomla.edit.params', $this); ?>
The first line makes sure we ignore the (eventually hardcoded fieldsets) and than render the dynamic fields tab using the joomla.edit.params
layout.
Public helper classes and API
The class FieldsHelper has some public API functions to work with fields.
JLoader::register('FieldsHelper', JPATH_ADMINISTRATOR . '/components/com_fields/helpers/fields.php');
$fields = FieldsHelper::getFields('com_example.item', $item, true);
The field model itself allows to get and store the value of a field.
JModelLegacy::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_fields/models', 'FieldsModel');
$fieldModel = JModelLegacy::getInstance('Field', 'FieldsModel', array('ignore_request' => true));
$fieldModel->setFieldValue($fieldId, $item->id, 'demo value');
ACL support
- Every field has an access level
- Every field has a new permission edit.value
JFactory::getUser()->authorise('edit.value', ‘com_example.item.field.' . (int) $field->id);
More Information
- https://www.youtube.com/watch?v=7ikOaOKyo6s | JAB16 - Les champs personnalités dans Joomla! pour les développeurs - En anglais
- https://www.youtube.com/watch?v=F_Ni15icn1U | JD16AT - Les champs personnalisés depuis Joomla! 3.7 - En anglais
- https://joomla.digital-peak.com/images/blog/JDD16%20Custom%20fields%20in%20Joomla%20for%20developers.pdf