# Добавление персональных кнопок

Для добавления персональных кнопок надо создать класс, наследуемый от pm_Hook_CustomButtons. Этот класс должен быть помещен в папку `plib/hooks/`. Параметр `place` определяет местоположение персональной кнопки в интерфейсе. Полный список поддерживаемых значений параметра `place` можно найти в разделе справочника Constants.

Следующий пример проекта предоставлен Plesk, чтобы проиллюстрировать добавление персональных кнопок расширения в разных местах интерфейса: https://github.com/plesk/ext-custom-buttons.

## Домашняя страница пользователя

Персональные кнопки `PLACE_ADMIN_HOME` и `PLACE_RESELLER_HOME` расположены на домашних страницах администратора и реселлера в разделе Персональные кнопки.

Персональная кнопка `PLACE_CUSTOMER_HOME` расположена на страницах Сайты и домены в правой боковой панели и видна всем пользователям.

## Навигационное меню

Значения `PLACE_ADMIN_NAVIGATION` и `PLACE_RESELLER_NAVIGATION` размещают персональные кнопки в Навигационном меню в интерфейсе администратора и реселлера соответственно.

Персональная кнопка `PLACE_HEADER_NAVIGATION` расположена в заголовке рядом с именем пользователя.

По умолчанию такие кнопки располагаются в разделе меню Ссылки на дополнительные услуги. Параметр `section` с перечисленными ниже значениями позволяет размещать персональные кнопки в различных разделах меню:

- `SECTION_NAV_GENERAL` — верхний раздел

- `SECTION_NAV_HOSTING` — раздел Услуги хостинга

- `SECTION_NAV_PROFILE` — раздел Мой профиль

- `SECTION_NAV_ADDITIONAL` — раздел Ссылки на дополнительные услуги

- `SECTION_NAV_SERVER_MANAGEMENT` — раздел Управление сервером

Параметр `order` используется для указания позиции персональной кнопки в списке внутри раздела («1» — для первой позиции в списке и так далее). Если этот параметр не указан, персональная кнопка будет добавлена в конец списка.

Примечание

Параметр `order` надо использовать с большой осторожностью, только для группировки связанных элементов.

## Инструменты и настройки

Значения `PLACE_ADMIN_TOOLS_AND_SETTINGS` и `PLACE_RESELLER_TOOLS_AND_SETTINGS` используются для добавления персональных кнопок на страницу Инструменты и настройки в интерфейсе администратора и на страницу Инструменты и утилиты в интерфейсе реселлера.

По умолчанию такие кнопки располагаются в разделе Ссылки на дополнительные услуги соответствующей страницы. Параметр `section` позволяет задать раздел. Для администратора:

- `SECTION_ADMIN_TOOLS_MAIL` — раздел Почта

- `SECTION_ADMIN_TOOLS_PLESK` — раздел Plesk

- `SECTION_ADMIN_TOOLS_GENERAL` — раздел Общие настройки

- `SECTION_ADMIN_TOOLS_SECURITY` — раздел Безопасность

- `SECTION_ADMIN_TOOLS_APPEARANCE` — раздел Интерфейс Plesk

- `SECTION_ADMIN_TOOLS_STATISTICS` — раздел Statistics

- `SECTION_ADMIN_TOOLS_APPS_AND_DBS` — раздел Приложения и базы данных

- `SECTION_ADMIN_TOOLS_EXTERNAL_SERVICES` — раздел Внешние услуги

- `SECTION_ADMIN_TOOLS_SERVER_MANAGEMENT` — раздел Управление сервером

- `SECTION_ADMIN_TOOLS_ADDITIONAL_SERVICES` — раздел Дополнительные услуги

- `SECTION_ADMIN_TOOLS_TOOLS_AND_RESOURCES` — раздел Инструменты и ресурсы

- `SECTION_ADMIN_TOOLS_TROUBLESHOOTING_BUTTONS` — раздел Поддержка и устранение неисправностей

Для реселлера:

- `SECTION_RESELLER_TOOLS_SERVICES` — раздел Услуги

- `SECTION_RESELLER_TOOLS_RESOURCES` — раздел Ресурсы

- `SECTION_RESELLER_TOOLS_PLESK_MANAGEMENT` — раздел Управление Plesk

- `SECTION_RESELLER_TOOLS_ADDITIONAL_SERVICES` — раздел Дополнительные услуги

Параметр `order` используется для указания позиции персональной кнопки в списке внутри раздела («1» — для первой позиции в списке и так далее). Если этот параметр не указан, персональная кнопка будет добавлена в конец списка.

Примечание

Параметр `order` надо использовать с большой осторожностью, только для группировки связанных элементов.

## Правая панель

- `PLACE_DOMAIN` — верхний раздел

- `PLACE_CUSTOMER_HOME` — раздел Дополнительные услуги

## Другие местоположения

- `PLACE_COMMON` — помещается в несколько мест одновременно: раздел Ссылки на дополнительные услуги в Навигационном меню, верхний раздел и раздел Дополнительные услуги в правой панели.

- `PLACE_HOSTING_PANEL_TABS` — помещается на дополнительную вкладку на странице подписки, а также отображается как элемент Навигационного меню в интерфейсе клиента.

- `PLACE_TOOLBAR` — добавляется как новая кнопка над всеми списками.

- `PLACE_DOMAIN_PROPERTIES` — отображается как дополнительная кнопка на вкладке Сайты и домены (в режиме Активный список). Параметр `additionalComments` содержит дополнительную информацию, поясняющую назначение кнопки. Может содержать либо однострочные данные (строку), либо многострочные (массив).

