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

    54 implementing `precommit_event` and other standard methods (wholly

    55 described later in this chapter).

    56 

   112 Using Hooks

   113 -----------

   114 

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

   116 with the following schema.

   117 

   118 .. sourcecode:: python

   119 

   120    class Person(EntityType):

   121        age = Int(required=True)

   122 

   123 An entity hook

   124 ~~~~~~~~~~~~~~

   125 

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

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

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

   129 containing hooks in various modules.

   130 

   131 .. sourcecode:: python

   132 

   133    from cubicweb import ValidationError

   134    from cubicweb.selectors import implements

   135    from cubicweb.server.hook import Hook

   136 

   137    class PersonAgeRange(Hook):

   138         __regid__ = 'person_age_range'

   139         events = ('before_add_entity', 'before_update_entity')

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

   141 

   142         def __call__(self):

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

   144                return

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

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

   147 

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

   149 __select__ class attribute. The base __select__ is augmented with an

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

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

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

   153 dispatch on any entity event at once if needed.

   154 

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

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

   157 attribute is also present.

   158 

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

   160 ValidationError. Raising anything but a (subclass of) ValidationError

   161 is a programming error.

   162 

   163 The ValidationError exception is used to convey enough information up

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

   165 default Exception constructor.It accepts, positionally:

   166 

   167 * an entity eid,

   168 

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

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

   171   hence it must be properly translated.

   172 

   173 A relation hook

   174 ~~~~~~~~~~~~~~~

   175 

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

   177 mycube/schema.py).

   178 

   179 .. sourcecode:: python

   180 

   181    class Company(EntityType):

   182         name = String(required=True)

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

   184 

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

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

   187 the `boss` relation is established.

   188 

   189 .. sourcecode:: python

   190 

   191    class CompanyBossLegalAge(Hook):

   192         __regid__ = 'company_boss_legal_age'

   193         events = ('before_add_relation',)

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

   195 

   196         def __call__(self):

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

   198             if boss.age < 18:

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

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

   201 

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

   203 

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

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

   206 which represent the subject and object eid of the relation.

   207 

   208 

   209 # XXX talk about

   210 

   211 dict access to entities in before_[add|update]

   212 set_operation