Registry

Introduction

In a modern cms you usually have several components that will be registered and/or configured in every installed site. This registration and configurations parameters would be defined by superuser in merengue admin interface. All would be stored in database.

Example use cases:

• Registering plugins, with plugin options (see plugin development docs?).
• Registering actions with configuration parameters (see actions docs?).
• Storing user preferences.
• Theme configuration (basic colors, etc.)

Using registry app

Example use case

Will be explaing with plugin configuration use case, with a example plugin that implements a "send page to friend" feature. That is already implemented on merengue plug app.

Use case is: imagine we wants to implement a plugin registering system, with configure plugins for developers.

Defining a registrable and configurable component

You can see it on __init__.py inside plug app. The fragment was:

from registry.items import RegistrableItem

class Plugin(RegistrableItem):

    @classmethod
    def get_category(cls):
        return 'plugin'

With this example, you have created a base class for all plugins. A plugin developer could declare his plugin with this fragment:

from plug import Plugin

class PluginConfig(Plugin):
    pass

As merengue convention, this fragment will live in a config.py module inside his plugin directory (that convention is for plugin autoregistering). But for this explanation we will consider that plugins are registered manually.

How can I do registering? With these sentences:

>>> from registry import register, is_registered
>>> from plugins.fooplugin.config import PluginConfig
>>> is_registered(PluginConfig)
False
>>> register(PluginConfig)
>>> is_registered(PluginConfig)
True

This sentences will register plugin by default in a RegisteredItem model in database. The RegisteredItem model definition is in apps.registry.models module.

Note: Do not confusing RegisteredItem with RegistrableItem. The last is not a Django model but an registrable object. The first is a model that store all RegistrableItems have been registered with registry.register function.

You can access to registered object with these sentences:

>>> from registry.models import RegisteredItem
>>> RegisteredItem.objects.all().values()
[{'class_name': u'PluginConfig', 'category': u'plugin', 'config': u'', 'id': 5, 'module': u'plugins.fooplugin.config'}]
>>> RegisteredItem.objects.get_by_item(PluginConfig)
<RegisteredItem: PluginConfig>

You can access to these registered items in admin interface. If you have launched a development server, listening on 8000 port. The URL for accessing registered items admin was:

http://localhost:8000/admin/registry/registereditem/

Configuring your registrable components

Let's look at this example:

from django.utils.translation import ugettext_lazy as _
from registry import params

class PluginConfig(Plugin):

    config_params = [
        params.Single(name='username', label=_('username'), default='pepe'),
        params.List(name='friends', label=_('friends'),
                    default=['antonio', 'juan'],
                    choices=[('antonio', 'Antonio'),
                             ('paco', 'Paco'),
                             ('rosa', 'Rosa'),
                             ('juan', 'Juan')]),
        params.Single(name='season', label=_('season'),
                      choices=[('spring', _('Spring')),
                               ('summer', _('Summer')),
                               ('autumn', _('Autumn')),
                               ('winter', _('Winter'))]),
    ]

Automatically, with this configuration, you can access to registered item in admin and will see and configure all parameters of this component.

If plugin developer want to access this configuration (remember, the configuration you customize in admin, no the default config_params for plugin), he would use these sentences:

>>> from plugins.fooplugin.config import PluginConfig
>>> config = PluginConfig.get_config()
>>> print config['friends'].value
['paco', 'juan']
>>> print config['friends'].choices
[('antonio', 'Antonio'), ('paco', 'Paco'), ('rosa', 'Rosa'), ('juan', 'Juan')]
>>> print config['friends'].default
['antonio', 'juan']
>>> config['friends'].get_type()
'List'