Modoboa provides a simple API to interact with events. It understands two kinds of events:
Listening to a specific event is achieved as follows:
from modoboa.lib import events
def callback(*args):
pass
events.register('event', callback)
You can also use the custom decorator events.observe:
@events.observe('event')
def callback(*args):
pass
event is the event’s name you want to listen to, callback is the function that will be called each time this event is raised. Each event impose to callbacks a specific prototype to respect. See below for a detailled list.
To stop listening to as specific event, you must use the unregister function:
events.unregister('event', callback)
The parameters are the same than those used with register.
To unregister all events declared by a specific extension, use the unregister_extension function:
events.unregister_extension([name])
name is the extension’s name but it is optional. Leave it empty to let the function guess the name.
Read further to get a complete list and description of all available events.
Raised when a new account is automatically created (example: LDAP synchronization).
Callback prototype:
def callback(account): pass
Raised when a new account is created.
Callback prototype:
def callback(account): pass
Raised when an existing account is deleted.
Callback prototype:
def callback(account, byuser, **options): pass
Raised when an account is exported to CSV.
Callback prototype:
def callback(account): pass
Must return a list of values to include in the export.
Raised when an account is imported from CSV.
Callback prototype:
def callback(user, account, row): pass
Raised when an existing account is modified.
Callback prototype:
def callback(oldaccount, newaccount): pass
Raised just before a user tries to create a new object.
Callback prototype:
def callback(user): pass
Return True or False to indicate if this user can respectively create or not create a new Domain object.
Raised before the unicity of a domain name is checked. By default, modoboa prevents duplicate names between domains and domain aliases but extensions have the possibility to extend this rule using this event.
Callback prototype:
def callback(): pass
Must return a list of 2uple, each one containing a model class and an associated label.
When an account is being modified, this event lets extensions check if this account is concerned by a specific form.
Callback prototype:
def callback(account, form): pass
Callbacks listening to this event must return a list containing one Boolean.
Raised when a new domain alias is created.
Callback prototype:
def callback(user, domain_alias): pass
Raised when an existing domain alias is about to be deleted.
Callback prototype:
def callback(domain_alias): pass
Raised when a new domain is created.
Callback prototype:
def callback(user, domain): pass
Raised when an existing domain is about to be deleted.
Callback prototype:
def callback(domain): pass
Raised when a domain has been modified.
Callback prototype:
def callback(domain): pass
Raised before the ownership of a domain is removed from its original creator.
Callback prototype:
def callback(owner, domain): pass
Raised just after an extension has been disabled.
Callback prototype:
def callback(extension): pass
Raised just after an extension has been activated.
Callback prototype:
def callback(extension): pass
Raised when the account list is displayed. Let developers define new actions to act on a specific user.
Callback prototype:
def callback(account): pass
Let extensions add new forms to the account edition form (the one with tabs).
Callback prototype:
def callback(user, account): pass
Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:
{"id" : "<the form's id>",
"title" : "<the title used to present the form>",
"cls" : TheFormClassName}
Let extensions add extra content into the admin panel.
Callback prototype:
def callback(user, target, currentpage): pass
Callbacks listening to this event must return a list of string.
Raised to request extra entries to display inside the domains listing.
Callback prototype:
def callback(user, domfilter, searchquery, **extrafilters): pass
Must return a valid QuerySet.
Raised to request extra filters for the domains listing page. For example, the postfix_relay_domains extension let users filter entries based on service types.
Callback prototype:
def callback(): pass
Must return a list of valid filter names (string).
Let extensions add new forms to the domain edition form (the one with tabs).
Callback prototype:
def callback(user, domain): pass
Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:
{"id" : "<the form's id>",
"title" : "<the title used to present the form>",
"cls" : TheFormClassName}
Raised to request extra help text to display inside the domain import form.
Callback prototype:
def callback(): pass
Must return a list a string.
Raised to request extra fields to include in a django form.
Callback prototype:
def callback(form_name, instance=None): pass
Must return a list of 2uple, each one containing the following information:
('field name', <Django form field instance>)
Let extensions add new forms to the relay domain edition form (the one with tabs).
Callback prototype:
def callback(user, rdomain): pass
Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:
{"id" : "<the form's id>",
"title" : "<the title used to present the form>",
"cls" : TheFormClassName}
When an account is beeing modified, this event is raised to fill extra forms.
Callback prototype:
def callback(user, account, instances): pass
When a domain is beeing modified, this event is raised to fill extra forms.
Callback prototype:
def callback(user, domain, instances): pass
When a relay domain is being modified, this event is raised to fill extra forms.
Callback prototype:
def callback(user, rdomain, instances): pass
Some places in the interface let plugins add their own announcement (ie. message).
Callback prototype:
def callback(target): pass
Callbacks listening to this event must return a list of string.
Raised to request the list of actions available for the domains listing entry being displayed.
Callback prototype:
def callback(user, rdomain): pass
Must return a list of dictionaries, each dictionary containing at least the following entries:
{"name": "<action name>",
"url": "<action url>",
"title": "<action title>",
"img": "<action icon>"}
Raised to request the modification url of the domains listing entry being displayed.
Callback prototype:
def callback(domain): pass
Must return a dictionary containing at least the following entry:
{'url': '<modification url>'}
Raised to request extra limit templates. For example, the postfix_relay_domains extension define a template to limit the number of relay domains an administrator can create.
Callback prototype:
def callback(): pass
Must return a list of set. Each set must contain at least three entries:
[('<limit_name>', '<limit label>', '<limit help text>')]
Raised to request extra parameters for a given parameters form.
Callback prototype:
def callback(application, level): pass
Must return a dictionary. Each entry must be a valid Django form field.
Let extensions define new administrative roles.
Callback prototype:
def callback(user): pass
Callbacks listening to this event must return a list of 2uple (two strings) which respect the following format: (value, label).
Let extensions add static content (ie. CSS or javascript) to default pages. It is pretty useful for functionalities that don’t need a template but need javascript stuff.
Callback prototype:
def callback(caller, user): pass
Callbacks listening to this event must return a list of string.
Raised to request the function handling an object being imported from CSV.
Callback prototype:
def callback(objtype): pass
objtype is the type of object being imported
Must return a list of function. A valid import function must respect the following prototype:
def import_function(user, row, formopts): pass
Raised when a new mailbox alias is created.
Callback prototype:
def callback(user, mailbox_alias): pass
Raised when an existing mailbox alias is about to be deleted.
Callback prototype:
def callback(mailbox_alias): pass
Raised when a new mailbox is created.
Callback prototype:
def callback(user, mailbox): pass
Raised when an existing mailbox is about to be deleted.
Callback prototype:
def callback(mailbox): pass
Raised when an existing mailbox is modified.
Callback prototype:
def callback(newmailbox, oldmailbox): pass
Raised just before a password change action.
Callback prototype:
def callback(user): pass
Callbacks listening to this event must return a list containing either True or False. If at least one True is returned, the password change will be cancelled (ie. changing the password for this user is disabled).
Let extensions add custom content into the top bar.
Callback prototype:
def callback(user): pass
Callbacks listening to this event must return a list of string.
Raised when a user logs in.
Callback prototype:
def callback(request, username, password): pass
Raised when a new relay domain alias is created.
Callback prototype:
def callback(user, rdomain_alias): pass
Raised when an existing relay domain alias is about to be deleted.
Callback prototype:
def callback(rdomain_alias): pass
Raised when a new relay domain is created.
Callback prototype:
def callback(user, rdomain): pass
Raised when an existing relay domain is about to be deleted.
Callback prototype:
def callback(rdomain): pass
Raised when a relay domain has been modified.
Callback prototype:
def callback(rdomain): pass
extra oldname field which contains the old name
Raised when the role of an account is about to be changed.
Callback prototype:
def callback(account, role): pass
Raised to save extra fields declared using ExtraFormFields.
Callback prototype:
def callback(form_name, instance, values): pass
Raised to check if a user is allowed to set a given role to an account.
Callback prototype:
def callback(account, role): pass
Must return a list containing True or False to indicate if this user can is allowed to set role.