Menus

Djing menus provide a convenient way to customize the main and user menus.

Overview

By default, Djing’s main left-side navigation menu displays all of your application’s dashboards, resources, and any custom tools you have registered.

When rendering the main menu, Djing will order your dashboards according to the order in which they are returned by the dashboards method within your application’s djing_admin.app.Providers.DjingServiceProvider class.

Djing will also automatically group your resources under the default “Resources” menu section according to the group property defined in the Resource class. In addition, any custom tools you have registered will be listed in the order they are defined within your application’s DjingServiceProvider.

Customizing the Main Menu

While Djing’s default main menu is sufficient for most applications, there are times you may wish to completely customize the menu based on your own preferences. For that reason, Djing allows you to define your own main menu via the Djing.main_menu method. Typically, this method should be invoked within the boot method of your application’sDjingServiceProvider class:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Foundation.Djing import Djing
from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Menu.MenuItem import MenuItem
from djing.core.Menu.MenuSection import MenuSection
from djing.core.Providers.DjingApplicationServiceProvider import (
    DjingApplicationServiceProvider,
)
from djing_admin.app.Djing.Dashboards.Main import Main
from djing_admin.app.Djing.User import User
from djing_admin.app.Djing.Product import Product

class DjingServiceProvider(DjingApplicationServiceProvider):
    # ...

    def _build_main_menu(self, request: DjingRequest):
        return [
            MenuSection.dashboard(Main).with_icon("chart-bar"),
            MenuSection.make(
                "Resources",
                [
                    MenuItem.resource(User),
                    MenuItem.resource(Product),
                ],
            )
            .with_icon("user")
            .collapsable(),
        ]

    def boot(self):
        super().boot()

        Djing.main_menu(self._build_main_menu)

Menu sections represent a top-level navigation item and are typically displayed with an corresponding icon representing the types of items in the menu. You can create a new menu section by calling the MenuSection.make method. This method accepts the name of the menu section and array of menu groups / items that should be placed within the section:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Foundation.Djing import Djing
from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Menu.MenuItem import MenuItem
from djing.core.Menu.MenuSection import MenuSection
from djing.core.Providers.DjingApplicationServiceProvider import (
    DjingApplicationServiceProvider,
)
from djing_admin.app.Djing.Dashboards.Main import Main
from djing_admin.app.Djing.Product import Product

class DjingServiceProvider(DjingApplicationServiceProvider):
    # ...

    def _build_main_menu(self, request: DjingRequest):
        return [
            MenuSection.make("Business", [
                MenuGroup.make("Licensing", [
                    MenuItem.dashboard(Main),
                    MenuItem.resource(Product),
                ]),    
            ]),
        ]

    def boot(self):
        super().boot()

        Djing.main_menu(self._build_main_menu)

Sometimes you may need another logical level between your menu sections and menu items. In this case, menu groups are the perfect solution. Menu groups allow you to group menu items under their own emphasized heading:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Foundation.Djing import Djing
from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Menu.MenuItem import MenuItem
from djing.core.Menu.MenuSection import MenuSection
from djing.core.Providers.DjingApplicationServiceProvider import (
    DjingApplicationServiceProvider,
)

class DjingServiceProvider(DjingApplicationServiceProvider):
    # ...

    def _build_main_menu(self, request: DjingRequest):
        return [
            MenuSection.make("Business", [
                MenuGroup.make("Licensing", [
                    # list of menu items
                ]),    
            ]),
        ]

    def boot(self):
        super().boot()

        Djing.main_menu(self._build_main_menu)

Collapsable Menu Groups

You may make your menu groups collapsable by invoking the collapsable method on the group. For convenience, Djing will remember the open state for the group between requests:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Foundation.Djing import Djing
from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Menu.MenuItem import MenuItem
from djing.core.Menu.MenuSection import MenuSection
from djing.core.Providers.DjingApplicationServiceProvider import (
    DjingApplicationServiceProvider,
)

class DjingServiceProvider(DjingApplicationServiceProvider):
    # ...

    def _build_main_menu(self, request: DjingRequest):
        return [
            MenuGroup.make("Licensing", [
                # list of menu items
            ]).collapsable(),
        ]

    def boot(self):
        super().boot()

        Djing.main_menu(self._build_main_menu)

Menu items represent the different types of links to areas inside and outside of your application that may be added to a custom Djing menu. Djing ships with several convenience methods for creating different types of menu items.

First, to create a link to an internal area of Djing, you may call the link factory method on the MenuItem class:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem

# ...

MenuItem.link('Cashier', '/cashier')

Resource Menu Items

Since you will often be creating links to Djing resources, you may use the resource method to quickly create a link to the appropriate path for a given resource:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem
from djing_admin.app.Djing.Product import Product

# ...

MenuItem.resource(Product)

Lens Menu Items

Similar to resource items, you may create links to Djing lenses via the lens method:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem
from djing_admin.app.Djing.Product import Product
from djing_admin.app.Djing.Lenses.MostValuableUsers import MostValuableUsers

# ...

MenuItem.lens(Product, MostValuableUsers)

Dashboard Menu Items

You may also create a link to any of your custom Djing dashboards by calling the dashboard factory method:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem
from djing_admin.app.Djing.Dashboards.Main import Main

# ...

MenuItem.dashboard(Main)

External Links Menu Items

To create a link that directs the user to a location that is totally outside of your Djing application, you may use the external_link factory method:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem

# ...

MenuItem.external_link('Documentation', 'https://djing.gitbook.io/docs')

Authorizing Menu Items

You may use the can_see method to determine if a menu item should be displayed for the currently authenticated user:

djing_admin/app/Providers/DjingServiceProvider.py
from djing.core.Menu.MenuItem import MenuItem
from djing_admin.app.Djing.Dashboards.Main import Main

# ...

MenuItem.dashboard(Main).can_see(lambda request: True)

Last updated