Меню

Elgg содержит вспомогательный код для построения меню по всему сайту.

Каждое отдельное меню требует имени, как и каждый отдельный пункт меню. Они необходимы для обеспечения лёгкого переопределения и манипулирования, а также для предоставления событий для темизации.

Базовое использование

Базовые функции могут быть достигнуты с помощью этих двух функций:

• elgg_register_menu_item() для добавления элемента в меню

• elgg_unregister_menu_item() для удаления элемента из меню

Обычно вы хотите вызывать их из функции init вашего плагина.

Примеры

// 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');

Меню администратора

Вы также можете зарегистрировать элементы меню page в меню бэкэнда администратора. При регистрации для меню администратора вы можете установить контекст элементов меню в admin, чтобы элементы меню отображались только в контексте admin. Есть 3 секции по умолчанию для добавления элементов вашего меню.

• administer для ежедневных задач, управления пользователями и других действий

• configure для настроек, конфигурации и утилит, которые настраивают что-либо

• information для статистики, обзора информации или статуса

Расширенное использование

Заголовки

По соображениям доступности каждое меню получит aria-label, который по умолчанию равен имени меню, но может быть переведён, убедившись, что языковой ключ menu:<menu name>:header доступен.

Также возможно отображать заголовки секций меню, установив show_section_headers в true в elgg_view_menu()

echo elgg_view_menu('my_menu', [
        'show_section_headers' => true,
]);

Заголовки имеют магический языковой ключ menu:<menu name>:header:<section name>, чтобы можно было перевести заголовки.

События

Вы можете получить больше контроля над меню, используя события и публичные методы, предоставляемые классом ElggMenuItem.

Есть три события, которые можно использовать для изменения меню:

• 'parameters', 'menu:<menu name>' для добавления или изменения параметров, используемых для построения меню (например, сортировка)

• 'register', 'menu:<menu name>' для добавления или изменения элементов (особенно в динамических меню)

• 'prepare', 'menu:<menu name>' для изменения структуры меню перед его отображением

При регистрации обработчика событий замените часть <menu name> на внутреннее имя меню.

Третий параметр, передаваемый в обработчик меню, содержит все элементы меню, которые были зарегистрированы до сих пор ядром Elgg и другими включёнными плагинами. В обработчике мы можем перебирать элементы меню и использовать методы класса для взаимодействия со свойствами элемента меню.

В некоторых случаях существует более детализированная версия событий меню register и prepare с menu:<menu name>:<type>:<subtype>, это применяется, когда меню получает \ElggEntity в $params['entity'] или \ElggAnnotation в $params['annotation'] или \ElggRelationship в $params['relationship'].

Примеры

Пример 1: Изменить URL для элемента меню с названием «albums» в меню 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;
}

Пример 2: Изменить меню entity для объектов ElggBlog

• Удалить иконку миниатюры

• Изменить текст «Редактировать» на пользовательскую иконку

/**
 * 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;
}

Создание нового меню

Elgg предоставляет несколько различных меню по умолчанию. Иногда вам могут понадобиться элементы меню, которые не вписываются ни в одно из существующих меню. Если это так, вы можете создать собственное меню с помощью функции elgg_view_menu(). Вы должны вызывать функцию из представления, где вы хотите, чтобы меню отображалось.

Пример: Отобразить меню с названием «my_menu», которое отображает свои элементы меню в алфавитном порядке:

// in a resource view
echo elgg_view_menu('my_menu', array('sort_by' => 'text'));

Теперь вы можете добавлять новые элементы в меню следующим образом:

// 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'),
));

Кроме того, теперь можно изменять меню с помощью событий 'register', 'menu:my_menu' и 'prepare', 'menu:my_menu'.

Выпадающие дочерние меню

Дочерние меню можно настроить с помощью опции фабрики child_menu на родительском элементе.

Массив опций child_menu принимает параметр display, который можно использовать для настройки открытия дочернего меню как dropdown или отображения через toggle. Все остальные пары ключ-значение будут переданы как атрибуты элементу 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',
        ],
));

Темизация

Имя меню, имена секций и имена элементов встраиваются в HTML как классы CSS (нормализованы для содержания только дефисов, а не подчёркиваний или двоеточий). Это немного увеличивает размер разметки, но предоставляет темизаторам высокую степень контроля и гибкости при стилизации сайта.

Пример: Следующее будет выводом меню foo с секциями alt и default, содержащими элементы baz и 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>

Переключение элементов меню

Есть ситуации, когда вы хотите переключать элементы меню, которые являются действиями, противоположными друг другу, и сделать их через ajax. Например, нравится/не нравится, друг/не друг, бан/разбан и т.д. Elgg имеет встроенную поддержку для таких действий. При регистрации элемента меню вы можете указать имя элемента меню (в том же меню), который должен переключаться. Будет сделан вызов ajax с использованием href элемента меню.

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'),
]);

Примечание

Элементы меню переключаются оптимистично. Это означает, что элементы меню переключаются до завершения действий. Если действия не удаются, элементы меню будут переключены обратно.

JavaScript

Часто элементы меню зависят от JavaScript. Вы можете привязать события на стороне клиента к элементам меню, поместив ваш JavaScript в модуль и определив требование во время регистрации.

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.mjs
import 'jquery';

$(document).on('click', '.hide-on-click', function(e) {
    e.preventDefault();
    $(this).hide();
});