[Feature Request] Hook for Adding Plugin Submenu to Admin Menubar #2199

New Issue

Closed

opened 2026-10-05 01:09:28 +02:00 by adam · 4 comments

adam commented 2026-10-05 01:09:28 +02:00

Owner

Copy link

Copy source

Piwigo Feature Request: Hook for Adding Plugin Submenu to Admin Menubar

Author : Gotcha (Piwigo Mosaic plugin)
Date : 2026-03-03
Repository : https://github.com/Piwigo/Piwigo
Type : Feature Request

---

Summary

Add a admin_menubar_plugin_links hook allowing plugins to inject entries into an expandable submenu under the "Plugins" section in the admin sidebar. This would provide plugins with better UI integration without DOM manipulation and make the menubar extensible and maintainable.

---

Current Problem

Admin Menubar State

The admin sidebar (admin/themes/default/template/admin.tpl) consists of static expandable sections (<dl>) hardcoded in the theme template. Each section follows this pattern:

<dl>
  <dt>
    <i class="icon-xxx"></i>
    <span>Title</span>
    <i class="icon-down-open open-menu"></i>
  </dt>
  <dd>
    <ul>
      <li><a href="...">Link</a></li>
    </ul>
  </dd>
</dl>

Issue : The "Plugins" section is currently simplified — it has no <dd> and works as a simple link:

<dl>
  <dt>
    <a href="{$U_PLUGINS}" class="admin-main">
      <i class="icon-puzzle"></i>
      <span>Plugins</span>
    </a>
  </dt>
</dl>

Situation with Plugins

There is no native mechanism allowing a plugin to add entries to the admin sidebar. Available hooks are insufficient:

Hook	Current Usefulness
get_admin_plugin_menu_links	Adds links on the plugin list page, not in the sidebar
loc_begin_admin	Runs before admin rendering, no access to menubar template
loc_begin_admin_page	Allows HTML/JS injection, but requires DOM manipulation (fragile)
loc_end_admin	Runs after rendering, too late for certain operations

Consequence : Plugins like Mosaic cannot display their menu in the sidebar without:

1. JavaScript DOM manipulation (fragile, not sustainable)
2. Admin theme modification (complicated, not scalable)
3. Third-party injection plugin (increased complexity)

---

Proposed Solution

1. New Hook: admin_menubar_plugin_links

Add a hook in admin.php (after $U_PLUGINS assignment):

// Call the hook to retrieve submenu items
$plugins_menu_items = trigger_change('admin_menubar_plugin_links', array());
$template->assign('PLUGINS_MENU_ITEMS', $plugins_menu_items);

2. Modify Template admin.tpl

Replace the static Plugins section with a dynamic one:

<dl id="menubar-plugins">
  <dt>
    {if $PLUGINS_MENU_ITEMS}
      <i class="icon-puzzle"></i>
      <span>{'Plugins'|@translate}&nbsp;</span>
      <i class="icon-down-open open-menu"></i>
    {else}
      <a href="{$U_PLUGINS}" class="admin-main">
        <i class="icon-puzzle"></i>
        <span>{'Plugins'|@translate}&nbsp;</span>
      </a>
    {/if}
  </dt>
  {if $PLUGINS_MENU_ITEMS}
  <dd>
    <ul>
      <li><a href="{$U_PLUGINS}"><i class="icon-list"></i>{'Manage'|@translate}</a></li>
      {foreach from=$PLUGINS_MENU_ITEMS item=item}
      <li><a href="{$item.URL}"><i class="{$item.ICON|default:'icon-puzzle'}"></i>{$item.NAME}</a></li>
      {/foreach}
    </ul>
  </dd>
  {/if}
</dl>

3. Plugin Usage Example (Mosaic)

A plugin can simply register its hook:

add_event_handler('admin_menubar_plugin_links', 'Mosaic_menubar_link');

function Mosaic_menubar_link($items)
{
  $items[] = array(
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
  );
  return $items;
}

---

Benefits of This Approach

Aspect	Details
Cleanliness	No DOM manipulation — server-side rendering, no fragile JavaScript
Backward Compatibility	Without plugins, the section remains a simple link (unchanged behavior)
Extensibility	Each plugin adds its entry independently, without collisions
Maintainability	Centralized modification in admin.php and admin.tpl
Theme Support	Compatible with all admin themes (not limited to default)
Flexibility	Future support for $ACTIVE_MENU flag to highlight the section

---

No Breaking Changes

• By default : Without plugins, $PLUGINS_MENU_ITEMS is empty → behavior identical to today
• With plugins : The hook adds entries and activates the submenu → improved user experience
• Custom themes : Themes that don't implement the modified template retain their current behavior

---

Implementation Estimate

Element	Effort
Add hook in admin.php	~5 min
Modify admin.tpl template	~10 min
Manage $ACTIVE_MENU (optional)	~15 min
Total	~30 min (very surgical)

---

Primary Use Cases

1. Mosaic — Display a link to the plugin's admin panel directly in the sidebar
2. Layout Plugins — Integrate their panels in the sidebar for better UX
3. Admin Plugins — centralAdmin, etc., can easily expose their menus

---

Priority Suggestion

• Priority : Medium (UX improvement, not critical but highly desired)
• Complexity : Very Low (~30 minutes of dev)
• Risk : None (surgical modification, backward compatible)

---

Discussion Points (Optional)

• Should we add a second hook admin_menubar_before_plugins to add sections before Plugins?
• Should we support an active flag on each item to auto-highlight?
• Should we expose a helper get_plugin_menu_item() to normalize structure?

---

Conclusion

Adding the admin_menubar_plugin_links hook is a legitimate request to improve plugin integration in the admin interface. It's a minor and sustainable modification that solves a UI design problem without impacting performance or compatibility.

Recommended : ⭐ Accept (30 min implementation, immediate UX gain for plugins and users)

# Piwigo Feature Request: Hook for Adding Plugin Submenu to Admin Menubar **Author** : Gotcha (Piwigo Mosaic plugin) **Date** : 2026-03-03 **Repository** : https://github.com/Piwigo/Piwigo **Type** : Feature Request --- ## Summary Add a **`admin_menubar_plugin_links` hook** allowing plugins to inject entries into an expandable submenu under the "Plugins" section in the admin sidebar. This would provide plugins with better UI integration without DOM manipulation and make the menubar **extensible and maintainable**. --- ## Current Problem ### Admin Menubar State The admin sidebar (`admin/themes/default/template/admin.tpl`) consists of static expandable sections (`<dl>`) hardcoded in the theme template. Each section follows this pattern: ```html <dl> <dt> <i class="icon-xxx"></i> <span>Title</span> <i class="icon-down-open open-menu"></i> </dt> <dd> <ul> <li><a href="...">Link</a></li> </ul> </dd> </dl> ``` **Issue** : The "Plugins" section is currently **simplified** — it has **no `<dd>`** and works as a simple link: ```html <dl> <dt> <a href="{$U_PLUGINS}" class="admin-main"> <i class="icon-puzzle"></i> <span>Plugins</span> </a> </dt> </dl> ``` ### Situation with Plugins There is **no native mechanism** allowing a plugin to add entries to the admin sidebar. Available hooks are **insufficient**: | Hook | Current Usefulness | |------|------------------| | `get_admin_plugin_menu_links` | Adds links on the *plugin list page*, not in the sidebar | | `loc_begin_admin` | Runs before admin rendering, no access to menubar template | | `loc_begin_admin_page` | Allows HTML/JS injection, but requires DOM manipulation (fragile) | | `loc_end_admin` | Runs after rendering, too late for certain operations | **Consequence** : Plugins like **Mosaic** cannot display their menu in the sidebar without: 1. **JavaScript DOM manipulation** (fragile, not sustainable) 2. **Admin theme modification** (complicated, not scalable) 3. **Third-party injection plugin** (increased complexity) --- ## Proposed Solution ### 1. New Hook: `admin_menubar_plugin_links` Add a hook in `admin.php` (after `$U_PLUGINS` assignment): ```php // Call the hook to retrieve submenu items $plugins_menu_items = trigger_change('admin_menubar_plugin_links', array()); $template->assign('PLUGINS_MENU_ITEMS', $plugins_menu_items); ``` ### 2. Modify Template `admin.tpl` Replace the static Plugins section with a dynamic one: ```smarty <dl id="menubar-plugins"> <dt> {if $PLUGINS_MENU_ITEMS} <i class="icon-puzzle"></i> <span>{'Plugins'|@translate}&nbsp;</span> <i class="icon-down-open open-menu"></i> {else} <a href="{$U_PLUGINS}" class="admin-main"> <i class="icon-puzzle"></i> <span>{'Plugins'|@translate}&nbsp;</span> </a> {/if} </dt> {if $PLUGINS_MENU_ITEMS} <dd> <ul> <li><a href="{$U_PLUGINS}"><i class="icon-list"></i>{'Manage'|@translate}</a></li> {foreach from=$PLUGINS_MENU_ITEMS item=item} <li><a href="{$item.URL}"><i class="{$item.ICON|default:'icon-puzzle'}"></i>{$item.NAME}</a></li> {/foreach} </ul> </dd> {/if} </dl> ``` ### 3. Plugin Usage Example (Mosaic) A plugin can simply register its hook: ```php add_event_handler('admin_menubar_plugin_links', 'Mosaic_menubar_link'); function Mosaic_menubar_link($items) { $items[] = array( 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', ); return $items; } ``` --- ## Benefits of This Approach | Aspect | Details | |--------|---------| | **Cleanliness** | No DOM manipulation — server-side rendering, no fragile JavaScript | | **Backward Compatibility** | Without plugins, the section remains a simple link (unchanged behavior) | | **Extensibility** | Each plugin adds its entry independently, without collisions | | **Maintainability** | Centralized modification in `admin.php` and `admin.tpl` | | **Theme Support** | Compatible with all admin themes (not limited to `default`) | | **Flexibility** | Future support for `$ACTIVE_MENU` flag to highlight the section | --- ## No Breaking Changes - **By default** : Without plugins, `$PLUGINS_MENU_ITEMS` is empty → behavior identical to today - **With plugins** : The hook adds entries and activates the submenu → improved user experience - **Custom themes** : Themes that don't implement the modified template retain their current behavior --- ## Implementation Estimate | Element | Effort | |---------|--------| | Add hook in `admin.php` | ~5 min | | Modify `admin.tpl` template | ~10 min | | Manage `$ACTIVE_MENU` (optional) | ~15 min | | **Total** | ~30 min (very surgical) | --- ## Primary Use Cases 1. **Mosaic** — Display a link to the plugin's admin panel directly in the sidebar 2. **Layout Plugins** — Integrate their panels in the sidebar for better UX 3. **Admin Plugins** — centralAdmin, etc., can easily expose their menus --- ## Priority Suggestion - **Priority** : Medium (UX improvement, not critical but highly desired) - **Complexity** : Very Low (~30 minutes of dev) - **Risk** : None (surgical modification, backward compatible) --- ## Discussion Points (Optional) - Should we add a second hook `admin_menubar_before_plugins` to add sections **before** Plugins? - Should we support an `active` flag on each item to auto-highlight? - Should we expose a helper `get_plugin_menu_item()` to normalize structure? --- ## Conclusion Adding the `admin_menubar_plugin_links` hook is a **legitimate request** to improve plugin integration in the admin interface. It's a **minor and sustainable** modification that solves a UI design problem without impacting performance or compatibility. **Recommended** : ⭐ Accept (30 min implementation, immediate UX gain for plugins and users) <!-- github-sync-id:4018537080 -->

