modoboa/doc/extending/events.rst

.. _events:

################
Available events
################

************
Introduction
************

Modoboa provides a simple API to interact with events. It understands
two kinds of events: 
 
* Those returning a value
* Those returning nothing

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.

****************
Supported events
****************

AccountAutoCreated
==================

Raised when a new account is automatically created (example: LDAP
synchronization).

*Callback prototype*::

  def callback(account): pass

* ``account`` is the newly created account (``User`` instance)

AccountCreated
==============

Raised when a new account is created.

*Callback prototype*::

  def callback(account): pass

* ``account`` is the newly created account (``User`` instance)

AccountDeleted
==============

Raised when an existing account is deleted.

*Callback prototype*::

  def callback(account, byuser, **options): pass

* ``account`` is the account that is going to be deleted
* ``byuser`` is the adminstrator deleting ``account``

AccountExported
===============

Raised when an account is exported to CSV.

*Callback prototype*::

  def callback(account): pass

* ``account`` is the account being exported

Must return a list of values to include in the export.

AccountImported
===============

Raised when an account is imported from CSV.

*Callback prototype*::

  def callback(user, account, row): pass

* ``user`` is the user importing the account
* ``account`` is the account being imported
* ``row`` is a list containing what remains from the CSV definition
  
AccountModified
===============

Raised when an existing account is modified.

*Callback prototype*::

  def callback(oldaccount, newaccount): pass

* ``oldaccount`` is the account before it is modified

* ``newaccount`` is the account after the modification

AdminMenuDisplay
================

Raised when an admin menu is about to be displayed.

*Callback prototype*::

  def callback(target, user): pass

The ``target`` argument indicates which menu is being
displayed. Possible values are:

* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages
* ``top_menu`` : corresponds to the top black bar

See :ref:`usermenudisplay` for a description of what callbacks that
listen to this event must return.

CanCreate
=========

Raised just before a user tries to create a new object.

*Callback prototype*::

  def callback(user): pass

* ``user`` is a ``User`` instance

Return ``True`` or ``False`` to indicate if this user can respectively
create or not create a new ``Domain`` object.

CheckDomainName
===============

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.

CheckExtraAccountForm
=====================

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

* ``account`` is the ``User`` instance beeing modified

* ``form`` is a dictionnary (same content as for ``ExtraAccountForm``)

Callbacks listening to this event must return a list containing one
Boolean.

DomainAliasCreated
==================

Raised when a new domain alias is created.

*Callback prototype*::

  def callback(user, domain_alias): pass

* ``user`` is the new domain alias owner (``User`` instance)
* ``domain_alias`` is the new domain alias (``DomainAlias`` instance)

DomainAliasDeleted
==================

Raised when an existing domain alias is about to be deleted. 

*Callback prototype*::

  def callback(domain_alias): pass

* ``domain_alias`` is a ``DomainAlias`` instance

DomainCreated
=============

Raised when a new domain is created. 

*Callback prototype*::

  def callback(user, domain): pass

* ``user`` corresponds to the ``User`` object creating the domain (its owner)
* ``domain`` is a ``Domain`` instance

DomainDeleted
=============

Raised when an existing domain is about to be deleted.

*Callback prototype*::

  def callback(domain): pass

* ``domain`` is a ``Domain`` instance

DomainModified
==============

Raised when a domain has been modified.

*Callback prototype*::

  def callback(domain): pass

* ``domain`` is the modified ``Domain`` instance, it contains an extra
  ``oldname`` field which contains the old name

DomainOwnershipRemoved
======================

Raised before the ownership of a domain is removed from its original
creator.

*Callback prototype*::

  def callback(owner, domain): pass

* ``owner`` is the original creator
* ``domain`` is the ``Domain`` instance being modified

ExtDisabled
===========

Raised just after an extension has been disabled. 

*Callback prototype*::

  def callback(extension): pass

* ``extension`` is an ``Extension`` instance

ExtEnabled
==========

Raised just after an extension has been activated. 

*Callback prototype*::

  def callback(extension): pass

* ``extension`` is an ``Extension`` instance

ExtraAccountActions
===================

Raised when the account list is displayed. Let developers define new
actions to act on a specific user.

*Callback prototype*::

  def callback(account): pass

* ``account`` is the account being listed

ExtraAccountForm
================

Let extensions add new forms to the account edition form (the one with
tabs).

*Callback prototype*::

  def callback(user, account): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

* ``account`` is the account beeing modified (``User`` instance)

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}

ExtraAdminContent
=================

Let extensions add extra content into the admin panel.

*Callback prototype*::

  def callback(user, target, currentpage): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

* ``target`` is a string indicating the place where the content will
  be displayed. Possible values are : ``leftcol``

* ``currentpage`` is a string indicating which page (or section) is
  displayed. Possible values are : ``domains``, ``identities``

Callbacks listening to this event must return a list of string.

