Menus
Elgg propose des fonctions d’aide pour créer des menus sur tout le site.
Chaque menu nécessite un nom, tout comme chaque élément de menu. Ceux-ci sont nécessaires pour permettre un remplacement et une manipulation faciles, ainsi que pour fournir des événements pour les thèmes.
Contenu
Utilisation simple
Les fonctionnalités de base peuvent être réalisées grâce à ces deux fonctions :
elgg_register_menu_item()
pour ajouter un élément à un menu
elgg_unregister_menu_item()
pour supprimer un élément d’un menu
Vous voudrez normalement les appeler à partir de la fonction d’initialisation de votre plugin.
Exemples
// Add a new menu item to the site main menu
elgg_register_menu_item('site', array(
'name' => 'itemname',
'text' => 'This is text of the item',
'href' => '/item/url',
));
// Remove the "Elgg" logo from the topbar menu
elgg_unregister_menu_item('topbar', 'elgg_logo');
Menu admin
Vous pouvez également enregistrer des éléments du menu page
dans le menu de l’interface d’administration. Lorsque vous enregistrez des éléments pour le menu d’administration, vous pouvez définir le contexte des éléments de menu sur admin
afin que les éléments du menu ne s’affichent que dans le contexte admin
. Il existe 3 sections par défaut auxquelles ajouter vos éléments de menu.
administer
pour les tâches quotidiennes, la gestion des utilisateurs et d’autres tâches pratiques
configure
pour des paramètres, des éléments de configuration et des utilitaires qui configurent diverses choses
information
pour des statistiques, une vue d’ensemble d’informations ou de statuts
Utilisation avancée
Entêtes
Pour des raisons d’accessibilité, chaque menu recevra un aria-label
qui par défaut est le nom du menu, mais peut être traduit en s’assurant que la clef de traduction menu:<menu name>:header
est disponible.
Il est également possible d’afficher les entêtes des sections de menu en définissant show_section_headers
sur true
dans elgg_view_menu()
echo elgg_view_menu('my_menu', [
'show_section_headers' => true,
]);
Les entêtes utilisent une clé de langage magique disponible menu:<menu name>:header:<section name>
afin de pouvoir traduire les entêtes.
Événements
Vous pouvez obtenir plus de contrôle sur les menus en utilisant events et les méthodes publiques fournies par la classe ElggMenuItem
.
- Trois événements peuvent être utilisés pour modifier un menu :
'parameters', 'menu:'
pour ajouter ou modifier les paramètres utilisés pour construire le menu (par exemple l’ordre de tri)'register', 'menu:'
pour ajouter ou modifier des éléments (en particulier dans les menus dynamiques)'prepare', 'menu:'
pour modifier la structure du menu avant qu’il soit affiché
Lorsque vous enregistrez un gestionnaire d’événements, remplacez la partie <menu name>
par le nom interne du menu.
Le troisième paramètre passé au gestionnaire de menu contient tous les éléments de menu qui ont été enregistrés jusqu’à présent par le noyau de Elgg et d’autres plugins activés. Dans le gestionnaire, nous pouvons faire une boucle à travers les éléments de menu et utiliser les méthodes de classe pour interagir avec les propriétés de l’élément de menu.
Dans certains cas, une version plus granulaire des événements de menu register
et prepare
existe avec menu:<menu name>:<type>:<subtype>
, cela s’applique lorsque le menu reçoit un \ElggEntity
dans `` $params[“entity”]`` ou un \ElggAnnotation
dans $params['annotation']
ou un \ElggRelationship
dans $params['relationship']
.
Exemples
Exemple 1 : Modifier l’URL de l’élément de menu appelé « albums » dans le menu owner_block
:
/**
* Initialize the plugin
*/
function my_plugin_init() {
// Register an event handler for the owner_block menu
elgg_register_event_handler('register', 'menu:owner_block', 'my_owner_block_menu_handler');
}
/**
* Change the URL of the "Albums" menu item in the owner_block menu
*/
function my_owner_block_menu_handler(\Elgg\Event $event) {
$owner = $event->getEntityParam();
// Owner can be either user or a group, so we
// need to take both URLs into consideration:
switch ($owner->getType()) {
case 'user':
$url = "album/owner/{$owner->guid}";
break;
case 'group':
$url = "album/group/{$owner->guid}";
break;
}
$items = $event->getValue();
if ($items->has('albums')) {
$items->get('albums')->setURL($url);
}
return $items;
}
- Exemple 2 : Modifier le menu
entity
pour les objetsElggBlog
Supprimer l’icône du pouce
Modifier le texte « Modifier » en une icône personnalisée
/**
* Initialize the plugin
*/
function my_plugin_init() {
// Register an event handler for the entity menu
elgg_register_event_handler('register', 'menu:entity', 'my_entity_menu_handler');
}
/**
* Customize the entity menu for ElggBlog objects
*/
function my_entity_menu_handler(\Elgg\Event $event) {
// The entity can be found from the $params parameter
$entity = $event->getEntityParam();
// We want to modify only the ElggBlog objects, so we
// return immediately if the entity is something else
if (!$entity instanceof ElggBlog) {
return;
}
$items = $event->getValue();
$items->remove('likes');
if ($items->has('edit')) {
$items->get('edit')->setText('Modify');
$items->get('edit')->icon = 'pencil';
}
return $items;
}
Créer un nouveau menu
Elgg fournit plusieurs menus différents par défaut. Vous pouvez cependant avoir besoin de certains éléments de menu qui ne figurent pas dans l’un des menus existants. Si tel est le cas, vous pouvez créer votre propre menu avec la fonction elgg_view_menu()
. Vous devez appeler la fonction à partir de la vue dans laquelle vous souhaitez afficher le menu.
Exemple: Afficher un menu appelé « my_menu » qui affiche ses éléments de menu dans l’ordre alphabétique :
// in a resource view
echo elgg_view_menu('my_menu', array('sort_by' => 'text'));
Vous pouvez maintenant ajouter de nouveaux éléments au menu comme ceci :
// in plugin init
elgg_register_menu_item('my_menu', array(
'name' => 'my_page',
'href' => 'path/to/my_page',
'text' => elgg_echo('my_plugin:my_page'),
));
De plus il est désormais possible de modifier le menu à l’aide des événements 'register', 'menu:my_menu'
et 'prepare', 'menu:my_menu'
.
Sous-menus déroulants
Les sous-menus peuvent être configurés à l’aide de l’option child_menu
de l’élément parent.
Le tableau d’options child_menu
accepte le paramètre display
, qui peut être utilisé pour définir que le menu enfant s’ouvre sous forme de liste déroulante dropdown
, ou être affiché via une bascule toggle
. Toutes les autres paires de clefs/valeurs seront transmises en tant qu’attributs à l’élément ul
.
// Register a parent menu item that has a dropdown submenu
elgg_register_menu_item('my_menu', array(
'name' => 'parent_item',
'href' => '#',
'text' => 'Show dropdown menu',
'child_menu' => [
'display' => 'dropdown',
'class' => 'elgg-additional-child-menu-class',
'data-position' => json_encode([
'at' => 'right bottom',
'my' => 'right top',
'collision' => 'fit fit',
]),
'data-foo' => 'bar',
'id' => 'dropdown-menu-id',
],
));
// Register a parent menu item that has a hidden submenu toggled when item is clicked
elgg_register_menu_item('my_menu', array(
'name' => 'parent_item',
'href' => '#',
'text' => 'Show submenu',
'child_menu' => [
'display' => 'dropdown',
'class' => 'elgg-additional-submenu-class',
'data-toggle-duration' => 'medium',
'data-foo' => 'bar2',
'id' => 'submenu-id',
],
));
Création de thèmes
Le nom du menu, les noms de sections et les noms des éléments sont tous intégrés dans le HTML sous forme de classes CSS (normalisées pour ne contenir que des traits d’union, plutôt que des soulignements ou des points). Cela augmente légèrement la taille du balisage, mais procure aux intégrateurs un haut degré de contrôle et de flexibilité lors de la mise en forme du site.
Exemple : Voici la sortie du menu foo
avec les sections alt
et default
contenant respectivement les éléments baz
et bar
.
<ul class="elgg-menu elgg-menu-foo elgg-menu-foo-alt">
<li class="elgg-menu-item elgg-menu-item-baz"></li>
</ul>
<ul class="elgg-menu elgg-menu-foo elgg-menu-foo-default">
<li class="elgg-menu-item elgg-menu-item-bar"></li>
</ul>
Basculer des éléments de menu
Il y a des situations où vous souhaitez basculer entre des éléments de menu qui sont des actions contraires l’une de l’autre, et les ajaxifier. Par exemple ajouter/retirer un contact, bannir/réintégrer, etc. Elgg dispose d’une prise en charge intégrée pour ce genre d’actions. Lorsque vous enregistrez un élément de menu, vous pouvez fournir le nom de l’élément de menu (dans le même menu) qui doit être basculé. Un appel ajax sera fait en utilisant le href de l’élément de menu.
elgg_register_menu_item('my_menu', [
'name' => 'like',
'data-toggle' => 'unlike',
'href' => 'action/like',
'text' => elgg_echo('like'),
]);
elgg_register_menu_item('my_menu', [
'name' => 'unlike',
'data-toggle' => 'like',
'href' => 'action/unlike',
'text' => elgg_echo('unlike'),
]);
Note
Les éléments de menu sont basculés de manière optimiste. Cela signifie que les éléments de menu sont basculés avant la fin des actions. Si les actions échouent, les éléments de menu seront rétablis.
JavaScript
Il est courant que les éléments de menu s’appuient sur JavaScript. Vous pouvez lier les événements côté client aux éléments du menu en plaçant votre JavaScript dans le module AMD et en définissant ses exigences lors de son enregistrement.
elgg_register_menu_item('my_menu', array(
'name' => 'hide_on_click',
'href' => '#',
'text' => elgg_echo('hide:on:click'),
'item_class' => '.hide-on-click',
'deps' => ['navigation/menu/item/hide_on_click'],
));
// in navigation/menu/item/hide_on_click.js
define(function(require) {
var $ = require('jquery');
$(document).on('click', '.hide-on-click', function(e) {
e.preventDefault();
$(this).hide();
});
});