customization: instructions for changing menus

docs/customize/look-and-feel/menus.md

@@ -0,0 +1,109 @@
+# Change Menus
+
+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*):
+![alt-text-read-for-accessibility](./img/user-dashboard.png)
+Menus are configurable in the following ways:
+
+- which tabs to show
+- what title-text to show in those tabs
+- which endpoint to request when clicking them
+- how to dynamically show/hide them (e.g. depending on currently logged-in user)
+
+## Step-by-step
+
+**Step 0** - Structure of Configuration
+
+The user-dashboard menu pictured above is internally named `"dashboard"`.
+The part of the menu-configuration particular to the `"dashboard"`-menu
+might look something like this:
+
+```python
+FLASK_MENU = {
+    "dashboard": {
+        "uploads": {
+            "endpoint": "invenio_app_rdm_users.uploads",
+            "text": _("Uploads"),
+            "order": 1,
+        },
+        "communities": {
+            "endpoint": "invenio_app_rdm_users.communities",
+            "text": _("Communities"),
+            "order": 2,
+        },
+        "requests": {
+            "endpoint": "invenio_app_rdm_users.requests",
+            "text": _("Requests"),
+            "order": 3,
+        },
+    },
+    ...  # configuration for other menus
+}
+```
+Here,
+
+- `"endpoint"` is the flask-endpoint requested when clicking the tab
+- `"text"` is the title-text in the tab
+- `"order"` determines order of tabs left-to-right
+
+**Step 1** - Modify menus via your `invenio.cfg`
+
+The relevant config-variable is `FLASK_MENU`.
+It will be populated with defaults when python-imports run.
+You can overwrite these defaults by adding to your `invenio.cfg` file:
+
+- overwrite the whole menu:
+```python
+# invenio.cfg file
+
+from flask_menu.config import FLASK_MENU
+
+FLASK_MENU["dashboard"] = {
+    "uploads": {
+        "endpoint": "my_user_endpoints.uploads",
+        "text": _("UPLOADS IN ALLCAPS"),
+        "order": 0,
+    },
+    # other tabs in default-configuration will be cut out
+}
+```
+
+- overwrite only a specific field of one submenu:
+```python
+# invenio.cfg file
+
+from flask_menu.config import FLASK_MENU
+
+FLASK_MENU["dashboard"]["communities"]["order"] = 4
+```
+
+**Step 2** - Re-run the server
+
+```shell
+<CTRL+C>
+invenio-cli run
+```
+
+## Advanced Configuration
+
+You can add to the configuration any kwarg that
+`flask_menu.menu:MenuNode.register` understands.
+
+### Configuring visibility
+
+`visible_when` can be any function that can be called with no arguments and
+returns a boolean.
+
+```python
+# invenio.cfg file
+
+from flask_menu import FLASK_MENU
+from invenio_config_my_institution import current_user_may_upload
+
+FLASK_MENU["dashboard"]["uploads"]["visible_when"] = current_user_may_upload
+```
+
+## Currently Configurable Menus
+
+- `"dashboard"`: dashboard on users' personal page

mkdocs.yml

@@ -52,6 +52,7 @@ nav:
           - Change logo: "customize/look-and-feel/logo.md"
           - Change templates: "customize/look-and-feel/templates.md"
           - Change theme: "customize/look-and-feel/theme.md"
+          - Change menus: "customize/look-and-feel/menus.md"
       - Authentication: "customize/authentication.md"
       - Sending emails: "customize/emails.md"
       - Search: