Write a plugin

Waliki has a very little core designed to be extensible with plugins.

At the moment, there are a few plugins built in but you can create a new one very easily.

A plugin is a normal Django app, with a file named waliki_plugin.py that defines a subclass of BasePlugin.

As an example, see the waliki.git.waliki_plugin.py.

from django.utils.translation import ugettext_lazy as _
from waliki.plugins import BasePlugin, register


class GitPlugin(BasePlugin):

    slug = 'git'
    urls_page = ['waliki.git.urls']
    extra_page_actions = {'all': [('waliki_history', _('History'))]}
    navbar_links = (('waliki_whatchanged', _('What changed')),)

register(GitPlugin)

What can a plugin do?

In the first place, it’s important to remark that a waliki plugin is a django app, so you can do with them anything an app can do: define new models, add or override templates, connect signals, etc.

Tip

Moreover, you can override a waliki core view! It’s possible because the urls registered by plugins take precedence over the core ones.

In addition, you can register “actions” (views that receive a page slug as parameter).

The field extra_page_actions is a list of tuples ('url_name', 'link text'), where each url_name is reversed passing the page’s slug as parameter. These actions appear in the dropdown of the * “Edit”* button.

Analogously, extra_edit_actions add “buttons” (links) to the editor toolbar.

Extending templates with entry points

Another thing a plugin can do is to extend the core templates. It leverages in the template tag entry_point.

Wherever a tag {% entry_point 'name' %} is present, this templatetag will look for templates named waliki/<plugin_slug>_name for each plugin registered and it will include those found.

For example, the block {% block content %} in edit.html ends like this:

    ...

    {% entry_point 'edit_content' %}
{% endblock content %}

At that point, the template waliki/attachments_edit_content.html (and any other template with the waliki/<plugin_slug>_edit_content.html) will be appended , using a standard include that receives the whole context.

Tip

you can search the code to know every template entry point available

Waliki signals

In addition to the built-in model signals, your plugin can connect receivers functions to the signals that Waliki sends when few actions happen. At the moment, there is one:

  • page_saved is sent just after saving a page. The parameters are the page instance, the user who edited the page, and the optional message. For example, Git extensions uses it to make a commit with the new comment.

Note

Of course, you can add any new signals you need!