ExtraDomainEntries
==================

Raised to request extra entries to display inside the *domains*
listing.

*Callback prototype*::

  def callback(user, domfilter, searchquery, **extrafilters): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user
* ``domfilter`` is a string indicating which domain type the user needs
* ``searchquery`` is a string containing a search query
* ``extrafilters`` is a set of keyword arguments that may contain additional filters

Must return a valid ``QuerySet``.

ExtraDomainFilters
==================

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).

ExtraDomainForm
===============

Let extensions add new forms to the domain edition form (the one with
tabs).

*Callback prototype*::

  def callback(user, domain): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

* ``domain`` is the domain beeing modified (``Domain`` instance)

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}

ExtraDomainImportHelp
=====================

Raised to request extra help text to display inside the domain import
form.

*Callback prototype*::

  def callback(): pass

Must return a list a string.

ExtraDomainMenuEntries
======================

Raised to request extra entries to include in the left menu of the
*domains* listing page.

*Callback prototype*::

  def callback(user): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user

Must return a list of dictionaries. Each dictionary must contain at
least three keys::

  {"name": "<menu name>",
   "label": "<menu label>",
   "url": "<menu url>"}

.. _extraformfields:

ExtraFormFields
===============

Raised to request extra fields to include in a django form.

*Callback prototype*::

  def callback(form_name, instance=None): pass

* ``form_name`` is a string used to distinguish a specific form
* ``instance`` is a django model instance related to ``form_name``

Must return a list of 2uple, each one containing the following
information::

  ('field name', <Django form field instance>)

ExtraRelayDomainForm
====================

Let extensions add new forms to the relay domain edition form (the one
with tabs).

*Callback prototype*::

  def callback(user, rdomain): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user
* ``rdomain`` is the relay domain being modified (``RelayDomain`` instance)

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}

FillAccountInstances
====================

When an account is beeing modified, this event is raised to fill extra
forms.

*Callback prototype*::

  def callback(user, account, instances): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

* ``account`` is the ``User`` instance beeing modified

* ``instances`` is a dictionnary where the callback will add
  information needed to fill a specific form

FillDomainInstances
===================

When a domain is beeing modified, this event is raised to fill extra
forms.

*Callback prototype*::

  def callback(user, domain, instances): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

* ``domain`` is the ``Domain`` instance beeing modified

* ``instances`` is a dictionnary where the callback will add
  information needed to fill a specific form

FillRelayDomainInstances
========================

When a relay domain is being modified, this event is raised to fill extra
forms.

*Callback prototype*::

  def callback(user, rdomain, instances): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user

* ``rdomain`` is the ``RelayDomain`` instance being modified

* ``instances`` is a dictionnary where the callback will add
  information needed to fill a specific form

GetAnnouncement
===============

Some places in the interface let plugins add their own announcement
(ie. message). 

*Callback prototype*::

  def callback(target): pass

* ``target`` is a string indicating the place where the announcement
  will appear:

* ``loginpage`` : corresponds to the login page

Callbacks listening to this event must return a list of string.

GetDomainActions
================

Raised to request the list of actions available for the *domains*
listing entry being displayed.

*Callback prototype*::

  def callback(user, rdomain): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user
* ``rdomain`` is the ``RelayDomain`` instance being displayed

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>"}

GetDomainModifyLink
===================

Raised to request the modification url of the *domains* listing entry
being displayed.

*Callback prototype*::

  def callback(domain): pass

* ``domain`` is a model instance (``RelayDomain`` for example)

Must return a dictionary containing at least the following entry::

  {'url': '<modification url>'}

GetExtraLimitTemplates
======================

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>')]

GetExtraParameters
==================

Raised to request extra parameters for a given parameters form.

*Callback prototype*::

  def callback(application, level): pass

* ``application`` is the name of the form's application (ie. admin, amavis, etc.)
* ``level`` is the form's level: ``A`` for admin or ``U`` for user

Must return a dictionary. Each entry must be a valid Django form field.

.. _getextraroles:

GetExtraRoles
=============

Let extensions define new administrative roles.

*Callback prototype*::

  def callback(user): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

Callbacks listening to this event must return a list of 2uple (two
strings) which respect the following format: ``(value, label)``.

GetStaticContent
================

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, st_type, user): pass

* ``caller`` is name of the application (or the location) responsible
  for the call

* ``st_type`` is the expected static content type (``css`` or ``js``)

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user

Callbacks listening to this event must return a list of string.

ImportObject
============

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

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user
* ``row`` is a string containing the object's definition (CSV format)
* ``formopts`` is a dictionary that may contain options

MailboxAliasCreated
===================

Raised when a new mailbox alias is created.

*Callback prototype*::

  def callback(user, mailbox_alias): pass

* ``user`` is the new domain alias owner (``User`` instance)
* ``mailbox_alias`` is the new mailbox alias (``Alias`` instance)

