From 632c5e3036b39fdee58b442aff72e7a50baa7496 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thibault=20Delavall=C3=A9e?= Date: Thu, 15 Mar 2012 10:52:03 +0100 Subject: [PATCH] [DOC] Updated code and server documentation. bzr revid: tde@openerp.com-20120315095203-8g7drwdz9axjexwj --- doc/api/need_action_specs.rst | 28 +++++++++++++-- openerp/addons/base/base_needaction.py | 47 ++++++++++++++++---------- 2 files changed, 56 insertions(+), 19 deletions(-) diff --git a/doc/api/need_action_specs.rst b/doc/api/need_action_specs.rst index 5d5d94cf903..d33536a347d 100644 --- a/doc/api/need_action_specs.rst +++ b/doc/api/need_action_specs.rst @@ -1,8 +1,32 @@ Need action mixin class ======================= -This revision adds a mixin class for object implementing the need action mechanism. Need action mechanism can be used by objects that have to be able to signal that an action is required on a particular record. If in the business logic an action must be performed by somebody, for instance validation by a manager, this mechanism allows to set a field with the user_id of the user requested to perform the action. +This revision adds a mixin class for objects using the need action feature. Need action mechanism can be used by objects that have to be able to signal that an action is required on a particular record. If in the business logic an action must be performed by somebody, for instance validation by a manager, this mechanism allows to set a field with the user_id of the user requested to perform the action. -Technically, this class adds a need_action_user_id field; when set to false, no action is required; when an user_id is set, this user has an action to perform. This field is a function field. Setting an user_id is done through redefining the get_needaction_user_id method. Therefore by redefining only one method, you can specify the cases in which an action will be required on a particular record. +This class wraps a table (base.needaction_users_rel) that behaves like a many2many field. However, no field is added to the model inheriting from base.needaction. The mixin class manages the low-level considerations of updating relationships. Every change made on the record calls a method that updates the relationships. + +Objects using the need_action feature should override the ``get_needaction_user_ids`` method. This methods returns a dictionary whose keys are record ids, and values a list of user ids, like in a many2many relationship. Therefore by defining only one method, you can specify if an action is required by defining the users that have to do it, in every possible situation. + +This class also offers several global services,: + - ``needaction_get_user_record_references``: for a given uid, get all the records that asks this user to perform an action. Records are given as references, a list of tuples (model_name, record_id). This mechanism is used for instance to display the number of pending actions in menus, such as Leads (12). + +Addon implementation example +++++++++++++++++++++++++++++ + +In your ``foo`` module, you want to specify that when it is in state ``confirmed``, it has to be validated by a manager, given by the field ``manager_id``. After making ``foo`` inheriting from ``base.needaction``, you override the ``get_needaction_user_ids`` method: + +:: + + [...] + _inherit = [base.needaction] + [...] + def get_needaction_user_ids(self, cr, uid, ids, context=None): + # set the list void by default + result = dict.fromkeys(ids, []) + for foo_obj in self.browse(cr, uid, ids, context=context): + # if foo_obj is confirmed: manager is required to perform an action + if foo_obj.state == 'confirmed': + result[foo_obj.id] = [foo_obj.manager_id] + return result diff --git a/openerp/addons/base/base_needaction.py b/openerp/addons/base/base_needaction.py index 2deeec64492..62a36162e89 100644 --- a/openerp/addons/base/base_needaction.py +++ b/openerp/addons/base/base_needaction.py @@ -24,12 +24,12 @@ from tools.translate import _ class base_needaction_users_rel(osv.osv): ''' - base_needaction_users_rel holds the data related to the needaction + base_needaction_users_rel holds data related to the needaction mechanism inside OpenERP. A needaction is characterized by: - - res_model: model of the followed objects - - res_id: ID of resource + - res_model: model of the record requiring an action + - res_id: ID of the record requiring an action - user_id: foreign key to the res.users table, to the user that - has to perform an action + has to perform the action ''' _name = 'base.needaction_users_rel' @@ -46,23 +46,33 @@ class base_needaction_users_rel(osv.osv): class base_needaction(osv.osv): - '''Mixin class for object implementing the need action mechanism. + '''Mixin class for objects using the need action feature. - Need action mechanism can be used by objects that have to be able to + Need action feature can be used by objects willing to be able to signal that an action is required on a particular record. If in the business logic an action must be performed by somebody, for instance - validation by a manager, this mechanism allows to set a field with - the user_id of the user requested to perform the action. + validation by a manager, this mechanism allows to set a list of + users asked ot perform an action. - Technically, this class adds a need_action_user_id field; when - set to false, no action is required; when an user_id is set, - this user has an action to perform. This field is a function field. - Setting an user_id is done through redefining the get_needaction_user_id method. - Therefore by redefining only one method, you can specify - the cases in which an action will be required on a particular record. + This class wraps a table (base.needaction_users_rel) that behaves + like a many2many field. However, no field is added to the model + inheriting from base.needaction. The mixin class manages the low-level + considerations of updating relationships. Every change made on the + record calls a method that updates the relationships. - This mechanism is used for instance to display the number of pending actions - in menus, such as Leads (12). + Objects using the need_action feature should override the + ``get_needaction_user_ids`` method. This methods returns a dictionary + whose keys are record ids, and values a list of user ids, like + in a many2many relationship. Therefore by defining only one method, + you can specify if an action is required by defining the users + that have to do it, in every possible situation. + + This class also offers several global services,: + - ``needaction_get_user_record_references``: for a given uid, get all + the records that asks this user to perform an action. Records + are given as references, a list of tuples (model_name, record_id). + This mechanism is used for instance to display the number of pending + actions in menus, such as Leads (12). ''' _name = 'base.needaction' _description = 'Need action mechanism' @@ -148,7 +158,10 @@ class base_needaction(osv.osv): search_res = needact_rel_obj.search(cr, uid, [('user_id', '=', user_id)], offset=offset, limit=limit, order=order, count=count, context=context) return search_res - def needaction_get_record_references(self, cr, uid, user_id, offset=0, limit=None, order=None, context=None): + def needaction_get_user_record_references(self, cr, uid, user_id, offset=0, limit=None, order=None, context=None): + '''for a given uid, get all the records that asks this user to + perform an action. Records are given as references, a list of + tuples (model_name, record_id).''' if context is None: context = {} needact_rel_obj = self.pool.get('base.needaction_users_rel')