.. _mainmenu:

Main menu
=========

The main menu component in iommi is used to create the main navigation for your app. This is primarily useful for SaaS or internal apps. It creates a sidebar menu with support for nested menu items, and centralized access control that automatically shows only menu items the user has access to.

To set up your main menu:

- add the `iommi.main_menu.main_menu_middleware` middleware to the `MIDDLEWARE` list
- declare your `MainMenu`
- define the `IOMMI_MAIN_MENU` setting to point to where you have defined your menu (like `IOMMI_MAIN_MENU = 'your_app.main_menu.main_menu'`).
- add the url patterns from the menu to your app

Access control is recursive, meaning that if a user does not have access to a menu item, it is automatically denied access to all subitems.

.. note::

    There are many more examples in :doc:`the cookbook <cookbook_main_menu>`.

.. code-block:: python

    menu_declaration = MainMenu(
        items=dict(
            artists=M(
                icon='people',
                view=artists_view,
            ),
            albums=M(
                icon='disc',
                view=albums_view,
            ),
        ),
    )

Add the url patterns from the menu to your app:

.. code-block:: python

    urlpatterns = menu_declaration.urlpatterns()

Your views will now get the menu rendered on standard iommi views. For non-iommi views you can render the menu with `{{ request.iommi_main_menu }}`.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2e2d8ae3-86f9-4d16-9e51-5369be0c89a1', this)">▼ Hide result</div>
    <iframe id="2e2d8ae3-86f9-4d16-9e51-5369be0c89a1" src="doc_includes/main_menu/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>