Navigation

Server side the user interface of the application is implemented with Blade. CoreUI is used for an appealing design. CoreUI already comes with everything that is necessary for a graphical implementation of a menu structure. A central navigation store is used so that the creation of menus in the code is kept simple and, if possible, no redundant code is generated.

Concepts

The basic concept and functionality of the navigation store are briefly summarized below.

• The store src/Support/Store/Navigation/Navigation is registered as a singleton service in src/App/Common/Providers/NavigationServiceProvider and given an alias to ensure use with the associated facade.
• The store is initialized with Navigation::initialize via the provider’s boot function. This is done by throwing thesrc/Support/Events/NavigationCollectItemsEvent, which causes connected listeners to write the navigation items into the store’s pool. The pool is then validated for consistency.
• In order to make the store globally available in the blade interface, it is transferred to the view-instance.
• It is now possible to pass a route name to Navigation::set() whereby the store adapts its state according to the respective route. This is taken over by the middleware src/App/Common/Middlewares/Navigate by default, but can also be set manually by calling it up again at another point in the code.
• Navigation items must be created in a listener that listens to the event above.

Menu Levels (Types)

NAVIGATION_MAIN_LEVEL_1: Main menu on the left side of the application.

NAVIGATION_MAIN_LEVEL_2: Direct submenu items of a main menu item.

NAVIGATION_SUB: Submenu of the main menu.

NAVIGATION_TABS: Tab menu items which form the last menu level.

NAVIGATION_USER: A separate menu in the top right corner of the application.

Use in application modules

The idea is that each module has its own NavigationCollectItemsListener which is registered in src/App/Common/Providers/EventServiceProvider and listens to the src/Support/Events/NavigationCollectItemsEvent. All navigation items defined in this listener are automatically loaded into the application menu.

Practical use

Creation of a navigation item

A navigation item can be created with Navigation::addItemTo(). The following functions are available for this.

addItemTo() addItemTo(string $type, string $identifier): NavigationItem

Adds a new item with the specified identifier to the given menu type.

parent() parent(string $parent): static

Connects the item with the specified item, thus becoming the parent item of this item

route() route(string $route): static

Gives the item the name of a route which it later represents.

label() label(string $label): static

Passes its label on to the item.

icon() icon(string $icon): static

Passes the name of the icon to the item, which it should display later. Since CoreUi is used in this application, it is only possible to use its icon set. Example: icon('cil-user').

color() color(callable $callback): static

Passes a callback function to the item, which must return a bootstrap text color as a return value. Example:

color(function () {
    return 'text-primary';
})

pill() pill(callable $callback): static

Passes a callback function to the item, which should return an integer value as a return value, which should later be displayed in the pill. Example:

pill(function () {
    return 14;
})

policy() policy(string $policy): static

Gives the item the name of a policy according to which a decision should be made if the item should be visible to the current user or not.

Example of a single item

Navigation::addItemTo(Navigation::NAVIGATION_SUB, 'user_show')
            ->parent('user')
            ->route('user_show')
            ->label('Overview')
            ->icon('cil-list-rich');

Example for the integration into an event listener

<?php

namespace App\Admin\Core\Listeners;

use JohnIt\Bc\Ui\Presentation\Events\NavigationCollectItemsEvent;
use JohnIt\Bc\Ui\Presentation\Support\Facades\Navigation;

class NavigationCollectItemsListener
{
    public function handle(NavigationCollectItemsEvent $event): void
    {
        /*
        |--------------------------------------------------------------------------
        | User-Menu Items
        |--------------------------------------------------------------------------
        */
        Navigation::addItemTo(Navigation::NAVIGATION_USER, 'logout')
            ->route('user_index')
            ->label('Logout')
            ->icon('cil-account-logout');

        /*
        |--------------------------------------------------------------------------
        | Main-Menu Level 1 Items
        |--------------------------------------------------------------------------
        */
        Navigation::addItemTo(Navigation::NAVIGATION_MAIN_LEVEL_1, 'user')
            ->route('user_index')
            ->label('User')
            ->icon('cil-user');

        /*
        |--------------------------------------------------------------------------
        | Sub-Menu Items
        |--------------------------------------------------------------------------
        */
        Navigation::addItemTo(Navigation::NAVIGATION_SUB, 'user_show')
            ->parent('user')
            ->route('user_show')
            ->label('Overview')
            ->icon('cil-list-rich');

        Navigation::addItemTo(Navigation::NAVIGATION_SUB, 'user_correspondence')
            ->parent('user')
            ->route('user_correspondence')
            ->label('Messages')
            ->icon('cil-envelope-closed');
    }
}