- `PLACE_LIST_ACTIONS` — отображается как дополнительная кнопка в других списках в режиме Активный список.

- `PLACE_HOSTING_PANEL_NAVIGATION` — отображается как дополнительный пункт Навигационного меню в интерфейсе администратора в режиме Power User.

## Параметры

Параметр | Значение | Описание
--- | --- | ---
`place` | константа, массив констант | Указывает местоположение кнопки в интерфейсе, например, `PLACE_COMMON`
`section` | константа | Там, где это применимо, указывает часть местоположения в интерфейсе, указанного параметром `place`, например, `SECTION_NAV_GENERAL`
`order` | целое число > 0 | Позиция кнопки в списке элементов
`title` | текст | Текст надписи на кнопке
`description` | текст | Текст подсказки к кнопке или текст описания, дополняющего надпись на кнопке
`icon` | URL | Расположение графического файла значка кнопки (PNG, 32 x 32 пикс, 64 x 64 пикс, 128 x 128 пикс). При этом значки для динамического списка должны соответствовать следующим требованиям: 16 x 16 пикс монохромное (черно-белое) изображение формат SVG
`link` | URL | Место перенаправления по кнопке
`newWindow` | логическое значение | Открывать ли новое окно при перенаправлении
`contextParams` | логическое значение используется для `PLACE_DOMAIN` и `PLACE_DOMAIN_PROPERTIES` | Надо ли отправлять контекстно-зависимые параметры: dom_id — ID подписки, site_id — ID домена или alias_id — ID псевдонима домена
`visibility` | обратный вызов, возвращающий логическое значение | Метод обратного вызова. Определяет, надо ли отображать кнопку. Пример 1, пример 2
`additionalComments` | текст обратного вызова, используется для `PLACE_DOMAIN_PROPERTIES` | Дополнительная информация Пример

## Пример

Следующие примеры показывают, как добавить несколько персональных кнопок. Используемый метод:

- getButtons()

Используйте следующий код:

    class Modules_CustomButtons_CustomButtons extends pm_Hook_CustomButtons
    {

        public function getButtons()
        {
            return [[
                'place' => self::PLACE_DOMAIN,
                'title' => 'Domain Button',
                'description' => 'Description for domain button',
                'icon' => pm_Context::getBaseUrl() . 'images/icon.png',
                'link' => pm_Context::getBaseUrl() . 'index.php/index/index',
            ], [
                'place' => [
                    self::PLACE_HOSTING_PANEL_NAVIGATION,
                    self::PLACE_ADMIN_TOOLS_AND_SETTINGS,
                    self::PLACE_RESELLER_TOOLS_AND_SETTINGS,
                ],
                'title' => 'Multi Place Button',
                'description' => 'Description for multi place button',
                'link' => 'https://plesk.com/',
                'newWindow' => true,
            ]];
        }

    }

    class Modules_CustomButtons_CustomButtons extends pm_Hook_CustomButtons
    {
        public function getButtons()
        {
            return [[
                'place' => self::PLACE_ADMIN_TOOLS_AND_SETTINGS,
                'section' => 'toolsAndResourcesButtons',
                'order' => 1,
                'title' => 'My Button 1',
                'description' => 'Description for my button 1',
                'link' => pm_Context::getActionUrl('index', 'another'),
            ], [
                'place' => self::PLACE_ADMIN_TOOLS_AND_SETTINGS,
                'section' => 'generalButtons',
                'order' => 4,
                'title' => 'My Button 2',
                'description' => 'Description for my button 2',
                'link' => pm_Context::getActionUrl('index', 'another'),
            ]];
        }
    }

## Комментарии

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

# Кнопки для администратора не должны отображаться на страницах интерфейса других пользователей

Удостоверьтесь в том, что персональные кнопки, используемые для доступа к функциям, предназначенным только для администратора, не отображаются на экранах Plesk, доступных другим пользователям, таким как реселлеры и клиенты. В следующих местах не должно содержаться функций, доступных только администратору:

- Навигационное меню слева

  Примечание

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

- Домашние страницы реселлеров и клиентов

- Обзор домена

- Страница Инструменты и утилиты в панели реселлера

- Правая боковая панель на странице Сайты и домены

# Кнопки для клиентов и реселлеров должны отображаться везде, где это необходимо

Некоторые функции предполагают доступ из разных мест интерфейса. Проверьте, что соответствующие персональные кнопки доступны во всех необходимых местах для всех типов пользователей.

# Используйте свойство `visibility`, чтобы скрыть функции, недоступные для доменов без хостинга и псевдонимов доменов

Домены без хостинга и псевдонимы доменов могут содержать или не содержать персональные кнопки в разделе Обзор домена (`PLACE_DOMAIN_PROPERTIES`). Чтобы регулировать это поведение, используйте свойство visibility, которое позволяет скрывать или показывать персональные кнопки, когда это необходимо.

# Используйте свойство `description`

Добавление описаний к персональным кнопкам расширения поможет пользователям легко и быстро освоить работу с расширением. Не пренебрегайте этим полезным инструментом.

# Удостоверьтесь в поддержке разных цветовых схем интерфейса

Интерфейс Plesk поддерживает множество разнообразных цветовых схем, включая светлые и темные схемы, и это может определенным образом повлиять на разработку интерфейса расширения. Чтобы проверить, что ваше расширение поддерживает эти схемы, установите бесплатное расширение Skins and Color Schemes.

# Доступность в режиме Power User

Удостоверьтесь в том, что необходимые персональные кнопки доступны, когда включен режим интерфейса Power User. Например, кнопка, расположенная в разделе `PLACE_HOSTING_PANEL_NAVIGATION` видна только в режиме Power User View в Навигационном меню.