J3.x

Ajout de champs personnalisés/Implémentation dans votre composant

From Joomla! Documentation

< J3.x:Adding custom fields
This page is a translated version of the page J3.x:Adding custom fields/Implement into your component and the translation is 44% complete.

Other languages:
Deutsch • ‎English • ‎français • ‎Bahasa Indonesia • ‎Nederlands • ‎中文(中国大陆)‎

Implémentation dans votre composant


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->setValue($fieldId, 'com_example.item', $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