adam closed this issue 2026-10-05 01:09:28 +02:00

adam commented 2026-10-05 01:09:29 +02:00

Author

Owner

Copy link

Copy source

Demande de fonctionnalité Piwigo : Hook pour ajouter un sous-menu aux Plugins dans le menubar admin

Auteur : Gotcha (Piwigo Mosaic plugin)
Date : 2026-03-03
Dépôt : https://github.com/Piwigo/Piwigo
Type : Feature Request

---

Résumé

Ajouter un hook admin_menubar_plugin_links permettant à un plugin d'injecter des entrées dans un sous-menu dépliable sous la section "Plugins" du menubar latéral de l'interface admin Piwigo. Cela offrirait aux plugins une meilleure intégration UI sans manipulation DOM et rendrait le menubar extensible et maintenable.

---

Problème actuel

État du menubar admin

Le menubar latéral admin (admin/themes/default/template/admin.tpl) est constitué de sections dépliables (<dl>) statiques, hardcodées dans le template. Chaque section suit le pattern :

<dl>
  <dt>
    <i class="icon-xxx"></i>
    <span>Titre</span>
    <i class="icon-down-open open-menu"></i>
  </dt>
  <dd>
    <ul>
      <li><a href="...">Lien</a></li>
    </ul>
  </dd>
</dl>

Problème : La section "Plugins" est actuellement simplifiée — elle n'a pas de <dd> et fonctionne comme un simple lien :

<dl>
  <dt>
    <a href="{$U_PLUGINS}" class="admin-main">
      <i class="icon-puzzle"></i>
      <span>Plugins</span>
    </a>
  </dt>
</dl>

Situation avec les plugins

Il n'existe aucun mécanisme natif permettant à un plugin d'ajouter des entrées au menubar latéral admin. Les hooks disponibles sont insuffisants :

Hook	Utilité actuelle
get_admin_plugin_menu_links	Ajoute des liens sur la page liste des plugins, pas dans le menubar
loc_begin_admin	Exécuté avant le rendu admin, pas d'accès au template menubar
loc_begin_admin_page	Permet injecter du HTML/JS, mais nécessite manipulation DOM (fragile)
loc_end_admin	Exécuté après le rendu, trop tard pour certaines opérations

Conséquence : Les plugins comme Mosaic ne peuvent pas afficher leur menu dans le menubar sans :

1. Manipulation DOM en JavaScript (fragile, non pérenne)
2. Modification du thème admin (compliqué, peu évolutif)
3. Plugin tiers pour l'injection (complexité accrue)

---

Solution proposée

1. Nouveau hook : admin_menubar_plugin_links

