README.md 2.13 KB
Newer Older
Pascal's avatar
Pascal committed
1 2
# admin-extra

Pascal's avatar
Pascal committed
3 4 5 6 7 8 9
This plugin adds buttons and messages facilities to the
[lektor](https://www.getlektor.com/) development server
and admin panel.

## Flash messages

Flask flash messages are displayed on top of the pages.
Pascal's avatar
Pascal committed
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

## Help pages

By default, a ``?`` help button is added to all served pages,
which links to a main help page.

If the lektor project contains a ``content/admin-pages`` folder,
the help button will redirect there. This page should have system
fields ``_hidden: yes`` and ``_discoverable: no``.

If ``content/admin-pages`` is not found, the default
``template/help.html`` of this plugin is served instead.

When writing ``admin-pages``, consider extending the default
``template/help.html``.

Pascal's avatar
Pascal committed
26 27
### Adding buttons via configuration

Pascal's avatar
Pascal committed
28
In the file ``configs/admin-extra.ini``
Pascal's avatar
Pascal committed
29 30 31 32
with the following syntax
```
[button.help]
url = /admin-pages/
Pascal's avatar
doc  
Pascal committed
33
title = help
Pascal's avatar
Pascal committed
34 35 36
html = ?
[button.logout]
url = /logout
Pascal's avatar
doc  
Pascal committed
37
title = logout
Pascal's avatar
Pascal committed
38 39 40 41
html = x
index = 0
scope = dash
```
Pascal's avatar
Pascal committed
42
(these buttons are automatically added)
Pascal's avatar
Pascal committed
43 44 45 46 47

Use ``scope=server`` to display the button only on display mode,
or ``scope=dash`` to show it only in admin panel (default both)

Use ``index=1`` to show the button in position 1 (index start at 0).
Pascal's avatar
Pascal committed
48

Pascal's avatar
Pascal committed
49
## Adding buttons with plugins
Pascal's avatar
Pascal committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74

Besides the default ``?`` help button, the plugin makes it possible
to register other links. For example, the ``lektor-login``
plugin registers a logout link.

Use ``add_serve_button(url, tooltip, html)`` to add a button
to all served pages, and ``add_dash_button`` for dash.

Example
```
class MyPlugin(Plugin):
    def on_setup_env(self, *args, **extra):
        admin_extra = get_plugin('admin-extra', self.env)
        admin_extra.add_button( '/secret/url', 'hidden diary', ':-/' )
```

Trick: in order to use ``url_for``, the code must run after Flask app has
started. An option is to register under ``before_app_first_request``
```
        from lektor.admin.modules import serve
        @serve.bp.before_app_first_request
        def register_button():
            admin_extra.add_button( '/secret/url', 'hidden diary', ':-/' )
```

Pascal's avatar
Pascal committed
75
## How it works
Pascal's avatar
Pascal committed
76

Pascal's avatar
Pascal committed
77 78
The plugin uses the flask ``after_request`` entrypoint to inject extra html
in all served pages.