diff --git a/docs/customize/look-and-feel/menus.md b/docs/customize/look-and-feel/menus.md index bf68026d..75bf7569 100644 --- a/docs/customize/look-and-feel/menus.md +++ b/docs/customize/look-and-feel/menus.md @@ -1,10 +1,17 @@ -# Change Menus +# Change Menus/Tabs + +For navigation, InvenioRDM often uses menus or tabs. For example, one such menu is the user-dropdown menu: + +![User-settings menu with its 5 default entries](./img/settings-menu.png) + +And one such set of tabs is at the top of the user-dashboard: -For navigation, InvenioRDM uses *menu*s. For example, one such menu is at the -top of the dashboard shown to users on their personal page (with submenus -*Uploads*, *Communities*, and *Requests*): ![User's personal dashboard with three tabs labeled (left-to-right) "Uploads", "Communities", and "Requests"](./img/user-dashboard.png) -Menus are configurable in the following ways: + +In the codebase, menus and sets of tabs like those are referred as *menus*, so we do so here for the remainder of this how-to as well. +Their options (e.g., "Uploads", "Profile") are referred as *submenus*. + +These *menus* can be configured in the following ways: - which submenus to show - what title-text to show in those submenus @@ -13,9 +20,9 @@ Menus are configurable in the following ways: ## Configurable Properties -All submenus share the following properties. Properties of existing submenus can be overridden, properties of newly added submenus can be freely chosen. +All submenus share the following properties: | Name | Example values | Notes | |----------------|--------------------------------------|-----------------------------------------------------| @@ -25,7 +32,7 @@ properties of newly added submenus can be freely chosen. | `visible_when` | `flask_menu.menu.CONDITION_TRUE` | when to show this submenu
- must be of type `callable[[], bool]`
- `CONDITION_TRUE` is just a named `lambda: True`
- use `CONDITION_FALSE` to hide a submenu | | ... | ... | in addtion to the above properties, all arguments for `flask_menu.menu:MenuNode.register` are configurable | -For an example consider the user-dashboard pictured above. +For example, consider the user-dashboard pictured above. Its *Uploads* submenu has the following default configuration: ```python { @@ -42,9 +49,9 @@ Its *Uploads* submenu has the following default configuration: Existing menus can be extended by custom-configured submenus. To add a new submenu to an existing menu: -1. get the name of the to-be-added-to menu from the [list of menus](#list-of-menus) +1. Get the name of the to-be-added-to menu from the [list of menus](#list-of-menus) For example, the user-dashboard is named `"dashboard"` (most names of menus/submenus are straightforward). -2. write a function that registers the new submenu +2. Write a function that registers the new submenu ```python # ext.py # ext.py is commonly used, you may use another file though @@ -67,9 +74,9 @@ To add a new submenu to an existing menu: ... # could .register more submenus here (or do so in another package) ``` -3. have the endpoint `invenio_base.finalize_app` point at your function - This will make your function be called at the app-finalization build-step. - For example, when using setuptools' `setup.cfg` with your python-package, add: +3. Register your function with the `invenio_base.finalize_app` entrypoint. + This will make your function be called at the app-finalization build-step. + For example, when using setuptools' `setup.cfg` with your python package, add: ```ini # setup.cfg @@ -82,8 +89,7 @@ To add a new submenu to an existing menu: For entrypoint changes to be picked up, you will need to reinstall the python package. *This is necessary even if the package is installed editably!* -!!! info "Have you tried to turn it off and on again?" - After entrypoint changes were picked up, + After entrypoint changes are picked up, you will further need to restart the server for changes to take effect: ```shell @@ -95,12 +101,12 @@ To add a new submenu to an existing menu: The defaults of submenus' properties are selectively overridable via config-variables. To modify an existing submenu's properties: -1. find the name of the corresponding override-variable in the [list of menus](#list-of-menus) +1. Find the name of the corresponding override-variable in the [list of menus](#list-of-menus) For example, the override-variable for the user-dashboard is named `USER_DASHBOARD_MENU_OVERRIDES`. -2. find the name of the to-be-overridden submenu in that same [list of menus](#list-of-menus) +2. Find the name of the to-be-overridden submenu in that same [list of menus](#list-of-menus) For example, the user-dashboard has a submenu for communities. This submenu is named (obviously enough) `"communities"`. -3. add to your `invenio.cfg`: +3. Add to your `invenio.cfg`: ```python # invenio.cfg