---
title: Navigation
---

# Navigation

<div class="documentation__toc"></div>

## Introduction

Navigation provides the top level addon navigation for the control panel. By default all installed and enabled modules will display a navigation item.

## Extending Navigation

To extend the navigation past it's default behavior you should listen for the `\Anomaly\Streams\Platform\Ui\ControlPanel\Component\Navigation\Event\GatherNavigation` event.

Below is a basic listener example of how the Stream Module adds navigation per "virtualized" namespace which acts as it's own addon later.

```php
<?php namespace Anomaly\StreamsModule\Group\Listener;

use Anomaly\Streams\Platform\Support\Authorizer;
use Anomaly\Streams\Platform\Ui\ControlPanel\Component\Navigation\Event\GatherNavigation;
use Anomaly\StreamsModule\Group\Contract\GroupInterface;
use Anomaly\StreamsModule\Group\Contract\GroupRepositoryInterface;

/**
 * Class AddVirtualizedNavigation
 *
 * @link   http://pyrocms.com/
 * @author PyroCMS, Inc. <support@pyrocms.com>
 * @author Ryan Thompson <ryan@pyrocms.com>
 */
class AddVirtualizedNavigation
{

    /**
     * The groups repository.
     *
     * @var GroupRepositoryInterface
     */
    protected $groups;

    /**
     * The authorizer utility.
     *
     * @var Authorizer
     */
    protected $authorizer;

    /**
     * Create a new AddVirtualizedNavigation instance.
     *
     * @param GroupRepositoryInterface $groups
     * @param Authorizer $authorizer
     */
    public function __construct(GroupRepositoryInterface $groups, Authorizer $authorizer)
    {
        $this->groups     = $groups;
        $this->authorizer = $authorizer;
    }

    /**
     * Handle the event.
     *
     * @param GatherNavigation $event
     */
    public function handle(GatherNavigation $event)
    {
        $builder = $event->getBuilder();

        /* @var GroupInterface $group */
        foreach ($this->groups->virtualized()->accessible() as $group) {
            $builder->addNavigation(
                $group->getSlug(),
                [
                    'breadcrumb' => $group->getName(),
                    'icon'       => $group->getIcon(),
                    'title'      => $group->getName(),
                    'slug'       => $group->getSlug(),
                    'href'       => 'admin/' . $group->getSlug(),
                    'permission' => 'anomaly.module.' . $group->getSlug() . '::*',
                ]
            );
        }
    }

}
```

### Sorting Navigation

The sorting is done alpha-numerically by default. However you can listen to the `\Anomaly\Streams\Platform\Ui\ControlPanel\Component\Navigation\Event\SortNavigation` event to arrange the navigation items to your liking.

Below is an example of how the `Accelerant` theme that comes with PyroCMS applies it's user defined custom sorting from settings/preferences.

[Settings Module](/documentation/settings-module){.link}
[Preferences Module](/documentation/preferences-module){.link}

```php
<?php namespace Pyrocms\AccelerantTheme\Listener;

use Anomaly\PreferencesModule\Preference\Contract\PreferenceRepositoryInterface;
use Anomaly\SettingsModule\Setting\Contract\SettingRepositoryInterface;
use Anomaly\Streams\Platform\Ui\ControlPanel\Component\Navigation\Event\SortNavigation;

/**
 * Class ApplySorting
 *
 * @link   http://pyrocms.com/
 * @author PyroCMS, Inc. <support@pyrocms.com>
 * @author Ryan Thompson <ryan@pyrocms.com>
 */
class ApplySorting
{

    /**
     * The settings repository.
     *
     * @var SettingRepositoryInterface
     */
    protected $settings;

    /**
     * The preferences repository.
     *
     * @var PreferenceRepositoryInterface $preferences
     */
    protected $preferences;

    /**
     * Create a new ApplySorting instance.
     *
     * @param SettingRepositoryInterface    $settings
     * @param PreferenceRepositoryInterface $preferences
     */
    public function __construct(SettingRepositoryInterface $settings, PreferenceRepositoryInterface $preferences)
    {
        $this->settings    = $settings;
        $this->preferences = $preferences;
    }

    /**
     * Handle the event.
     *
     * @param SortNavigation $event
     */
    public function handle(SortNavigation $event)
    {
        $builder    = $event->getBuilder();
        $navigation = $builder->getNavigation();

        if ($settings = $this->settings->value('pyrocms.theme.accelerant::navigation')) {
            $navigation = array_merge(array_flip((array)json_decode($settings)), $navigation);
        }

        if ($preferences = $this->preferences->value('pyrocms.theme.accelerant::navigation')) {
            $navigation = array_merge(array_flip((array)json_decode($preferences)), $navigation);
        }

        /**
         * Remove non-installed addons
         * cause they won't be in the nav.
         */
        $navigation = array_filter(
            $navigation,
            function ($item) {
                return is_array($item);
            }
        );

        $builder->setNavigation($navigation);
    }
}
```