MailboxAliasDeleted
===================

Raised when an existing mailbox alias is about to be deleted. 

*Callback prototype*::

  def callback(mailbox_alias): pass

* ``mailbox_alias`` is an ``Alias`` instance

MailboxCreated
==============

Raised when a new mailbox is created.

*Callback prototype*::

  def callback(user, mailbox): pass

* ``user`` is the new mailbox's owner (``User`` instance)
* ``mailbox`` is the new mailbox (``Mailbox`` instance)

MailboxDeleted
==============

Raised when an existing mailbox is about to be deleted. 

*Callback prototype*::

  def callback(mailbox): pass

* ``mailbox`` is a ``Mailbox`` instance

MailboxModified
===============

Raised when an existing mailbox is modified. 

*Callback prototype*::

  def callback(mailbox): pass

* ``mailbox`` is the ``Mailbox`` modified instance. It contains a
  ``old_full_address`` extra field to check if the address was
  modified.

PasswordChange
==============

Raised just before a *password change* action. 

*Callback prototype*::

  def callback(user): pass

* ``user`` is a ``User`` instance

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).

TopNotifications
================

Lets extensions subscribe to the global notification service (located
inside the top bar).

*Callback prototype*::

  def callback(user, include_all): pass

* ``user`` is a ``User`` instance corresponding to the currently
  logged in user
* ``include_all`` is a boolean indicating if empty notifications must
  be included into the result or not

Callbacks listening to this event must return a list of dictionary,
each dictionary containing at least the following entries::

  {"id": "<notification entry ID>",
   "url": "<associated URL>",
   "text": "<text to display>"}

If your notification needs a counter, you can specify it by adding the
two following entries in the dictionary:

  {"counter": <associated counter>,
   "level": "<info|success|warning|error>"}

UserLogin
=========

Raised when a user logs in.

*Callback prototype*::

  def callback(request, username, password): pass

UserLogout
==========

Raised when a user logs out.

*Callback prototype*::

  def callback(request): pass

.. _usermenudisplay:

UserMenuDisplay
===============

Raised when a user menu is about to be displayed. 

*Callback prototype*::

  def callback(target, user): pass

The ``target`` argument indicates which menu is being
displayed. Possible values are:

* ``options_menu``: corresponds to the top-right user menu
* ``uprefs_menu``: corresponds to the menu bar available inside the
  *User preferences* page
* ``top_menu``: corresponds to the top black bar

All the callbacks that listen to this event must return a list of
dictionnaries (corresponding to menu entries). Each dictionnary must
contain at least the following keys::

  {"name" : "a_name_without_spaces",
   "label" : _("The menu label"),
   "url" : reverse("your_view")}

RelayDomainAliasCreated
=======================

Raised when a new relay domain alias is created.

*Callback prototype*::

  def callback(user, rdomain_alias): pass

* ``user`` is the new relay domain alias owner (``User`` instance)
* ``rdomain_alias`` is the new relay domain alias (``DomainAlias`` instance)

RelayDomainAliasDeleted
=======================

Raised when an existing relay domain alias is about to be deleted. 

*Callback prototype*::

  def callback(rdomain_alias): pass

* ``rdomain_alias`` is a ``RelayDomainAlias`` instance

RelayDomainCreated
==================

Raised when a new relay domain is created.

*Callback prototype*::

  def callback(user, rdomain): pass

* ``user`` corresponds to the ``User`` object creating the relay domain (its owner)
* ``rdomain`` is a ``RelayDomain`` instance

RelayDomainDeleted
==================

Raised when an existing relay domain is about to be deleted.

*Callback prototype*::

  def callback(rdomain): pass

* ``rdomain`` is a ``RelayDomain`` instance

RelayDomainModified
===================

Raised when a relay domain has been modified.

*Callback prototype*::

  def callback(rdomain): pass

* ``rdomain`` is the modified ``RelayDomain`` instance, it contains an
   extra ``oldname`` field which contains the old name

RoleChanged
===========

Raised when the role of an account is about to be changed.

*Callback prototype*::

  def callback(account, role): pass

* ``account`` is the account being modified
* ``role`` is the new role (string)

SaveExtraFormFields
===================

Raised to save extra fields declared using :ref:`extraformfields`.

*Callback prototype*::

  def callback(form_name, instance, values): pass

* ``form_name`` is a string used to distinguish a specific form
* ``instance`` is a django model instance related to ``form_name``
* ``values`` is a dictionary containing the form's values

UserCanSetRole
==============

Raised to check if a user is allowed to set a given role to an
account.

*Callback prototype*::

  def callback(account, role): pass

* ``user`` is the ``User`` instance corresponding to the currently
  logged in user
* ``role`` is the role ``user`` tries to set

Must return a list containing ``True`` or ``False`` to indicate if
this user can is allowed to set ``role``.