Paramètres de plugin

Vous devez effectuer quelques étapes supplémentaires si votre plugin a besoin de paramètres qui doivent être enregistrés et contrôlés via le panneau d’administration :

  • Créez un fichier dans le dossier des vues par défaut de votre plugin appelé plugins/your_plugin/settings.php, où your_plugin est le nom du répertoire de votre plugin dans la hiérarchie mod

  • Remplissez ce fichier avec les éléments de formulaire que vous souhaitez afficher avec les traductions des étiquettes de texte

  • Définissez l’attribut name dans vos composants de formulaire sur params[`varname`] où varname est le nom de la variable. Ceux-ci seront enregistrés sous forme de métadonnées attachées à une entité de plugin. Ainsi, si votre variable s’appelle params[myparameter], votre plugin (qui est également passé à cette vue sous le nom $vars['entity']) s’appellera $vars['entity'] ->myparameter

Un exemple de settings.php ressemblerait à :

echo elgg_view_field([
        '#type' => 'select',
        '#label' => elgg_echo('myplugin:settings:limit'),
        'name' => 'params[limit]',
        'value' => $vars['entity']->limit,
        'options' => [5,8,12,15],
]);

Note

Vous n’avez pas besoin d’ajouter de bouton d’enregistrement ni le formulaire, cela sera géré par le framework.

Note

Vous ne pouvez pas utiliser des composants de formulaire qui n’envoient aucune valeur lorsqu’ils sont « off ». Il s’agit notamment des entrées radio et des cases à cocher.

Si vos paramètres de plugin ont besoin d’un vidage des caches, vous pouvez ajouter une entrée (cachée) sur le formulaire avec le nom “flush_cache” et la valeur “1”

elgg_view_field([
        '#type' => 'hidden',
        'name' => 'flush_cache',
        'value' => 1,
]);

Paramètres de l’utilisateur

Votre plugin peut également avoir besoin de stocker des paramètres pour chaque utilisateur, et vous voudrez voir les options de votre plugin apparaître dans la page des paramètres de l’utilisateur. Ceci est également facile à faire et suit le même modèle que la configuration globale du plugin expliquée plus tôt. La seule différence est qu’au lieu d’utiliser un fichier settings, vous utiliserez usersettings. Ainsi, le chemin d’accès à la vue de modification des paramètres utilisateur de votre plugin serait plugins/<your_plugin>/usersettings.php.

Note

Le titre du formulaire des paramètres utilisateur sera par défaut le nom du plugin. Si vous souhaitez modifier cela, ajoutez une traduction pour <plugin_id>:usersettings:title.

Paramètres du groupe

Si votre plugin a besoin de paramètres pour chaque groupe, vous pouvez étendre la vue groups/edit/settings pour afficher vos paramètres. Les paramètres sont affichés lors de la création et de la modification du groupe. Pour que les paramètres soient enregistrés correctement, ils ont besoin d’un nom au format settings[<plugin id>][<setting name>].

Récupérer des paramètres dans votre code

Pour récupérer les paramètres depuis votre code utilisez :

$setting = elgg_get_plugin_setting($name, $plugin_id);

ou pour les paramètres utilisateur :

$user_setting = elgg_get_plugin_user_setting($name, $user_guid, $plugin_id);

// or
$user = get_user($user_guid);
$user_setting = $user->getPluginSetting($plugin_id, $name);

où :

  • $name Est la valeur que vous souhaitez récupérer

  • $user_guid Est l’utilisateur pour lequel vous souhaitez récupérer ces valeurs (par défaut l’utilisateur actuellement connecté)

  • $plugin_name Est le nom du plugin (détecté s’il s’exécute à partir d’un plugin)

ou pour les paramètres du groupe :

$group = get_entity($group_guid);
$value = $group->getPluginSetting('<plugin id>', '<setting name>');

Définir des valeurs via le code

Les valeurs peuvent également être définies à partir du code de votre plugin, pour cela utilisez l’une des fonctions suivantes :

$plugin = elgg_get_plugin_from_id($plugin_id);
$plugin->setSetting($name, $value);

ou pour les paramètres utilisateur :

$user = elgg_get_logged_in_user_entity();
$user->setPluginSetting($plugin_id, $name, $value);

ou pour les paramètres du groupe :

$group = get_entity($group_guid);
$group->setPluginSetting($plugin_id, $name, $value);

Avertissement

Le $plugin_id doit être fourni lors de la définition des paramètres du plugin (ou de l’utilisateur).

Paramètres par défaut (groupe|utilisateur) du plugin

Si un plugin ou un utilisateur n’a pas de paramètre stocké dans la base de données, vous avez parfois besoin d’une certaine valeur par défaut. Vous pouvez passer cela lors de l’utilisation des fonctions de récupération - getter.

$user_setting = elgg_get_plugin_user_setting($name, $user_guid, $plugin_id, $default);

$plugin_setting = elgg_get_plugin_setting($name, $plugin_id, $default);

$group_setting = $group->getPluginSetting($plugin_id, $name, $default);

Vous pouvez également fournir des paramètres par défaut du plugin et de l’utilisateur dans le fichier elgg-plugin.php.

<?php

return [
        'settings' => [
            'key' => 'value',
        ],
        'user_settings' => [
            'key' => 'value',
        ],
];

Note

Les paramètres de groupe n’ont pas de valeur par défaut disponible dans le fichier elgg-plugin.php.