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 that return a value
* Those that return nothing

Listening to a specific event is achieved as follow::

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

Read further to get a complete list and description of all available events.

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

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): pass

* ``oldaccount`` is the account that is going to be deleted
  
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.

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.

CreateDomain
============

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

CreateMailbox
=============

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)

DeleteDomain
============

Raised when an existing domain is about to be deleted.

*Callback prototype*::

  def callback(domain): pass

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

DeleteMailbox
=============

Raised when an existing mailbox is about to be deleted. 

*Callback prototype*::

  def callback(mailbox): pass

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

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

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 domain name

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

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.

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}

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

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.

.. _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(user): pass

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

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

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

ModifyMailbox
=============

Raised when an existing mailbox is modified. 

*Callback prototype*::

  def callback(newmailbox, oldmailbox): pass

* ``newmailbox`` is a ``Mailbox`` instance containing the new values
* ``oldmailbox`` is a ``Mailbox`` instance containing the old values

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
================

Let extensions add custom content into the top bar.

*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 string.

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