Generalities

------------

occasion (this is called `running the hook`).

In CubicWeb, hooks are subclasses of the Hook class in

`server/hook.py`, implementing their own `call` method, and selected

over a set of pre-defined `events` (and possibly more conditions,

hooks being selectable AppObjects like views and components).

events.

trigger`_, except that database triggers definition languages are not

  (spanning several entities/relations, specific value ranges, exotic

  cardinalities, etc.)

Operations are subclasses of the Operation class in `server/hook.py`,

implementing `precommit_event` and other standard methods (wholly

described later in this chapter).

means as data gets in (entities added, updated, relations set or

unset), specific events are issued and the Hooks matching these events

are called.

Using Hooks

-----------

We will use a very simple example to show hooks usage. Let us start

with the following schema.

.. sourcecode:: python

   class Person(EntityType):

       age = Int(required=True)

An entity hook

~~~~~~~~~~~~~~

We would like to add a range constraint over a person's age. Let's

write an hook. It shall be placed into mycube/hooks.py. If this file

were to grow too much, we can easily have a mycube/hooks/... package

containing hooks in various modules.

.. sourcecode:: python

   from cubicweb import ValidationError

   from cubicweb.selectors import implements

   from cubicweb.server.hook import Hook

   class PersonAgeRange(Hook):

        __regid__ = 'person_age_range'

        events = ('before_add_entity', 'before_update_entity')

        __select__ = Hook.__select__ & implements('Person')

        def __call__(self):

            if 0 >= self.entity.age <= 120:

               return

            msg = self._cw._('age must be between 0 and 120')

            raise ValidationError(self.entity.eid, {'age': msg})

Hooks being AppObjects like views, they have a __regid__ and a

__select__ class attribute. The base __select__ is augmented with an

`implements` selector matching the desired entity type. The `events`

tuple is used by the Hook.__select__ base selector to dispatch the

hook on the right events. In an entity hook, it is possible to

dispatch on any entity event at once if needed.

Like all appobjects, hooks have the self._cw attribute which

represents the current session. In entity hooks, a self.entity

attribute is also present.

When a condition is not met in a Hook, it must raise a

ValidationError. Raising anything but a (subclass of) ValidationError

is a programming error.

The ValidationError exception is used to convey enough information up

to the user interface. Hence its constructor is different from the

default Exception constructor.It accepts, positionally:

* an entity eid,

* a dict whose keys represent attributes and values a message relating

  the problem; such a message will be presented to the end-users;

  hence it must be properly translated.

A relation hook

~~~~~~~~~~~~~~~

Let us add another entity type with a relation to person (in

mycube/schema.py).

.. sourcecode:: python

   class Company(EntityType):

        name = String(required=True)

        boss = SubjectRelation('Person', cardinality='1*')

We would like to constrain the company's bosses to have a minimum

(legal) age. Let's write an hook for this, which will be fired when

the `boss` relation is established.

.. sourcecode:: python

   class CompanyBossLegalAge(Hook):

        __regid__ = 'company_boss_legal_age'

        events = ('before_add_relation',)

        __select__ = Hook.__select__ & match_rtype('boss')

        def __call__(self):

            boss = self._cw.entity_from_eid(self.eidto)

            if boss.age < 18:

                msg = self._cw._('the minimum age for a boss is 18')

                raise ValidationError(self.eidfrom, {'boss': msg})

We use the `match_rtype` selector to select the proper relation type.

The essential difference with respect to an entity hook is that there

is no self.entity, but `self.eidfrom` and `self.eidto` hook attributes

which represent the subject and object eid of the relation.

# XXX talk about

dict access to entities in before_[add|update]

set_operation