Ajouter un hook dans admin.php (après l'assignation de $U_PLUGINS) :

// Appel du hook pour récupérer les items de sous-menu
$plugins_menu_items = trigger_change('admin_menubar_plugin_links', array());
$template->assign('PLUGINS_MENU_ITEMS', $plugins_menu_items);

2. Modification du template admin.tpl

Remplacer la section Plugins statique par une section dynamique :

<dl id="menubar-plugins">
  <dt>
    {if $PLUGINS_MENU_ITEMS}
      <i class="icon-puzzle"></i>
      <span>{'Plugins'|@translate}&nbsp;</span>
      <i class="icon-down-open open-menu"></i>
    {else}
      <a href="{$U_PLUGINS}" class="admin-main">
        <i class="icon-puzzle"></i>
        <span>{'Plugins'|@translate}&nbsp;</span>
      </a>
    {/if}
  </dt>
  {if $PLUGINS_MENU_ITEMS}
  <dd>
    <ul>
      <li><a href="{$U_PLUGINS}"><i class="icon-list"></i>{'Manage'|@translate}</a></li>
      {foreach from=$PLUGINS_MENU_ITEMS item=item}
      <li><a href="{$item.URL}"><i class="{$item.ICON|default:'icon-puzzle'}"></i>{$item.NAME}</a></li>
      {/foreach}
    </ul>
  </dd>
  {/if}
</dl>

3. Usage par un plugin (exemple : Mosaic)

Un plugin peut simplement enregistrer son hook :

add_event_handler('admin_menubar_plugin_links', 'Mosaic_menubar_link');

function Mosaic_menubar_link($items)
{
  $items[] = array(
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
  );
  return $items;
}

---

Avantages de cette approche

Aspect	Détail
Propreté	Aucune manipulation DOM — rendu serveur, pas de JavaScript fragile
Rétrocompatibilité	Sans plugin, la section reste un simple lien (comportement inchangé)
Extensibilité	Chaque plugin ajoute sa ligne indépendamment, sans collision
Maintenabilité	Modification centralisée dans admin.php et admin.tpl
Thèmes	Compatible avec tous les thèmes admin (pas limité à default)
Flexibilité	Support futur du flag $ACTIVE_MENU pour highlighter la section

---

Pas de breaking change

• Par défaut : Sans plugin, $PLUGINS_MENU_ITEMS est vide → comportement identique à aujourd'hui
• Avec plugin : Le hook ajoute les entrées et active le sous-menu → expérience utilisateur améliorée
• Thèmes personnalisés : Les thèmes qui n'implémentent pas le template modifié conservent leur comportement actuel

---

Implémentation estimée

Élément	Effort
Ajout du hook dans admin.php	~5 min
Modification du template admin.tpl	~10 min
Gestion $ACTIVE_MENU (optionnel)	~15 min
Total	~30 min (très chirurgical)

---

Cas d'usage prioritaire

1. Mosaic — Afficher un lien vers l'admin du plugin directement dans le menubar
2. Plugins layout — Intégrer leurs panels dans le menubar pour meilleur UX
3. Plugins d'administration — centralAdmin, etc., peuvent exposer leurs menus facilement

---

Suggestions de priorité

• Priorité : Moyenne (amélioration UX, pas critique mais très désirée)
• Complexité : Très basse (~30 minutes de dev)
• Risque : Nul (modification chirurgicale, rétrocompatible)

---

Points de discussion (optionnels)

• Faut-il un second hook admin_menubar_before_plugins pour ajouter des sections avant Plugins ?
• Faut-il supporter un flag active sur chaque item pour highlighter automatiquement ?
• Faut-il exposer un helper get_plugin_menu_item() pour normaliser la structure ?

---

Conclusion

L'ajout du hook admin_menubar_plugin_links est une demande légitime pour améliorer l'intégration des plugins dans l'interface admin. C'est une modification mineure et pérenne qui résout un problème de design UI sans impacter les performances ou la compatibilité.

Vote recommandé : ⭐ Accepter (30 min d'implémentation, gain UX immédiat pour plugins et utilisateurs)

# Demande de fonctionnalité Piwigo : Hook pour ajouter un sous-menu aux Plugins dans le menubar admin **Auteur** : Gotcha (Piwigo Mosaic plugin) **Date** : 2026-03-03 **Dépôt** : https://github.com/Piwigo/Piwigo **Type** : Feature Request --- ## Résumé Ajouter un **hook `admin_menubar_plugin_links`** permettant à un plugin d'injecter des entrées dans un sous-menu dépliable sous la section "Plugins" du menubar latéral de l'interface admin Piwigo. Cela offrirait aux plugins une meilleure intégration UI sans manipulation DOM et rendrait le menubar **extensible et maintenable**. --- ## Problème actuel ### État du menubar admin Le menubar latéral admin (`admin/themes/default/template/admin.tpl`) est constitué de sections dépliables (`<dl>`) statiques, hardcodées dans le template. Chaque section suit le pattern : ```html <dl> <dt> <i class="icon-xxx"></i> <span>Titre</span> <i class="icon-down-open open-menu"></i> </dt> <dd> <ul> <li><a href="...">Lien</a></li> </ul> </dd> </dl> ``` **Problème** : La section "Plugins" est actuellement **simplifiée** — elle n'a **pas de `<dd>`** et fonctionne comme un simple lien : ```html <dl> <dt> <a href="{$U_PLUGINS}" class="admin-main"> <i class="icon-puzzle"></i> <span>Plugins</span> </a> </dt> </dl> ``` ### Situation avec les plugins Il n'existe **aucun mécanisme natif** permettant à un plugin d'ajouter des entrées au menubar latéral admin. Les hooks disponibles sont **insuffisants** : | Hook | Utilité actuelle | |------|-----------------| | `get_admin_plugin_menu_links` | Ajoute des liens sur la *page liste des plugins*, pas dans le menubar | | `loc_begin_admin` | Exécuté avant le rendu admin, pas d'accès au template menubar | | `loc_begin_admin_page` | Permet injecter du HTML/JS, mais nécessite manipulation DOM (fragile) | | `loc_end_admin` | Exécuté après le rendu, trop tard pour certaines opérations | **Conséquence** : Les plugins comme **Mosaic** ne peuvent pas afficher leur menu dans le menubar sans : 1. **Manipulation DOM en JavaScript** (fragile, non pérenne) 2. **Modification du thème admin** (compliqué, peu évolutif) 3. **Plugin tiers pour l'injection** (complexité accrue) --- ## Solution proposée ### 1. Nouveau hook : `admin_menubar_plugin_links` Ajouter un hook dans `admin.php` (après l'assignation de `$U_PLUGINS`) : ```php // Appel du hook pour récupérer les items de sous-menu $plugins_menu_items = trigger_change('admin_menubar_plugin_links', array()); $template->assign('PLUGINS_MENU_ITEMS', $plugins_menu_items); ``` ### 2. Modification du template `admin.tpl` Remplacer la section Plugins statique par une section dynamique : ```smarty <dl id="menubar-plugins"> <dt> {if $PLUGINS_MENU_ITEMS} <i class="icon-puzzle"></i> <span>{'Plugins'|@translate}&nbsp;</span> <i class="icon-down-open open-menu"></i> {else} <a href="{$U_PLUGINS}" class="admin-main"> <i class="icon-puzzle"></i> <span>{'Plugins'|@translate}&nbsp;</span> </a> {/if} </dt> {if $PLUGINS_MENU_ITEMS} <dd> <ul> <li><a href="{$U_PLUGINS}"><i class="icon-list"></i>{'Manage'|@translate}</a></li> {foreach from=$PLUGINS_MENU_ITEMS item=item} <li><a href="{$item.URL}"><i class="{$item.ICON|default:'icon-puzzle'}"></i>{$item.NAME}</a></li> {/foreach} </ul> </dd> {/if} </dl> ``` ### 3. Usage par un plugin (exemple : Mosaic) Un plugin peut simplement enregistrer son hook : ```php add_event_handler('admin_menubar_plugin_links', 'Mosaic_menubar_link'); function Mosaic_menubar_link($items) { $items[] = array( 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', ); return $items; } ``` --- ## Avantages de cette approche | Aspect | Détail | |--------|--------| | **Propreté** | Aucune manipulation DOM — rendu serveur, pas de JavaScript fragile | | **Rétrocompatibilité** | Sans plugin, la section reste un simple lien (comportement inchangé) | | **Extensibilité** | Chaque plugin ajoute sa ligne indépendamment, sans collision | | **Maintenabilité** | Modification centralisée dans `admin.php` et `admin.tpl` | | **Thèmes** | Compatible avec tous les thèmes admin (pas limité à `default`) | | **Flexibilité** | Support futur du flag `$ACTIVE_MENU` pour highlighter la section | --- ## Pas de breaking change - **Par défaut** : Sans plugin, `$PLUGINS_MENU_ITEMS` est vide → comportement identique à aujourd'hui - **Avec plugin** : Le hook ajoute les entrées et active le sous-menu → expérience utilisateur améliorée - **Thèmes personnalisés** : Les thèmes qui n'implémentent pas le template modifié conservent leur comportement actuel --- ## Implémentation estimée | Élément | Effort | |---------|--------| | Ajout du hook dans `admin.php` | ~5 min | | Modification du template `admin.tpl` | ~10 min | | Gestion `$ACTIVE_MENU` (optionnel) | ~15 min | | **Total** | ~30 min (très chirurgical) | --- ## Cas d'usage prioritaire 1. **Mosaic** — Afficher un lien vers l'admin du plugin directement dans le menubar 2. **Plugins layout** — Intégrer leurs panels dans le menubar pour meilleur UX 3. **Plugins d'administration** — centralAdmin, etc., peuvent exposer leurs menus facilement --- ## Suggestions de priorité - **Priorité** : Moyenne (amélioration UX, pas critique mais très désirée) - **Complexité** : Très basse (~30 minutes de dev) - **Risque** : Nul (modification chirurgicale, rétrocompatible) --- ## Points de discussion (optionnels) - Faut-il un second hook `admin_menubar_before_plugins` pour ajouter des sections **avant** Plugins ? - Faut-il supporter un flag `active` sur chaque item pour highlighter automatiquement ? - Faut-il exposer un helper `get_plugin_menu_item()` pour normaliser la structure ? --- ## Conclusion L'ajout du hook `admin_menubar_plugin_links` est une **demande légitime** pour améliorer l'intégration des plugins dans l'interface admin. C'est une modification **mineure et pérenne** qui résout un problème de design UI sans impacter les performances ou la compatibilité. **Vote recommandé** : ⭐ Accepter (30 min d'implémentation, gain UX immédiat pour plugins et utilisateurs) <!-- github-comment-id:3993331652 -->

adam commented 2026-10-05 01:09:30 +02:00

Author

Owner

Copy link

Copy source

Hook admin_menubar_plugin_links — Plugin Developer Guide

Piwigo 14.0+

Overview

The admin_menubar_plugin_links hook allows your plugin to add entries to the Piwigo admin interface's sidebar menubar. This provides your users with direct access to your plugin's admin panel without complex navigation.

Before / After

Before : Users navigate to Admin > Plugins > List, then click on your plugin.

After : A single click in the sidebar menubar accesses your admin panel directly.

---

Registering the Hook

Basic Syntax

In your plugin's main.inc.php file, register the hook:

<?php
// plugins/my_plugin/main.inc.php

defined('PHPWG_ROOT_PATH') or die('Hacking attempt!');

add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar_register');

function my_plugin_menubar_register($items)
{
  $items[] = array(
    'NAME' => 'My Plugin',
    'URL'  => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-cog',
  );

  return $items;
}
?>

Important Notes

1. The hook is called on every admin page load — ensure your callback is performant
2. Always return the $items array — even if you only add entries
3. Plugin order is not guaranteed — administrators can reorganize via Admin > Plugins > Menubar

---

Menu Item Structure

Each element in the $items array must follow this structure:

Required Parameters

Key	Type	Description
NAME	string	Display name in the menubar. Keep it short (< 30 characters for readability)
URL	string	URL to your plugin's admin panel

Optional Parameters

Key	Type	Description
ICON	string	Font Awesome icon class (e.g., icon-cog, icon-th, icon-sliders). Default: icon-puzzle
ID	string	Unique identifier for order and visibility management. Auto-generated if omitted, but recommended for stability

Complete Example

function my_plugin_menubar_register($items)
{
  $items[] = array(
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
    'ID'   => 'mosaic_plugin',
  );

  return $items;
}

---

Best Practices

1. Idempotence: Check if Already Registered

If your plugin is called multiple times (rare but possible), verify you don't add duplicate entries:

function my_plugin_menubar_register($items)
{
  // Check if our entry already exists
  foreach ($items as $item)
  {
    if (isset($item['ID']) && $item['ID'] === 'my_plugin')
    {
      return $items;  // Already registered
    }
  }

  $items[] = array(
    'ID'   => 'my_plugin',
    'NAME' => 'My Plugin',
    'URL'  => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-cog',
  );

  return $items;
}

2. Use get_admin_plugin_menu_link()

Always use this function to generate your admin panel URL:

'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'),

This ensures compatibility with complex file paths and URL rewrites.

3. Follow ID Naming Conventions

Use a prefixed format to avoid collisions:

'ID' => 'my_plugin',               // Good
'ID' => 'mosaic_images_layout',    // Good (descriptive)
'ID' => 'foo_bar_baz_123',         // Valid but verbose

IDs must be alphanumeric + underscore: [a-zA-Z0-9_]

4. Choose an Appropriate Icon

Some popular icon suggestions:

'ICON' => 'icon-cog',              // Settings / configuration
'ICON' => 'icon-th',               // Gallery / mosaic
'ICON' => 'icon-sliders',          // Adjustments / filters
'ICON' => 'icon-palette',          // Colors / theme
'ICON' => 'icon-file-image',       // Images
'ICON' => 'icon-users',            // Users
'ICON' => 'icon-lock',             // Security / permissions
'ICON' => 'icon-puzzle',           // Default (if no icon fits)

Check the full Font Awesome icon list for Piwigo compatibility.

Accessing the Complete Fontello Icon List

Piwigo includes a customized Fontello icon font. To explore all available icons:

Option 1: Consult the demo.html File (Local)

1. Navigate to: admin/themes/default/fontello/demo.html
2. Open the file in your web browser
3. You'll see the complete icon gallery with their names (e.g., icon-cog, icon-th, etc.)

Option 2: Inspect the CSS File

Icon definitions are located in:

admin/themes/default/fontello/css/fontello.css

You'll find lines like:

.icon-cog:before { content: '\f013'; } /* '' */
.icon-th:before { content: '\f009'; } /* '' */
.icon-lock:before { content: '\f023'; } /* '' */

Each class corresponds to a Unicode character rendered by the Fontello font.

Option 3: Use Browser DevTools (F12)

1. Open any Piwigo admin page
2. Press F12 to open devtools
3. Use the inspector to target an element with an icon (e.g., <i class="icon-cog">)
4. In the Styles tab, you'll see the icon class and rendered character
5. Consult the CSS source file to see all available icons

Example: Adding a Custom Icon

If you want a specific icon (e.g., users, lock, images, etc.):

1. Consult demo.html to list all available icons
2. Copy the exact name (e.g., icon-users, icon-lock, icon-file-image)
3. Use it in your hook:

$items[] = array(
  'NAME' => 'User Management',
  'URL'  => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'),
  'ICON' => 'icon-users',  // Users icon
  'ID'   => 'my_plugin_users',
);

5. Avoid Expensive Operations

The hook fires on every admin page load. Avoid:

// ❌ BAD: Database query on every page load
function my_plugin_menubar_register($items)
{
  $count = pwg_query("SELECT COUNT(*) FROM ..."); // SLOW
  $items[] = array('NAME' => "My Plugin ($count)", ...);
  return $items;
}

// ✅ GOOD: Static information only
function my_plugin_menubar_register($items)
{
  $items[] = array('NAME' => 'My Plugin', ...);
  return $items;
}

---

Preference Management (Admin > Plugins > Menubar)

Piwigo administrators can manage your entries via Admin > Plugins > Menubar:

• Reorder : Drag-and-drop to change order
• Hide : Uncheck to hide an entry without removing it
• Add separators : Group entries visually

Your plugin doesn't need to do anything — these preferences are handled automatically.

---

Real-World Example: Mosaic Plugin

<?php
// plugins/mosaic/main.inc.php

defined('PHPWG_ROOT_PATH') or die('Hacking attempt!');

// ... plugin code ...

add_event_handler('admin_menubar_plugin_links', 'mosaic_menubar_register');

/**
 * Registers the Mosaic entry in the admin menubar
 */
function mosaic_menubar_register($items)
{
  $items[] = array(
    'ID'   => 'mosaic_plugin',
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
  );

  return $items;
}
?>

---

Troubleshooting

My entry doesn't appear

1. Verify your plugin is enabled — the hook only fires for active plugins
2. Check syntax — the callback must return the $items array
3. Verify admin panel exists — admin.php must exist in your plugin folder
4. Check permissions — only administrators see the menubar

My icon doesn't display correctly

• Ensure the icon class is correct (e.g., icon-cog, not cog)
• Icons are from Font Awesome (Piwigo-compatible)
• When in doubt, omit ICON to use the default

Entry order keeps changing

This is normal! Administrators can reorganize entries via the management panel. For initial ordering, use consistent IDs.

---

Typical Use Cases

Gallery Layout Plugin

add_event_handler('admin_menubar_plugin_links', 'my_gallery_menubar');

function my_gallery_menubar($items)
{
  $items[] = array(
    'NAME' => 'My Gallery Layout',
    'URL'  => get_admin_plugin_menu_link(MY_GALLERY_PATH . 'admin.php'),
    'ICON' => 'icon-th-large',
    'ID'   => 'my_gallery_layout',
  );
  return $items;
}

Security Plugin

add_event_handler('admin_menubar_plugin_links', 'security_plugin_menubar');

function security_plugin_menubar($items)
{
  $items[] = array(
    'NAME' => 'Security',
    'URL'  => get_admin_plugin_menu_link(SECURITY_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-lock',
    'ID'   => 'security_admin',
  );
  return $items;
}

Plugin with Multiple Sections (Multiple Entries)

add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar');

function my_plugin_menubar($items)
{
  $base_url = get_admin_plugin_menu_link(MY_PLUGIN_PATH);

  // Check that entries don't already exist
  $ids = array();
  foreach ($items as $item) {
    if (isset($item['ID'])) {
      $ids[] = $item['ID'];
    }
  }

  // Add main entries
  if (!in_array('my_plugin_settings', $ids)) {
    $items[] = array(
      'ID'   => 'my_plugin_settings',
      'NAME' => 'Settings',
      'URL'  => $base_url . 'admin_settings.php',
      'ICON' => 'icon-cog',
    );
  }

  if (!in_array('my_plugin_logs', $ids)) {
    $items[] = array(
      'ID'   => 'my_plugin_logs',
      'NAME' => 'Logs',
      'URL'  => $base_url . 'admin_logs.php',
      'ICON' => 'icon-list',
    );
  }

  return $items;
}

---

Resources

• Piwigo Hooks : https://piwigo.org/en/doc/doku.php?id=dev:plugins:events
• Font Awesome Icons : https://fontawesome.io/icons/
• Piwigo Plugin Development : https://piwigo.org/en/doc/doku.php?id=dev:plugins

---

Change Log

Version	Date	Change
1.0	2026-03-04	Initial documentation

---

Support

If you have questions about this hook, consult:

1. Source code: admin/include/add_core_tabs.inc.php (tab registration)
2. Processing file: admin/plugins_menubar.php (preference management)
3. Piwigo forums/issues

---

Author : Gotcha
License : Same as Piwigo (GPLv2)

# Hook admin_menubar_plugin_links — Plugin Developer Guide **Piwigo 14.0+** ## Overview The `admin_menubar_plugin_links` hook allows your plugin to add entries to the Piwigo admin interface's sidebar menubar. This provides your users with direct access to your plugin's admin panel without complex navigation. ### Before / After **Before** : Users navigate to Admin > Plugins > List, then click on your plugin. **After** : A single click in the sidebar menubar accesses your admin panel directly. --- ## Registering the Hook ### Basic Syntax In your plugin's `main.inc.php` file, register the hook: ```php <?php // plugins/my_plugin/main.inc.php defined('PHPWG_ROOT_PATH') or die('Hacking attempt!'); add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar_register'); function my_plugin_menubar_register($items) { $items[] = array( 'NAME' => 'My Plugin', 'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-cog', ); return $items; } ?> ``` ### Important Notes 1. **The hook is called on every admin page load** — ensure your callback is performant 2. **Always return the `$items` array** — even if you only add entries 3. **Plugin order is not guaranteed** — administrators can reorganize via Admin > Plugins > Menubar --- ## Menu Item Structure Each element in the `$items` array must follow this structure: ### Required Parameters | Key | Type | Description | |-----|------|-------------| | `NAME` | string | Display name in the menubar. Keep it short (< 30 characters for readability) | | `URL` | string | URL to your plugin's admin panel | ### Optional Parameters | Key | Type | Description | |-----|------|-------------| | `ICON` | string | Font Awesome icon class (e.g., `icon-cog`, `icon-th`, `icon-sliders`). Default: `icon-puzzle` | | `ID` | string | Unique identifier for order and visibility management. Auto-generated if omitted, but recommended for stability | ### Complete Example ```php function my_plugin_menubar_register($items) { $items[] = array( 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', 'ID' => 'mosaic_plugin', ); return $items; } ``` --- ## Best Practices ### 1. Idempotence: Check if Already Registered If your plugin is called multiple times (rare but possible), verify you don't add duplicate entries: ```php function my_plugin_menubar_register($items) { // Check if our entry already exists foreach ($items as $item) { if (isset($item['ID']) && $item['ID'] === 'my_plugin') { return $items; // Already registered } } $items[] = array( 'ID' => 'my_plugin', 'NAME' => 'My Plugin', 'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-cog', ); return $items; } ``` ### 2. Use `get_admin_plugin_menu_link()` Always use this function to generate your admin panel URL: ```php 'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'), ``` This ensures compatibility with complex file paths and URL rewrites. ### 3. Follow ID Naming Conventions Use a prefixed format to avoid collisions: ```php 'ID' => 'my_plugin', // Good 'ID' => 'mosaic_images_layout', // Good (descriptive) 'ID' => 'foo_bar_baz_123', // Valid but verbose ``` IDs must be alphanumeric + underscore: `[a-zA-Z0-9_]` ### 4. Choose an Appropriate Icon Some popular icon suggestions: ```php 'ICON' => 'icon-cog', // Settings / configuration 'ICON' => 'icon-th', // Gallery / mosaic 'ICON' => 'icon-sliders', // Adjustments / filters 'ICON' => 'icon-palette', // Colors / theme 'ICON' => 'icon-file-image', // Images 'ICON' => 'icon-users', // Users 'ICON' => 'icon-lock', // Security / permissions 'ICON' => 'icon-puzzle', // Default (if no icon fits) ``` Check the full Font Awesome icon list for Piwigo compatibility. ### Accessing the Complete Fontello Icon List Piwigo includes a **customized Fontello icon font**. To explore all available icons: #### Option 1: Consult the demo.html File (Local) 1. Navigate to: `admin/themes/default/fontello/demo.html` 2. Open the file in your web browser 3. You'll see the complete icon gallery with their names (e.g., `icon-cog`, `icon-th`, etc.) #### Option 2: Inspect the CSS File Icon definitions are located in: ``` admin/themes/default/fontello/css/fontello.css ``` You'll find lines like: ```css .icon-cog:before { content: '\f013'; } /* '' */ .icon-th:before { content: '\f009'; } /* '' */ .icon-lock:before { content: '\f023'; } /* '' */ ``` Each class corresponds to a Unicode character rendered by the Fontello font. #### Option 3: Use Browser DevTools (F12) 1. Open any Piwigo admin page 2. Press **F12** to open devtools 3. Use the inspector to target an element with an icon (e.g., `<i class="icon-cog">`) 4. In the **Styles** tab, you'll see the icon class and rendered character 5. Consult the CSS source file to see all available icons #### Example: Adding a Custom Icon If you want a specific icon (e.g., users, lock, images, etc.): 1. **Consult `demo.html`** to list all available icons 2. **Copy the exact name** (e.g., `icon-users`, `icon-lock`, `icon-file-image`) 3. **Use it in your hook**: ```php $items[] = array( 'NAME' => 'User Management', 'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-users', // Users icon 'ID' => 'my_plugin_users', ); ``` ### 5. Avoid Expensive Operations The hook fires on every admin page load. Avoid: ```php // ❌ BAD: Database query on every page load function my_plugin_menubar_register($items) { $count = pwg_query("SELECT COUNT(*) FROM ..."); // SLOW $items[] = array('NAME' => "My Plugin ($count)", ...); return $items; } // ✅ GOOD: Static information only function my_plugin_menubar_register($items) { $items[] = array('NAME' => 'My Plugin', ...); return $items; } ``` --- ## Preference Management (Admin > Plugins > Menubar) Piwigo administrators can manage your entries via **Admin > Plugins > Menubar**: - **Reorder** : Drag-and-drop to change order - **Hide** : Uncheck to hide an entry without removing it - **Add separators** : Group entries visually Your plugin doesn't need to do anything — these preferences are handled automatically. --- ## Real-World Example: Mosaic Plugin ```php <?php // plugins/mosaic/main.inc.php defined('PHPWG_ROOT_PATH') or die('Hacking attempt!'); // ... plugin code ... add_event_handler('admin_menubar_plugin_links', 'mosaic_menubar_register'); /** * Registers the Mosaic entry in the admin menubar */ function mosaic_menubar_register($items) { $items[] = array( 'ID' => 'mosaic_plugin', 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', ); return $items; } ?> ``` --- ## Troubleshooting ### My entry doesn't appear 1. **Verify your plugin is enabled** — the hook only fires for active plugins 2. **Check syntax** — the callback must return the `$items` array 3. **Verify admin panel exists** — `admin.php` must exist in your plugin folder 4. **Check permissions** — only administrators see the menubar ### My icon doesn't display correctly - Ensure the icon class is correct (e.g., `icon-cog`, not `cog`) - Icons are from Font Awesome (Piwigo-compatible) - When in doubt, omit `ICON` to use the default ### Entry order keeps changing This is normal! Administrators can reorganize entries via the management panel. For initial ordering, use consistent IDs. --- ## Typical Use Cases ### Gallery Layout Plugin ```php add_event_handler('admin_menubar_plugin_links', 'my_gallery_menubar'); function my_gallery_menubar($items) { $items[] = array( 'NAME' => 'My Gallery Layout', 'URL' => get_admin_plugin_menu_link(MY_GALLERY_PATH . 'admin.php'), 'ICON' => 'icon-th-large', 'ID' => 'my_gallery_layout', ); return $items; } ``` ### Security Plugin ```php add_event_handler('admin_menubar_plugin_links', 'security_plugin_menubar'); function security_plugin_menubar($items) { $items[] = array( 'NAME' => 'Security', 'URL' => get_admin_plugin_menu_link(SECURITY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-lock', 'ID' => 'security_admin', ); return $items; } ``` ### Plugin with Multiple Sections (Multiple Entries) ```php add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar'); function my_plugin_menubar($items) { $base_url = get_admin_plugin_menu_link(MY_PLUGIN_PATH); // Check that entries don't already exist $ids = array(); foreach ($items as $item) { if (isset($item['ID'])) { $ids[] = $item['ID']; } } // Add main entries if (!in_array('my_plugin_settings', $ids)) { $items[] = array( 'ID' => 'my_plugin_settings', 'NAME' => 'Settings', 'URL' => $base_url . 'admin_settings.php', 'ICON' => 'icon-cog', ); } if (!in_array('my_plugin_logs', $ids)) { $items[] = array( 'ID' => 'my_plugin_logs', 'NAME' => 'Logs', 'URL' => $base_url . 'admin_logs.php', 'ICON' => 'icon-list', ); } return $items; } ``` --- ## Resources - **Piwigo Hooks** : https://piwigo.org/en/doc/doku.php?id=dev:plugins:events - **Font Awesome Icons** : https://fontawesome.io/icons/ - **Piwigo Plugin Development** : https://piwigo.org/en/doc/doku.php?id=dev:plugins --- ## Change Log | Version | Date | Change | |---------|------|--------| | 1.0 | 2026-03-04 | Initial documentation | --- ## Support If you have questions about this hook, consult: 1. Source code: `admin/include/add_core_tabs.inc.php` (tab registration) 2. Processing file: `admin/plugins_menubar.php` (preference management) 3. Piwigo forums/issues --- **Author** : Gotcha **License** : Same as Piwigo (GPLv2) <!-- github-comment-id:4016313006 -->

adam commented 2026-10-05 01:09:30 +02:00

Author

Owner

Copy link

Copy source

Hook admin_menubar_plugin_links — Documentation pour les développeurs de plugins

Piwigo 14.0+

Vue d'ensemble

Le hook admin_menubar_plugin_links permet à votre plugin d'ajouter des entrées dans le menubar latéral de l'interface d'administration Piwigo. Cela offre à vos utilisateurs un accès direct au panneau d'administration de votre plugin sans navigation complexe.

Avant / Après

Avant : Les utilisateurs doivent aller sur Admin > Plugins > Liste, puis cliquer sur votre plugin.

Après : Un simple clic dans le menubar latéral accède directement à votre panneau.

---

Enregistrement du hook

Syntaxe basique

Dans le fichier main.inc.php de votre plugin, enregistrez le hook :

<?php
// plugins/mon_plugin/main.inc.php

defined('PHPWG_ROOT_PATH') or die('Hacking attempt!');

add_event_handler('admin_menubar_plugin_links', 'mon_plugin_menubar_register');

function mon_plugin_menubar_register($items)
{
  $items[] = array(
    'NAME' => 'Mon Plugin',
    'URL'  => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-cog',
  );

  return $items;
}
?>

Points importants

1. Le hook est appelé à chaque chargement de la page admin — assurez-vous que votre callback est performant
2. Retournez toujours le tableau $items — même si vous n'ajoutez qu'une seule entrée
3. L'ordre d'enregistrement des plugins ne garantit pas l'ordre final — l'administrateur peut réorganiser via Admin > Plugins > Menubar

---

Structure des éléments de menu

Chaque élément du tableau $items doit respecter cette structure :

Paramètres obligatoires

Clé	Type	Description
NAME	string	Nom affiché dans le menubar. Doit être court (< 30 caractères pour une bonne lisibilité)
URL	string	URL du panneau d'administration du plugin

Paramètres optionnels

Clé	Type	Description
ICON	string	Classe d'icône Font Awesome (ex: icon-cog, icon-th, icon-sliders). Défaut : icon-puzzle
ID	string	Identifiant unique pour gérer l'ordre et la visibilité. Auto-généré si absent, mais recommandé pour la stabilité

Exemple complet

function mon_plugin_menubar_register($items)
{
  $items[] = array(
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
    'ID'   => 'mosaic_plugin',
  );

  return $items;
}

---

Bonnes pratiques

1. Idempotence : Vérifier si déjà enregistré

Si votre plugin est appelé plusieurs fois (cas rare mais possible), vérifiez que vous n'ajoutez pas l'entrée en double :

function mon_plugin_menubar_register($items)
{
  // Vérifier que notre entrée n'existe pas déjà
  foreach ($items as $item)
  {
    if (isset($item['ID']) && $item['ID'] === 'mon_plugin')
    {
      return $items;  // Déjà enregistré
    }
  }

  $items[] = array(
    'ID'   => 'mon_plugin',
    'NAME' => 'Mon Plugin',
    'URL'  => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-cog',
  );

  return $items;
}

2. Utiliser get_admin_plugin_menu_link()

Toujours utiliser cette fonction pour générer l'URL de votre panneau admin :

'URL' => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'),

Cela garantit la compatibilité avec les chemins de fichiers compliqués et les URL réécrites.

3. Respecter les conventions de nommage pour les IDs

Utilisez un format préfixé pour éviter les collisions :

'ID' => 'mon_plugin',          // Bon
'ID' => 'mosaic_images_layout', // Bon (descriptif)
'ID' => 'foo_bar_baz_123',      // Valide mais un peu long

Les IDs doivent être alphanumériques + underscore : [a-zA-Z0-9_]

4. Choisir une icône appropriée

Quelques suggestions d'icônes populaires :

'ICON' => 'icon-cog',             // Paramètres / configuration
'ICON' => 'icon-th',              // Galerie / mosaïque
'ICON' => 'icon-sliders',         // Réglages / filtres
'ICON' => 'icon-palette',         // Couleurs / thème
'ICON' => 'icon-file-image',      // Images
'ICON' => 'icon-users',           // Utilisateurs
'ICON' => 'icon-lock',            // Sécurité / permissions
'ICON' => 'icon-puzzle',          // Défaut (si aucune icône appropriée)

Consultez la liste complète des icônes Font Awesome compatibles.

Accéder à la liste complète des icônes Fontello

Piwigo embarque une police d'icônes Fontello customisée. Pour explorer toutes les icônes disponibles :

Option 1 : Consulter le fichier demo.html (local)

1. Navigez vers : admin/themes/default/fontello/demo.html
2. Ouvrez le fichier dans votre navigateur web
3. Vous verrez la galerie complète des icônes avec leurs noms (ex: icon-cog, icon-th, etc.)

Option 2 : Inspecter le fichier CSS

Les définitions des icônes se trouvent dans :

admin/themes/default/fontello/css/fontello.css

Vous y trouverez des lignes comme :

.icon-cog:before { content: '\f013'; } /* '' */
.icon-th:before { content: '\f009'; } /* '' */
.icon-lock:before { content: '\f023'; } /* '' */

Chaque classe correspond à un caractère Unicode spécifique rendu par la police Fontello.

Option 3 : Utiliser les devtools du navigateur (F12)

1. Ouvrez une page d'administration Piwigo
2. Appuyez sur F12 pour ouvrir les devtools
3. Utilisez l'inspecteur pour cibler un élément avec une icône (ex: <i class="icon-cog">)
4. Dans l'onglet Styles, vous verrez la classe d'icône et le caractère rendu
5. Consultez le fichier CSS source pour voir toutes les icônes disponibles

Exemple : Ajouter une icône personnalisée

Si vous voulez une icône spécifique (ex: icônes utilisateur, cadenas, images, etc.) :

1. Consultez demo.html pour lister toutes les icônes disponibles
2. Copiez le nom exact (ex: icon-users, icon-lock, icon-file-image)
3. Utilisez-le dans votre hook :

$items[] = array(
  'NAME' => 'User Management',
  'URL'  => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'),
  'ICON' => 'icon-users',  // Icône utilisateurs
  'ID'   => 'my_plugin_users',
);

5. Éviter les opérations coûteuses

Le hook est déclenché à chaque chargement de page admin. Évitez :

// ❌ MAUVAIS : requête SQL à chaque chargement
function mon_plugin_menubar_register($items)
{
  $count = pwg_query("SELECT COUNT(*) FROM ..."); // LENT
  $items[] = array('NAME' => "Mon Plugin ($count)", ...);
  return $items;
}

// ✅ BON : informations statiques uniquement
function mon_plugin_menubar_register($items)
{
  $items[] = array('NAME' => 'Mon Plugin', ...);
  return $items;
}

---

Gestion des préférences (Admin > Plugins > Menubar)

Les administrateurs Piwigo peuvent gérer vos entrées via Admin > Plugins > Menubar :

• Réordonner : Glisser-déposer pour changer l'ordre
• Masquer : Décocher pour masquer une entrée sans la supprimer
• Ajouter des séparateurs : Grouper les entrées visuellement

Votre plugin n'a rien à faire — ces préférences sont gérées automatiquement.

---

Exemple réel : Plugin Mosaic

<?php
// plugins/mosaic/main.inc.php

defined('PHPWG_ROOT_PATH') or die('Hacking attempt!');

// ... code du plugin ...

add_event_handler('admin_menubar_plugin_links', 'mosaic_menubar_register');

/**
 * Enregistre l'entrée Mosaic dans le menubar admin
 */
function mosaic_menubar_register($items)
{
  $items[] = array(
    'ID'   => 'mosaic_plugin',
    'NAME' => 'Mosaic',
    'URL'  => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'),
    'ICON' => 'icon-th',
  );

  return $items;
}
?>

---

Dépannage

Mon entrée n'apparaît pas

1. Vérifiez que votre plugin est activé — le hook ne se déclenche que pour les plugins actifs
2. Vérifiez la syntaxe — le callback doit retourner le tableau $items
3. Vérifiez que votre panneau d'admin existe — admin.php doit exister dans le dossier du plugin
4. Vérifiez les permissions — seul un administrateur peut voir le menubar

Mon icône n'apparaît pas correctement

• Assurez-vous que la classe d'icône est correcte (ex: icon-cog, pas cog)
• Les icônes proviennent de Font Awesome (compatible Piwigo)
• En cas de doute, omettez ICON pour utiliser le défaut

L'ordre de mes entrées change

C'est normal ! L'administrateur peut réorganiser les entrées via le panneau de gestion. Pour un ordre initial, utilisez des IDs cohérents.

---

Cas d'usage typiques

Plugin de galerie (layout)

add_event_handler('admin_menubar_plugin_links', 'my_gallery_menubar');

function my_gallery_menubar($items)
{
  $items[] = array(
    'NAME' => 'My Gallery Layout',
    'URL'  => get_admin_plugin_menu_link(MY_GALLERY_PATH . 'admin.php'),
    'ICON' => 'icon-th-large',
    'ID'   => 'my_gallery_layout',
  );
  return $items;
}

Plugin de sécurité

add_event_handler('admin_menubar_plugin_links', 'security_plugin_menubar');

function security_plugin_menubar($items)
{
  $items[] = array(
    'NAME' => 'Security',
    'URL'  => get_admin_plugin_menu_link(SECURITY_PLUGIN_PATH . 'admin.php'),
    'ICON' => 'icon-lock',
    'ID'   => 'security_admin',
  );
  return $items;
}

Plugin avec plusieurs sections (ajouter plusieurs entrées)

add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar');

function my_plugin_menubar($items)
{
  $base_url = get_admin_plugin_menu_link(MY_PLUGIN_PATH);

  // Vérifier que les entrées n'existent pas déjà
  $ids = array();
  foreach ($items as $item) {
    if (isset($item['ID'])) {
      $ids[] = $item['ID'];
    }
  }

  // Ajouter les entrées principales
  if (!in_array('my_plugin_settings', $ids)) {
    $items[] = array(
      'ID'   => 'my_plugin_settings',
      'NAME' => 'Settings',
      'URL'  => $base_url . 'admin_settings.php',
      'ICON' => 'icon-cog',
    );
  }

  if (!in_array('my_plugin_logs', $ids)) {
    $items[] = array(
      'ID'   => 'my_plugin_logs',
      'NAME' => 'Logs',
      'URL'  => $base_url . 'admin_logs.php',
      'ICON' => 'icon-list',
    );
  }

  return $items;
}

---

Ressources

• Hooks Piwigo : https://piwigo.org/en/doc/doku.php?id=dev:plugins:events
• Font Awesome Icons : https://fontawesome.io/icons/
• Piwigo Plugin Development : https://piwigo.org/en/doc/doku.php?id=dev:plugins

---

Historique des modifications

Version	Date	Changement
1.0	2026-03-04	Documentation initiale

---

Support

Si vous avez des questions sur ce hook, consultez :

1. Le code source : admin/include/add_core_tabs.inc.php (enregistrement du tab)
2. Le fichier de traitement : admin/plugins_menubar.php (gestion des préférences)
3. Les forums/issues Piwigo

---

Auteur : Gotcha
Licence : Même licence que Piwigo (GPLv2)

# Hook admin_menubar_plugin_links — Documentation pour les développeurs de plugins **Piwigo 14.0+** ## Vue d'ensemble Le hook `admin_menubar_plugin_links` permet à votre plugin d'ajouter des entrées dans le menubar latéral de l'interface d'administration Piwigo. Cela offre à vos utilisateurs un accès direct au panneau d'administration de votre plugin sans navigation complexe. ### Avant / Après **Avant** : Les utilisateurs doivent aller sur Admin > Plugins > Liste, puis cliquer sur votre plugin. **Après** : Un simple clic dans le menubar latéral accède directement à votre panneau. --- ## Enregistrement du hook ### Syntaxe basique Dans le fichier `main.inc.php` de votre plugin, enregistrez le hook : ```php <?php // plugins/mon_plugin/main.inc.php defined('PHPWG_ROOT_PATH') or die('Hacking attempt!'); add_event_handler('admin_menubar_plugin_links', 'mon_plugin_menubar_register'); function mon_plugin_menubar_register($items) { $items[] = array( 'NAME' => 'Mon Plugin', 'URL' => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-cog', ); return $items; } ?> ``` ### Points importants 1. **Le hook est appelé à chaque chargement de la page admin** — assurez-vous que votre callback est performant 2. **Retournez toujours le tableau `$items`** — même si vous n'ajoutez qu'une seule entrée 3. **L'ordre d'enregistrement des plugins ne garantit pas l'ordre final** — l'administrateur peut réorganiser via Admin > Plugins > Menubar --- ## Structure des éléments de menu Chaque élément du tableau `$items` doit respecter cette structure : ### Paramètres obligatoires | Clé | Type | Description | |-----|------|-------------| | `NAME` | string | Nom affiché dans le menubar. Doit être court (< 30 caractères pour une bonne lisibilité) | | `URL` | string | URL du panneau d'administration du plugin | ### Paramètres optionnels | Clé | Type | Description | |-----|------|-------------| | `ICON` | string | Classe d'icône Font Awesome (ex: `icon-cog`, `icon-th`, `icon-sliders`). Défaut : `icon-puzzle` | | `ID` | string | Identifiant unique pour gérer l'ordre et la visibilité. Auto-généré si absent, mais recommandé pour la stabilité | ### Exemple complet ```php function mon_plugin_menubar_register($items) { $items[] = array( 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', 'ID' => 'mosaic_plugin', ); return $items; } ``` --- ## Bonnes pratiques ### 1. Idempotence : Vérifier si déjà enregistré Si votre plugin est appelé plusieurs fois (cas rare mais possible), vérifiez que vous n'ajoutez pas l'entrée en double : ```php function mon_plugin_menubar_register($items) { // Vérifier que notre entrée n'existe pas déjà foreach ($items as $item) { if (isset($item['ID']) && $item['ID'] === 'mon_plugin') { return $items; // Déjà enregistré } } $items[] = array( 'ID' => 'mon_plugin', 'NAME' => 'Mon Plugin', 'URL' => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-cog', ); return $items; } ``` ### 2. Utiliser `get_admin_plugin_menu_link()` Toujours utiliser cette fonction pour générer l'URL de votre panneau admin : ```php 'URL' => get_admin_plugin_menu_link(MON_PLUGIN_PATH . 'admin.php'), ``` Cela garantit la compatibilité avec les chemins de fichiers compliqués et les URL réécrites. ### 3. Respecter les conventions de nommage pour les IDs Utilisez un format préfixé pour éviter les collisions : ```php 'ID' => 'mon_plugin', // Bon 'ID' => 'mosaic_images_layout', // Bon (descriptif) 'ID' => 'foo_bar_baz_123', // Valide mais un peu long ``` Les IDs doivent être alphanumériques + underscore : `[a-zA-Z0-9_]` ### 4. Choisir une icône appropriée Quelques suggestions d'icônes populaires : ```php 'ICON' => 'icon-cog', // Paramètres / configuration 'ICON' => 'icon-th', // Galerie / mosaïque 'ICON' => 'icon-sliders', // Réglages / filtres 'ICON' => 'icon-palette', // Couleurs / thème 'ICON' => 'icon-file-image', // Images 'ICON' => 'icon-users', // Utilisateurs 'ICON' => 'icon-lock', // Sécurité / permissions 'ICON' => 'icon-puzzle', // Défaut (si aucune icône appropriée) ``` Consultez la liste complète des icônes Font Awesome compatibles. ### Accéder à la liste complète des icônes Fontello Piwigo embarque une **police d'icônes Fontello customisée**. Pour explorer toutes les icônes disponibles : #### Option 1 : Consulter le fichier demo.html (local) 1. Navigez vers : `admin/themes/default/fontello/demo.html` 2. Ouvrez le fichier dans votre navigateur web 3. Vous verrez la galerie complète des icônes avec leurs noms (ex: `icon-cog`, `icon-th`, etc.) #### Option 2 : Inspecter le fichier CSS Les définitions des icônes se trouvent dans : ``` admin/themes/default/fontello/css/fontello.css ``` Vous y trouverez des lignes comme : ```css .icon-cog:before { content: '\f013'; } /* '' */ .icon-th:before { content: '\f009'; } /* '' */ .icon-lock:before { content: '\f023'; } /* '' */ ``` Chaque classe correspond à un caractère Unicode spécifique rendu par la police Fontello. #### Option 3 : Utiliser les devtools du navigateur (F12) 1. Ouvrez une page d'administration Piwigo 2. Appuyez sur **F12** pour ouvrir les devtools 3. Utilisez l'inspecteur pour cibler un élément avec une icône (ex: `<i class="icon-cog">`) 4. Dans l'onglet **Styles**, vous verrez la classe d'icône et le caractère rendu 5. Consultez le fichier CSS source pour voir toutes les icônes disponibles #### Exemple : Ajouter une icône personnalisée Si vous voulez une icône spécifique (ex: icônes utilisateur, cadenas, images, etc.) : 1. **Consultez `demo.html`** pour lister toutes les icônes disponibles 2. **Copiez le nom exact** (ex: `icon-users`, `icon-lock`, `icon-file-image`) 3. **Utilisez-le dans votre hook** : ```php $items[] = array( 'NAME' => 'User Management', 'URL' => get_admin_plugin_menu_link(MY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-users', // Icône utilisateurs 'ID' => 'my_plugin_users', ); ``` ### 5. Éviter les opérations coûteuses Le hook est déclenché à chaque chargement de page admin. Évitez : ```php // ❌ MAUVAIS : requête SQL à chaque chargement function mon_plugin_menubar_register($items) { $count = pwg_query("SELECT COUNT(*) FROM ..."); // LENT $items[] = array('NAME' => "Mon Plugin ($count)", ...); return $items; } // ✅ BON : informations statiques uniquement function mon_plugin_menubar_register($items) { $items[] = array('NAME' => 'Mon Plugin', ...); return $items; } ``` --- ## Gestion des préférences (Admin > Plugins > Menubar) Les administrateurs Piwigo peuvent gérer vos entrées via **Admin > Plugins > Menubar** : - **Réordonner** : Glisser-déposer pour changer l'ordre - **Masquer** : Décocher pour masquer une entrée sans la supprimer - **Ajouter des séparateurs** : Grouper les entrées visuellement Votre plugin n'a rien à faire — ces préférences sont gérées automatiquement. --- ## Exemple réel : Plugin Mosaic ```php <?php // plugins/mosaic/main.inc.php defined('PHPWG_ROOT_PATH') or die('Hacking attempt!'); // ... code du plugin ... add_event_handler('admin_menubar_plugin_links', 'mosaic_menubar_register'); /** * Enregistre l'entrée Mosaic dans le menubar admin */ function mosaic_menubar_register($items) { $items[] = array( 'ID' => 'mosaic_plugin', 'NAME' => 'Mosaic', 'URL' => get_admin_plugin_menu_link(MOSAIC_PATH . 'admin.php'), 'ICON' => 'icon-th', ); return $items; } ?> ``` --- ## Dépannage ### Mon entrée n'apparaît pas 1. **Vérifiez que votre plugin est activé** — le hook ne se déclenche que pour les plugins actifs 2. **Vérifiez la syntaxe** — le callback doit retourner le tableau `$items` 3. **Vérifiez que votre panneau d'admin existe** — `admin.php` doit exister dans le dossier du plugin 4. **Vérifiez les permissions** — seul un administrateur peut voir le menubar ### Mon icône n'apparaît pas correctement - Assurez-vous que la classe d'icône est correcte (ex: `icon-cog`, pas `cog`) - Les icônes proviennent de Font Awesome (compatible Piwigo) - En cas de doute, omettez `ICON` pour utiliser le défaut ### L'ordre de mes entrées change C'est normal ! L'administrateur peut réorganiser les entrées via le panneau de gestion. Pour un ordre initial, utilisez des IDs cohérents. --- ## Cas d'usage typiques ### Plugin de galerie (layout) ```php add_event_handler('admin_menubar_plugin_links', 'my_gallery_menubar'); function my_gallery_menubar($items) { $items[] = array( 'NAME' => 'My Gallery Layout', 'URL' => get_admin_plugin_menu_link(MY_GALLERY_PATH . 'admin.php'), 'ICON' => 'icon-th-large', 'ID' => 'my_gallery_layout', ); return $items; } ``` ### Plugin de sécurité ```php add_event_handler('admin_menubar_plugin_links', 'security_plugin_menubar'); function security_plugin_menubar($items) { $items[] = array( 'NAME' => 'Security', 'URL' => get_admin_plugin_menu_link(SECURITY_PLUGIN_PATH . 'admin.php'), 'ICON' => 'icon-lock', 'ID' => 'security_admin', ); return $items; } ``` ### Plugin avec plusieurs sections (ajouter plusieurs entrées) ```php add_event_handler('admin_menubar_plugin_links', 'my_plugin_menubar'); function my_plugin_menubar($items) { $base_url = get_admin_plugin_menu_link(MY_PLUGIN_PATH); // Vérifier que les entrées n'existent pas déjà $ids = array(); foreach ($items as $item) { if (isset($item['ID'])) { $ids[] = $item['ID']; } } // Ajouter les entrées principales if (!in_array('my_plugin_settings', $ids)) { $items[] = array( 'ID' => 'my_plugin_settings', 'NAME' => 'Settings', 'URL' => $base_url . 'admin_settings.php', 'ICON' => 'icon-cog', ); } if (!in_array('my_plugin_logs', $ids)) { $items[] = array( 'ID' => 'my_plugin_logs', 'NAME' => 'Logs', 'URL' => $base_url . 'admin_logs.php', 'ICON' => 'icon-list', ); } return $items; } ``` --- ## Ressources - **Hooks Piwigo** : https://piwigo.org/en/doc/doku.php?id=dev:plugins:events - **Font Awesome Icons** : https://fontawesome.io/icons/ - **Piwigo Plugin Development** : https://piwigo.org/en/doc/doku.php?id=dev:plugins --- ## Historique des modifications | Version | Date | Changement | |---------|------|-----------| | 1.0 | 2026-03-04 | Documentation initiale | --- ## Support Si vous avez des questions sur ce hook, consultez : 1. Le code source : `admin/include/add_core_tabs.inc.php` (enregistrement du tab) 2. Le fichier de traitement : `admin/plugins_menubar.php` (gestion des préférences) 3. Les forums/issues Piwigo --- **Auteur** : Gotcha **Licence** : Même licence que Piwigo (GPLv2) <!-- github-comment-id:4016313226 -->

adam commented 2026-10-05 01:09:31 +02:00

Author

Owner

Copy link

Copy source

No need, see https://fr.piwigo.org/forum/viewtopic.php?pid=244412#p244412

No need, see https://fr.piwigo.org/forum/viewtopic.php?pid=244412#p244412 <!-- github-comment-id:4207072262 -->

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

master

issue-2560-people

translation

16.x

feat/embedding-based-contextual-tagging

issue-2576-search-include-ai-in-search-results

feat/search-ocr-ai

issue-2391-update-menu-design

15.x

detect-container

issue-2386-update-filters-users-activity

issue-2362-add-filters-options-in-admin

issue-2367-imagemagick7

issue-2225-quicksearch-help

14.x

issue-2164-BatchManagerUnitMode-Redesign

13.x

12.x

issue-1657-SVG_Support

issue-1703-historySearchMethod

11.x

2.10

2.9

2.8

2.7

2.5

2.6

2.4

2.3

2.2

2.1

2.0

1.7

1.3

1.6

1.5

1.4

16.4.0

16.3.0

16.2.0

16.1.0

16.0.0

16.0.0RC3

16.0.0RC2

15.7.0

16.0.0RC1

16.0.0beta1

16.0.0beta2

15.6.0

15.5.0

15.4.0

15.3.0

15.2.0

15.1.0

15.0.0

15.0.0beta3

15.0.0beta2

15.0.0beta1

14.5.0

14.4.0

14.3.0

14.2.0

14.1.0

14.0.0

14.0.0RC2

14.0.0RC1

14.0.0beta3

14.0.0beta2

13.8.0

14.0.0beta1

13.7.0

13.6.0

13.5.0

13.4.0

13.3.0

13.2.0

13.1.0

13.0.0

13.0.0RC4

13.0.0RC3

13.0.0RC2

13.0.0RC1

12.3.0

13.0.0beta2

13.0.0beta1

12.2.0

12.1.0

12.0.0

12.0.0RC2

12.0.0RC1

12.0.0beta2

12.0.0beta1

11.5.0

11.4.0

11.3.0

11.2.0

11.1.0

11.0.0

11.0.0beta5

2.11.0beta4

2.11.0beta3

2.11.0beta2

2.11.0beta1

2.10.2

2.10.1

2.10.0

2.10.0RC1

2.10.0beta2

2.10.0beta1

2.9.5

2.9.4

2.9.3

2.9.2

2.9.1

2.9.0

2.9.0RC2

2.9.0RC1

2.9.0beta2

2.8.6

2.8.5

2.8.4

2.9.0beta1

2.8.3

2.8.2

2.8.1

2.8.0

2.8.0RC2

2.8.0RC1

2.7.4

2.7.3

2.6.5

2.5.6

2.5.5

2.6.4

2.7.2

2.7.1

2.7.0

2.7.0RC2

2.7.0RC1

2.7.0beta2

2.6.3

2.7.0beta1

2.6.2

2.5.4

2.6.1

2.6.0

2.6.0RC2

2.6.0RC1

2.6.0beta2

2.5.3

2.5.2

2.6.0beta1

2.5.1

2.5.0

2.5.0RC2

2.4.7

2.5.0RC1

2.4.6

2.5.0beta3

2.5.0beta2

2.5.0beta1

2.4.5

2.4.4

2.4.3

2.4.2

2.4.1

2.4.0

2.3.5

2.4.0RC3

2.3.4

2.4.0RC2

2.4.0RC1

2.3.3

2.4.0beta2

2.4.0beta1

2.3.2

2.3.1

2.3.0

2.3.0RC2

2.3.0RC1

2.2.5

2.3.0beta3

2.2.4

2.3.0beta2

2.2.3

2.2.2

2.3.0beta1

2.2.1

2.2.0

2.2.0RC4

2.2.0RC3

2.2.0RC2

2.1.6

2.2.0RC1

2.1.5

2.1.4

2.1.3

2.1.2

2.1.1

2.1.0

2.0.10

2.1.0RC3

2.1.0RC2

2.1.0RC1

2.0.9

2.0.8

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0.1

2.0.0

2.0.0RC4

1.7.3

2.0.0RC3

2.0.0RC2

2.0.0RC1

1.7.2

1.7.1

1.7.0

1.7.0RC2

1.7.0RC1

1.6.2

1.6.1

1.6.0

1.6.0RC2

1.6.0RC1

1.5.2

1.5.1

1.5.0

1.5.0RC2

1.5.0RC1

1.4.1

1.4.0

1.4.0RC3

1.4.0RC2

1.3.4

1.4.0RC1

1.3.3

1.3.2

1.3.1

1.3.0

1.3.0RC2

1.3.0RC1

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

adam (Adam Wojcieszonek)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: adam/Piwigo#2199