.. doctest docs/dev/xlmenu.rst .. _dev.xlmenu: ============================ The XL and application menus ============================ We have seen :doc:`menu`. You have already read about :ref:`xl`, a library of shared plugins that are designed to work together. An important aspect of this collaboration is how to integrate the functionalities into the application menu. .. contents:: :depth: 1 :local: .. include:: /../docs/shared/include/tested.rst The code snippets on this page use the :mod:`lino_book.projects.min1` demo project. >>> from lino import startup >>> startup('lino_book.projects.min1.settings') >>> from lino.api.doctest import * The :mod:`lino_book.projects.min1` has the following menu: >>> show_menu('robin') - Contacts : Persons, Organizations - Configure : - System : Site Parameters, Users - Contacts : Organization types, Functions - Places : Countries, Places - Explorer : - System : Authorities, User types, User roles - Contacts : Contact persons, Partners - Site : About, User sessions This menu is *not* defined by overriding the :meth:`setup_menu ` method. It was automatically generated by the installed plugins. Let's explore how this works. The top-level menus =================== The default implementation of :meth:`setup_menu ` uses a system of predefined **top-level menus** that are filled by the different installed plugins. These predefined top-level menus are themselves configurable in the :attr:`top_level_menus ` attribute of your application. You might specify your own set of top-level menus. But the :ref:`xl` assumes that your application uses the default value, which is: >>> settings.SITE.top_level_menus [('master', 'Master'), ('main', None), ('reports', 'Reports'), ('config', 'Configure'), ('explorer', 'Explorer'), ('site', 'Site')] It is a list of tuples with 2 items each. Each tuple has an internal name and a display name. Only the main entry has no display name. When a Lino application starts up, it loops over the installed plugins and, for each of them, loops again over these top-level menus and checks whether the plugin has a method called ``setup_XXX_menu`` (where XXX is the top-level menu name). - `setup_master_menu` - `setup_main_menu` - `setup_reports_menu` - `setup_config_menu` - `setup_explorer_menu` - `setup_site_menu` The main menu ============= setup_main_menu .. _config_menu: The Configuration menu ---------------------- setup_config_menu The Explorer menu ----------------- setup_explorer_menu .. _menu.groups: Introduction to menu groups =========================== The different installed plugins (identified by their `app_label`) are one way to group your database models into different "modules". But this grouping almost never exactly matches how the users would modularize their application. TODO: write more about it.