Integrate with Plesk Navigation

Plesk SDK API allows you to describe the way the pages of your extension are structured, and how users can navigate between them. To better understand the options available to you, take a look at the various navigational elements in Plesk.

Pathbar

This element displays hierarchical paths identifying where the page you are viewing is located within the navigational structure and allows you to move up this structure. Note that the pathbar works differently from "breadcrumbs" - it does not display the viewed pages in the order they were viewed (for example, Home > Domains > Home > Tools & Settings > Action Log > Home).

Title

In most cases, this element displays the name of the current page, except that on "Object overview" pages it shows the name of the currently viewed object instead. On "Object properties" pages, in addition to the name of the currently viewed object, it shows the current operation under the object and allows the user to go back to the "Object overview" page (like breadcrumbs would).

Object switcher

This element is displayed on "Object overview" and "Object properties" pages, and allows to switch between the currently viewed objects (for example, domains) without having to go to the page containing the complete list of those objects.

Tabs

This element allows to group several pages into a single one with the same title and pathbar.

Search

This element allows you to jump directly to a specific page without having to go through a sequence of transitions between pages.

Main navigation

See the Add Custom Buttons topic to learn how you can embed into this element.

For describing the navigational structure of your extension, use the pm_Hook_Navigation class. The hook must describe the method of the public function getNavigation() which must return an array including the configuration of pages.

Page configuration options:

  • controller (required) - the name of the controller to use when generating a href to the page (type: string).
  • action (required) - the name of the action to use when generating a href to the page (type: string).
  • label (optional) - a page label, such as 'Home' or 'Blog' (type: string, by default will use a localized message with key controllers.<controller_name>.<action_name>.title).
  • pages (optional) - child pages of this page. This can be an array containing the options for either page (type: array).
  • tabbed (optional) - a flag marking a page as the root page when a tabbed layout is used (type: boolean).
  • type (optional) - a class name which must be autoloaded and must extend either the pm_Navigation_Page or the pm_Navigation_OverviewPage class. This option is used for custom implementation of page objects or to mark that the page is an object overview page. This class is used when rendering the page title, object switcher, and for global search (type: string).

By default, the parent page for all top level pages is the "Extensions Management" page. If an extension has custom buttons with the same URL as the top level page, then its parent page depends on the placement of the custom button. For example, a page with same link as a custom button in the left menu has "Home" as its parent page.

Examples

Create a simple structure of pages

src/plib/hooks/Navigation.php

<?php
class Modules_<YourExtensionName>_Navigation extends pm_Hook_Navigation
{
    public function getNavigation()
    {
        return [
            [
                'controller' => 'index',
                'action' => 'index',
                'pages' => [
                    [
                        'controller' => 'blog',
                        'action' => 'index',
                        'pages' => [
                            [
                                'controller' => 'blog',
                                'action' => 'topic1',
                            ],
                            [
                                'controller' => 'blog',
                                'action' => 'topic2',
                            ],
                        ],
                    ],
                    [
                        'controller' => 'index',
                        'action' => 'about',
                    ],
                ],
            ],
        ];
    }
}

Do not forget to create controllers, actions, view scripts, and localization for titles related to your pages.

Group several pages into a single tabbed page

Use the renderTabs() view helper in view scripts of pages you want to group. Then add the "tabbed = true" option to the configuration of its' parent page in navigation configuration to mark it as a tabbed page.

Object Overview Page

Mark a page as an object overview page:

src/plib/hooks/Navigation.php

[
    'controller' => 'index',
    'action' => 'index',
    'type' => 'Modules_<YourExtensionName>_OverviewPage',
],

Page class:

src/plib/library/Objects.php

<?php
class Modules_<YourExtensionName>_OverviewPage extends pm_Navigation_OverviewPage
{
    public function getData() {
        $data = [];
        for ($i = 1; $i < 10; $i++) {
            $data[] = [
                'id' => $i,
                'title' => 'Object ' . $i,
            ];
        }
        return $data;
    }
}
 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.