.. _menus:

=====
Menus
=====

Introducion
-----------

A menu is a (mptt) tree of :class:`pagetools.menus.models.MenuEntry` objects.
A `menu entry` encapsulates a generic content_object.
The content_object must provide a `get_absolute_url` method.
To be visible to unauthorized users a menu entry needs to have set the attribute `enabled` to `True`.

The root node of a menu is a proxy model of menu entry, :class:`pagetools.menus.models.Menu`.
The content object of a menu is a :class:`pagetools.menus.models.MenuCache` object.

The Menu admin
--------------

Once a menu is created it's admin page can be used to add/remove and edit both the entries and their content objects and reorder the entries through drag and drop.


.. image:: menuadmin.jpeg
   :height: 300px
   :alt: The menu admin
   :align: left

The menu tag
------------

A menu is meant to be called in the template with the template tag `menu`.
In contrast to a `Menu Entry` object, a menu is always enabled, the usage of the `enabled` property is overwritten and determinates if the menu cache is to be used.

For dynamic menu entries (e.g. only visible to authorized users) the menu cache can't be used.
But there is no limitation of the number of menus, so this possible::

        {% load menus_tags %}

        <ul class="menu ...">
        {% menu CommonMenu menukey %} {# enabled=True = use cache #}
        {% menu UserMenu menukey %}   {# enabled=False = no cache #}
        </ul>


The menu template
-----------------

The template used to render the menu is set in ``settings.PT_MENU_TEMPLATE``.
To support nested menus it must be able to call it self recursively,
see the templates :any:`django-pagetools/pagetools/menus/templates/menu.html`.
There are also
- `foundation_nav_menu.html`
- `foundation6_nav_menu.html`
- `bootstrap_nav_menu`.


.. _menuentrieables:

Menu entry content objects
--------------------------

There are some classes that are meant to be used as menu entry content objects.
They will be listed in the 'Add entry` section of the menu admin.
Furthermore all models which admin class inherits from :class:`pagetools.menus.admin.EntriableAdmin` *or*
were modified by :func:`pagetools.menus.admin.make_entrieable_admin` are shown there.


Link
^^^^

:class:`pagetools.menus.models.Link`
Just a simple link to anything.


ViewLink
^^^^^^^^

:class:`pagetools.menus.models.ViewLink`
A link to a view. The view must have a reverse name and cant' have any parameters.
To be shown in the corresponding admin choice field, somewhere
:func:`pagetools.menus.utils.entrieable_reverse_name` must be called with the reverse name of the view. It returns the name,
so that could be done directly in a `urls.py`::

        patterns = [
            (r'/foo', MyView.as_view(), name=entriebale_reverse_name("Foo")),
        ]

With an app name in the urls::

        app_name = "myapp"
        patterns = [
            (r'/foo', MyView.as_view(), name=entriebale_reverse_name("Foo", app_name="myapp")),
        ]


AutoPopulated
^^^^^^^^^^^^^
:class:`pagetools.menus.models.AutoPopulated`. An entry with sub entries which are generated by a callback.
See :ref:`app_integration` for an example.


Dashboard Menu Module
---------------------

The :class:`pagetools.menus.dashboard_modules.MenuModule` can be included in the dashboard. It has one additional parameter
`title` which is the name of the menu. The default is `MainMenu`.