1087 lines
46 KiB
ReStructuredText
1087 lines
46 KiB
ReStructuredText
:banner: banners/flectra_mixins_and_useful_classes.jpg
|
|
|
|
.. _reference/mixins:
|
|
|
|
=========================
|
|
Mixins and Useful Classes
|
|
=========================
|
|
|
|
Flectra implements some useful classes and mixins that make it easy for you to add
|
|
often-used behaviours on your objects. This guide will details most of them, with
|
|
examples and use cases.
|
|
|
|
.. _reference/mixins/mail:
|
|
|
|
Messaging features
|
|
==================
|
|
|
|
.. _reference/mixins/mail/chatter:
|
|
|
|
Messaging integration
|
|
---------------------
|
|
|
|
Basic messaging system
|
|
''''''''''''''''''''''
|
|
|
|
Integrating messaging features to your model is extremely easy. Simply inheriting
|
|
the ``mail.thread`` model and adding the messaging fields (and their appropriate
|
|
widgets) to your form view will get you up and running in no time.
|
|
|
|
.. admonition:: Example
|
|
|
|
Let's create a simplistic model representing a business trip. Since organizing
|
|
this kind of trip usually involves a lot of people and a lot of discussion, let's
|
|
add support for message exchange on the model.
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread']
|
|
_description = 'Business Trip'
|
|
|
|
name = fields.Char()
|
|
partner_id = fields.Many2one('res.partner', 'Responsible')
|
|
guest_ids = fields.Many2many('res.partner', 'Participants')
|
|
|
|
In the form view:
|
|
|
|
.. code-block:: xml
|
|
|
|
<record id="businness_trip_form" model="ir.ui.view">
|
|
<field name="name">business.trip.form</field>
|
|
<field name="model">business.trip</field>
|
|
<field name="arch" type="xml">
|
|
<form string="Business Trip">
|
|
<!-- Your usual form view goes here
|
|
...
|
|
Then comes chatter integration -->
|
|
<div class="oe_chatter">
|
|
<field name="message_follower_ids" widget="mail_followers"/>
|
|
<field name="message_ids" widget="mail_thread"/>
|
|
</div>
|
|
</form>
|
|
</field>
|
|
</record>
|
|
|
|
Once you've added chatter support on your model, users can easily add messages
|
|
or internal notes on any record of your model; every one of those will send a
|
|
notification (to all followers for messages, to employee (*base.group_user*)
|
|
users for internal notes). If your mail gateway and catchall address are correctly
|
|
configured, these notifications will be sent by e-mail and can be replied-to directly
|
|
from your mail client; the automatic routing system will route the answer to the
|
|
correct thread.
|
|
|
|
Server-side, some helper functions are there to help you easily send messages and
|
|
to manage followers on your record:
|
|
|
|
.. rubric:: Posting messages
|
|
|
|
.. method:: message_post(self, body='', subject=None, message_type='notification', subtype=None, parent_id=False, attachments=None, content_subtype='html', **kwargs)
|
|
|
|
Post a new message in an existing thread, returning the new
|
|
mail.message ID.
|
|
|
|
:param str body: body of the message, usually raw HTML that will
|
|
be sanitized
|
|
:param str message_type: see mail_message.type field
|
|
:param str content_subtype: if plaintext: convert body into html
|
|
:param int parent_id: handle reply to a previous message by adding the
|
|
parent partners to the message in case of private discussion
|
|
:param list(tuple(str,str)) attachments: list of attachment tuples in the form
|
|
``(name,content)``, where content is NOT base64 encoded
|
|
:param `\**kwargs`: extra keyword arguments will be used as default column values for the
|
|
new mail.message record
|
|
:return: ID of newly created mail.message
|
|
:rtype: int
|
|
|
|
.. method:: message_post_with_view(views_or_xmlid, **kwargs):
|
|
|
|
Helper method to send a mail / post a message using a view_id to
|
|
render using the ir.qweb engine. This method is stand alone, because
|
|
there is nothing in template and composer that allows to handle
|
|
views in batch. This method will probably disappear when templates
|
|
handle ir ui views.
|
|
|
|
:param str or ``ir.ui.view`` record: external id or record of the view that
|
|
should be sent
|
|
|
|
.. method:: message_post_with_template(template_id, **kwargs)
|
|
|
|
Helper method to send a mail with a template
|
|
|
|
:param template_id: the id of the template to render to create the body of the message
|
|
:param `\**kwargs`: parameter to create a mail.compose.message wizzard (which inherit from mail.message)
|
|
|
|
.. rubric:: Receiving messages
|
|
|
|
These methods are called when a new e-mail is processed by the mail gateway. These
|
|
e-mails can either be new thread (if they arrive via an :ref:`alias <reference/mixins/mail/alias>`)
|
|
or simply replies from an existing thread. Overriding them allows you to set values
|
|
on the thread's record depending on some values from the email itself (i.e. update
|
|
a date or an e-mail address, add CC's addresses as followers, etc.).
|
|
|
|
.. method:: message_new(msg_dict, custom_values=None)
|
|
|
|
Called by ``message_process`` when a new message is received
|
|
for a given thread model, if the message did not belong to
|
|
an existing thread.
|
|
|
|
The default behavior is to create a new record of the corresponding
|
|
model (based on some very basic info extracted from the message).
|
|
Additional behavior may be implemented by overriding this method.
|
|
|
|
:param dict msg_dict: a map containing the email details and
|
|
attachments. See ``message_process`` and ``mail.message.parse`` for details
|
|
:param dict custom_values: optional dictionary of additional
|
|
field values to pass to create() when creating the new thread record;
|
|
be careful, these values may override any other values coming from
|
|
the message
|
|
:rtype: int
|
|
:return: the id of the newly created thread object
|
|
|
|
.. method:: message_update(msg_dict, update_vals=None)
|
|
|
|
Called by ``message_process`` when a new message is received
|
|
for an existing thread. The default behavior is to update the record
|
|
with ``update_vals`` taken from the incoming email.
|
|
|
|
Additional behavior may be implemented by overriding this
|
|
method.
|
|
|
|
:param dict msg_dict: a map containing the email details and attachments;
|
|
see ``message_process`` and ``mail.message.parse()`` for details.
|
|
:param dict update_vals: a dict containing values to update records given
|
|
their ids; if the dict is None or is void, no write operation is performed.
|
|
:return: True
|
|
|
|
.. rubric:: Followers management
|
|
|
|
.. method:: message_subscribe(partner_ids=None, channel_ids=None, subtype_ids=None, force=True)
|
|
|
|
Add partners to the records followers.
|
|
|
|
:param list(int) partner_ids: IDs of the partners that will be subscribed
|
|
to the record
|
|
:param list(int) channel_ids: IDs of the channels that will be subscribed
|
|
to the record
|
|
:param list(int) subtype_ids: IDs of the subtypes that the channels/partners
|
|
will be subscribed to (defaults to the default subtypes if ``None``)
|
|
:param force: if True, delete existing followers before creating new one
|
|
using the subtypes given in the parameters
|
|
:return: Success/Failure
|
|
:rtype: bool
|
|
|
|
.. method:: message_subscribe_users(user_ids=None, subtype_ids=None)
|
|
|
|
Wrapper on message_subscribe, using users instead of partners.
|
|
|
|
:param list(int) user_ids: IDs of the users that will be subscribed
|
|
to the record; if ``None``, subscribe the current user instead.
|
|
:param list(int) subtype_ids: IDs of the subtypes that the channels/partners
|
|
will be subscribed to
|
|
:return: Success
|
|
:rtype: bool
|
|
|
|
.. method:: message_unsubscribe(partner_ids=None, channel_ids=None)
|
|
|
|
Remove partners from the record's followers.
|
|
|
|
:param list(int) partner_ids: IDs of the partners that will be subscribed
|
|
to the record
|
|
:param list(int) channel_ids: IDs of the channels that will be subscribed
|
|
to the record
|
|
:return: True
|
|
:rtype: bool
|
|
|
|
|
|
.. method:: message_unsubscribe_users(user_ids=None)
|
|
|
|
Wrapper on message_subscribe, using users.
|
|
|
|
:param list(int) user_ids: IDs of the users that will be unsubscribed
|
|
to the record; if None, unsubscribe the current user instead.
|
|
:return: True
|
|
:rtype: bool
|
|
|
|
|
|
Logging changes
|
|
'''''''''''''''
|
|
|
|
The ``mail`` module adds a powerful tracking system on fields, allowing you
|
|
to log changes to specific fields in the record's chatter.
|
|
|
|
To add tracking to a field, simple add the track_visibility attribute with the
|
|
value ``onchange`` (if it should be displayed in the notification only if the
|
|
field changed) or ``always`` (if the value should always be displayed in change
|
|
notifications even if this particular field did not change - useful to make
|
|
notification more explanatory by always adding the name field, for example).
|
|
|
|
.. admonition:: Example
|
|
|
|
Let's track changes on the name and responsible of our business trips:
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread']
|
|
_description = 'Business Trip'
|
|
|
|
name = fields.Char(track_visibility='always')
|
|
partner_id = fields.Many2one('res.partner', 'Responsible',
|
|
track_visibility='onchange')
|
|
guest_ids = fields.Many2many('res.partner', 'Participants')
|
|
|
|
From now on, every change to a trip's name or responsible will log a note
|
|
on the record. The ``name`` field will be displayed in the notification as
|
|
well to give more context about the notification (even if the name did not
|
|
change).
|
|
|
|
|
|
Subtypes
|
|
''''''''
|
|
|
|
Subtypes give you more granular control over messages. Subtypes act as a classification
|
|
system for notifications, allowing subscribers to a document to customize the
|
|
subtype of notifications they wish to receive.
|
|
|
|
Subtypes are created as data in your module; the model has the following fields:
|
|
|
|
``name`` (mandatory) - :class:`~flectra.fields.Char`
|
|
name of the subtype, will be displayed in the notification customization
|
|
popup
|
|
``description`` - :class:`~flectra.fields.Char`
|
|
description that will be added in the message posted for this
|
|
subtype. If void, the name will be added instead
|
|
``internal`` - :class:`~flectra.fields.Boolean`
|
|
messages with internal subtypes will be visible only by employees,
|
|
aka members of the ``base.group_user`` group
|
|
``parent_id`` - :class:`~flectra.fields.Many2one`
|
|
link subtypes for automatic subscription; for example project subtypes are
|
|
linked to task subtypes through this link. When someone is subscribed to
|
|
a project, he will be subscribed to all tasks of this project with
|
|
subtypes found using the parent subtype
|
|
``relation_field`` - :class:`~flectra.fields.Char`
|
|
as an example, when linking project and tasks subtypes, the relation
|
|
field is the project_id field of tasks
|
|
``res_model`` - :class:`~flectra.fields.Char`
|
|
model the subtype applies to; if False, this subtype applies to all models
|
|
``default`` - :class:`~flectra.fields.Boolean`
|
|
wether the subtype is activated by default when subscribing
|
|
``sequence`` - :class:`~flectra.fields.Integer`
|
|
used to order subtypes in the notification customization popup
|
|
``hidden`` - :class:`~flectra.fields.Boolean`
|
|
wether the subtype is hidden in the notification customization popup
|
|
|
|
|
|
Interfacing subtypes with field tracking allows to subscribe to different kind
|
|
of notifications depending on what might interest users. To do this, you
|
|
can override the ``_track_subtype()`` function:
|
|
|
|
.. method:: _track_subtype(init_values)
|
|
|
|
Give the subtype triggered by the changes on the record according
|
|
to values that have been updated.
|
|
|
|
:param dict init_values: the original values of the record; only modified fields
|
|
are present in the dict
|
|
:returns: a subtype's full external id or False if no subtype is triggered
|
|
|
|
|
|
.. admonition:: Example
|
|
|
|
Let's add a ``state`` field on our example class and trigger a notification
|
|
with a specific subtype when this field change values.
|
|
|
|
First, let's define our subtype:
|
|
|
|
.. code-block:: xml
|
|
|
|
<record id="mt_state_change" model="mail.message.subtype">
|
|
<field name="name">Trip confirmed</field>
|
|
<field name="res_model">business.trip</field>
|
|
<field name="default" eval="True"/>
|
|
<field name="description">Business Trip confirmed!</field>
|
|
</record>
|
|
|
|
|
|
Then, we need to override the ``track_subtype()`` function. This function
|
|
is called by the tracking system to know which subtype should be used depending
|
|
on the change currently being applied. In our case, we want to use our shiny new
|
|
subtype when the ``state`` field changes from *draft* to *confirmed*:
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread']
|
|
_description = 'Business Trip'
|
|
|
|
name = fields.Char(track_visibility='onchange')
|
|
partner_id = fields.Many2one('res.partner', 'Responsible',
|
|
track_visibility='onchange')
|
|
guest_ids = fields.Many2many('res.partner', 'Participants')
|
|
state = fields.Selection([('draft', 'New'), ('confirmed', 'Confirmed')],
|
|
track_visibility='onchange')
|
|
|
|
def _track_subtype(self, init_values):
|
|
# init_values contains the modified fields' values before the changes
|
|
#
|
|
# the applied values can be accessed on the record as they are already
|
|
# in cache
|
|
self.ensure_one()
|
|
if 'state' in init_values and self.state == 'confirmed':
|
|
return 'my_module.mt_state_change' # Full external id
|
|
return super(BusinessTrip, self)._track_subtype(init_values)
|
|
|
|
|
|
Customizing notifications
|
|
'''''''''''''''''''''''''
|
|
|
|
When sending notifications to followers, it can be quite useful to add buttons in
|
|
the template to allow quick actions directly from the e-mail. Even a simple button
|
|
to link directly to the record's form view can be useful; however in most cases
|
|
you don't want to display these buttons to portal users.
|
|
|
|
The notification system allows customizing notification templates in the following
|
|
ways:
|
|
|
|
- Display *Access Buttons*: these buttons are visible at the top of the notification
|
|
e-mail and allow the recipient to directly access the form view of the record
|
|
- Display *Follow Buttons*: these buttons allow the recipient to
|
|
directly quickly subscribe from the record
|
|
- Display *Unfollow Buttons*: these buttons allow the recipient to
|
|
directly quickly unsubscribe from the record
|
|
- Display *Custom Action Buttons*: these buttons are calls to specific routes
|
|
and allow you to make some useful actions directly available from the e-mail (i.e.
|
|
converting a lead to an opportunity, validating an expense sheet for an
|
|
Expense Manager, etc.)
|
|
|
|
These buttons settings can be applied to different groups that you can define
|
|
yourself by overriding the function ``_notification_recipients``.
|
|
|
|
.. method:: _notification_recipients(message, groups)
|
|
|
|
Give the subtype triggered by the changes on the record according
|
|
to values that have been updated.
|
|
|
|
:param ``record`` message: ``mail.message`` record currently being sent
|
|
:param list(tuple) groups: list of tuple of the form (group_name, group_func,group_data) where:
|
|
|
|
group_name
|
|
is an identifier used only to be able to override and manipulate
|
|
groups. Default groups are ``user`` (recipients linked to an employee user),
|
|
``portal`` (recipients linked to a portal user) and ``customer`` (recipients not
|
|
linked to any user). An example of override use would be to add a group
|
|
linked to a res.groups like Hr Officers to set specific action buttons to
|
|
them.
|
|
group_func
|
|
is a function pointer taking a partner record as parameter. This
|
|
method will be applied on recipients to know whether they belong to a given
|
|
group or not. Only first matching group is kept. Evaluation order is the
|
|
list order.
|
|
group_data
|
|
is a dict containing parameters for the notification email with the following
|
|
possible keys - values:
|
|
|
|
- has_button_access
|
|
whether to display Access <Document> in email. True by default for
|
|
new groups, False for portal / customer.
|
|
- button_access
|
|
dict with url and title of the button
|
|
- has_button_follow
|
|
whether to display Follow in email (if recipient is not currently
|
|
following the thread). True by default for new groups, False for
|
|
portal / customer.
|
|
- button_follow
|
|
dict with url adn title of the button
|
|
- has_button_unfollow
|
|
whether to display Unfollow in email (if recipient is currently following the thread).
|
|
True by default for new groups, False for portal / customer.
|
|
- button_unfollow
|
|
dict with url and title of the button
|
|
- actions
|
|
list of action buttons to display in the notification email.
|
|
Each action is a dict containing url and title of the button.
|
|
|
|
:returns: a subtype's full external id or False if no subtype is triggered
|
|
|
|
|
|
The urls in the actions list can be generated automatically by calling the
|
|
``_notification_link_helper()`` function:
|
|
|
|
|
|
.. method:: _notification_link_helper(self, link_type, **kwargs)
|
|
|
|
Generate a link for the given type on the current record (or on a specific
|
|
record if the kwargs ``model`` and ``res_id`` are set).
|
|
|
|
:param str link_type: link type to be generated; can be any of these values:
|
|
|
|
``view``
|
|
link to form view of the record
|
|
``assign``
|
|
assign the logged user to the ``user_id`` field of
|
|
the record (if it exists)
|
|
``follow``
|
|
self-explanatory
|
|
``unfollow``
|
|
self-explanatory
|
|
``method``
|
|
call a method on the record; the method's name should be
|
|
provided as the kwarg ``method``
|
|
``new``
|
|
open an empty form view for a new record; you can specify
|
|
a specific action by providing its id (database id or fully resolved
|
|
external id) in the kwarg ``action_id``
|
|
|
|
:returns: link of the type selected for the record
|
|
:rtype: str
|
|
|
|
.. admonition:: Example
|
|
|
|
Let's add a custom button to the Business Trip state change notification;
|
|
this button will reset the state to Draft and will be only visible to a member
|
|
of the (imaginary) group Travel Manager (``business.group_trip_manager``)
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread', 'mail.alias.mixin']
|
|
_description = 'Business Trip'
|
|
|
|
# Pevious code goes here
|
|
|
|
def action_cancel(self):
|
|
self.write({'state': 'draft'})
|
|
|
|
def _notification_recipients(self, message, groups):
|
|
""" Handle Trip Manager recipients that can cancel the trip at the last
|
|
minute and kill all the fun. """
|
|
groups = super(BusinessTrip, self)._notification_recipients(message, groups)
|
|
|
|
self.ensure_one()
|
|
if self.state == 'confirmed':
|
|
app_action = self._notification_link_helper('method',
|
|
method='action_cancel')
|
|
trip_actions = [{'url': app_action, 'title': _('Cancel')}]
|
|
|
|
new_group = (
|
|
'group_trip_manager',
|
|
lambda partner: bool(partner.user_ids) and
|
|
any(user.has_group('business.group_trip_manager')
|
|
for user in partner.user_ids),
|
|
{
|
|
'actions': trip_actions,
|
|
})
|
|
|
|
return [new_group] + groups
|
|
|
|
|
|
Note that that I could have defined my evaluation function outside of this
|
|
method and define a global function to do it instead of a lambda, but for
|
|
the sake of being more brief and less verbose in these documentation files
|
|
that can sometimes be boring, I choose the former instead of the latter.
|
|
|
|
Overriding defaults
|
|
'''''''''''''''''''
|
|
|
|
There are several ways you can customize the behaviour of ``mail.thread`` models,
|
|
including (but not limited to):
|
|
|
|
``_mail_post_access`` - :class:`~flectra.models.Model` attribute
|
|
the required access rights to be able to post a message on the model; by
|
|
default a ``write`` access is needed, can be set to ``read`` as well
|
|
|
|
Context keys:
|
|
These context keys can be used to somewhat control ``mail.thread`` features
|
|
like auto-subscription or field tracking during calls to ``create()`` or
|
|
``write()`` (or any other method where it may be useful).
|
|
|
|
- ``mail_create_nosubscribe``: at create or message_post, do not subscribe
|
|
the current user to the record thread
|
|
- ``mail_create_nolog``: at create, do not log the automatic '<Document>
|
|
created' message
|
|
- ``mail_notrack``: at create and write, do not perform the value tracking
|
|
creating messages
|
|
- ``tracking_disable``: at create and write, perform no MailThread features
|
|
(auto subscription, tracking, post, ...)
|
|
- ``mail_auto_delete``: auto delete mail notifications; True by default
|
|
- ``mail_notify_force_send``: if less than 50 email notifications to send,
|
|
send them directly instead of using the queue; True by default
|
|
- ``mail_notify_user_signature``: add the current user signature in
|
|
email notifications; True by default
|
|
|
|
|
|
.. _reference/mixins/mail/alias:
|
|
|
|
Mail alias
|
|
----------
|
|
|
|
Aliases are configurable email addresses that are linked to a specific record
|
|
(which usually inherits the ``mail.alias.mixin`` model) that will create new records when
|
|
contacted via e-mail. They are an easy way to make your system accessible from
|
|
the outside, allowing users or customers to quickly create records in your
|
|
database without needing to connect to Flectra directly.
|
|
|
|
Aliases vs. Incoming Mail Gateway
|
|
'''''''''''''''''''''''''''''''''
|
|
|
|
Some people use the Incoming Mail Gateway for this same purpose. You still need
|
|
a correctly configured mail gateway to use aliases, however a single
|
|
catchall domain will be sufficient since all routing will be done inside Flectra.
|
|
Aliases have several advantages over Mail Gateways:
|
|
|
|
* Easier to configure
|
|
* A single incoming gateway can be used by many aliases; this avoids having
|
|
to configure multiple emails on your domain name (all configuration is done
|
|
inside Flectra)
|
|
* No need for System access rights to configure aliases
|
|
* More coherent
|
|
* Configurable on the related record, not in a Settings submenu
|
|
* Easier to override server-side
|
|
* Mixin model is built to be extended from the start, allowing you to
|
|
extract useful data from incoming e-mails more easily than with a mail
|
|
gateway.
|
|
|
|
|
|
Alias support integration
|
|
'''''''''''''''''''''''''
|
|
|
|
Aliases are usually configured on a parent model which will then create specific
|
|
record when contacted by e-mail. For example, Project have aliases to create tasks
|
|
or issues, Sales Channel have aliases to generate Leads.
|
|
|
|
.. note:: The model that will be created by the alias **must** inherit the
|
|
``mail_thread`` model.
|
|
|
|
Alias support is added by inheriting ``mail.alias.mixin``; this mixin will
|
|
generate a new ``mail.alias`` record for each record of the parent class that
|
|
gets created (for example, every ``project.project`` record having its ``mail.alias``
|
|
record initialized on creation).
|
|
|
|
.. note:: Aliases can also be created manually and supported by a simple
|
|
:class:`~flectra.fields.Many2one` field. This guide assumes you wish a
|
|
more complete integration with automatic creation of the alias, record-specific
|
|
default values, etc.
|
|
|
|
Unlike ``mail.thread`` inheritance, the ``mail.alias.mixin`` **requires** some
|
|
specific overrides to work correctly. These overrides will specify the values
|
|
of the created alias, like the kind of record it must create and possibly
|
|
some default values these records may have depending on the parent object:
|
|
|
|
.. method:: get_alias_model_name(vals)
|
|
|
|
Return the model name for the alias. Incoming emails that are not
|
|
replies to existing records will cause the creation of a new record
|
|
of this alias model. The value may depend on ``vals``, the dict of
|
|
values passed to ``create`` when a record of this model is created.
|
|
|
|
:param vals dict: values of the newly created record that will holding
|
|
the alias
|
|
:return: model name
|
|
:rtype: str
|
|
|
|
.. method:: get_alias_values()
|
|
|
|
Return values to create an alias, or to write on the alias after its
|
|
creation. While not completely mandatory, it is usually required to make
|
|
sure that newly created records will be linked to the alias' parent (i.e.
|
|
tasks getting created in the right project) by setting a dictionary of
|
|
default values in the alias' ``alias_defaults`` field.
|
|
|
|
:return: dictionnary of values that will be written to the new alias
|
|
:rtype: dict
|
|
|
|
The ``get_alias_values()`` override is particularly interesting as it allows you
|
|
to modify the behaviour of your aliases easily. Among the fields that can be set
|
|
on the alias, the following are of particular interest:
|
|
|
|
``alias_name`` - :class:`~flectra.fields.Char`
|
|
name of the email alias, e.g. 'jobs' if you want to catch emails for
|
|
<jobs@example.flectrahq.com>
|
|
``alias_user_id`` - :class:`~flectra.fields.Many2one` (``res.users``)
|
|
owner of records created upon receiving emails on this alias;
|
|
if this field is not set the system will attempt to find the right owner
|
|
based on the sender (From) address, or will use the Administrator account
|
|
if no system user is found for that address
|
|
``alias_defaults`` - :class:`~flectra.fields.Text`
|
|
Python dictionary that will be evaluated to provide
|
|
default values when creating new records for this alias
|
|
``alias_force_thread_id`` - :class:`~flectra.fields.Integer`
|
|
optional ID of a thread (record) to which all incoming messages will be
|
|
attached, even if they did not reply to it; if set, this will disable the
|
|
creation of new records completely
|
|
``alias_contact`` - :class:`~flectra.fields.Selection`
|
|
Policy to post a message on the document using the mailgateway
|
|
|
|
- *everyone*: everyone can post
|
|
- *partners*: only authenticated partners
|
|
- *followers*: only followers of the related document or members of following channels
|
|
|
|
Note that aliases make use of :ref:`delegation inheritance <reference/orm/inheritance>`,
|
|
which means that while the alias is stored in another table, you have
|
|
access to all these fields directly from your parent object. This allows
|
|
you to make your alias easily configurable from the record's form view.
|
|
|
|
.. admonition:: Example
|
|
|
|
Let's add aliases on our business trip class to create expenses on the fly via
|
|
e-mail.
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread', 'mail.alias.mixin']
|
|
_description = 'Business Trip'
|
|
|
|
name = fields.Char(track_visibility='onchange')
|
|
partner_id = fields.Many2one('res.partner', 'Responsible',
|
|
track_visibility='onchange')
|
|
guest_ids = fields.Many2many('res.partner', 'Participants')
|
|
state = fields.Selection([('draft', 'New'), ('confirmed', 'Confirmed')],
|
|
track_visibility='onchange')
|
|
expense_ids = fields.One2many('business.expense', 'trip_id', 'Expenses')
|
|
alias_id = fields.Many2one('mail.alias', string='Alias', ondelete="restrict",
|
|
required=True)
|
|
|
|
def get_alias_model_name(self, vals):
|
|
""" Specify the model that will get created when the alias receives a message """
|
|
return 'business.expense'
|
|
|
|
def get_alias_values(self):
|
|
""" Specify some default values that will be set in the alias at its creation """
|
|
values = super(BusinessTrip, self).get_alias_values()
|
|
# alias_defaults holds a dictionnary that will be written
|
|
# to all records created by this alias
|
|
#
|
|
# in this case, we want all expense records sent to a trip alias
|
|
# to be linked to the corresponding business trip
|
|
values['alias_defaults'] = {'trip_id': self.id}
|
|
# we only want followers of the trip to be able to post expenses
|
|
# by default
|
|
values['alias_contact'] = 'followers'
|
|
return values
|
|
|
|
class BusinessExpense(models.Model):
|
|
_name = 'business.expense'
|
|
_inherit = ['mail.thread']
|
|
_description = 'Business Expense'
|
|
|
|
name = fields.Char()
|
|
amount = fields.Float('Amount')
|
|
trip_id = fields.Many2one('business.trip', 'Business Trip')
|
|
partner_id = fields.Many2one('res.partner', 'Created by')
|
|
|
|
We would like our alias to be easily configurable from the form view of our
|
|
business trips, so let's add the following to our form view:
|
|
|
|
.. code-block:: xml
|
|
|
|
<page string="Emails">
|
|
<group name="group_alias">
|
|
<label for="alias_name" string="Email Alias"/>
|
|
<div name="alias_def">
|
|
<!-- display a link while in view mode and a configurable field
|
|
while in edit mode -->
|
|
<field name="alias_id" class="oe_read_only oe_inline"
|
|
string="Email Alias" required="0"/>
|
|
<div class="oe_edit_only oe_inline" name="edit_alias"
|
|
style="display: inline;" >
|
|
<field name="alias_name" class="oe_inline"/>
|
|
@
|
|
<field name="alias_domain" class="oe_inline" readonly="1"/>
|
|
</div>
|
|
</div>
|
|
<field name="alias_contact" class="oe_inline"
|
|
string="Accept Emails From"/>
|
|
</group>
|
|
</page>
|
|
|
|
Now we can change the alias address directly from the form view and change
|
|
who can send e-mails to the alias.
|
|
|
|
We can then override ``message_new()`` on our expense model to fetch the values
|
|
from our email when the expense will be created:
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessExpense(models.Model):
|
|
# Previous code goes here
|
|
# ...
|
|
|
|
def message_new(self, msg, custom_values=None):
|
|
""" Override to set values according to the email.
|
|
|
|
In this simple example, we simply use the email title as the name
|
|
of the expense, try to find a partner with this email address and
|
|
do a regex match to find the amount of the expense."""
|
|
name = msg_dict.get('subject', 'New Expense')
|
|
# Match the last occurence of a float in the string
|
|
# Example: '50.3 bar 34.5' becomes '34.5'. This is potentially the price
|
|
# to encode on the expense. If not, take 1.0 instead
|
|
amount_pattern = '(\d+(\.\d*)?|\.\d+)'
|
|
expense_price = re.findall(amount_pattern, name)
|
|
price = expense_price and float(expense_price[-1][0]) or 1.0
|
|
# find the partner by looking for it's email
|
|
partner = self.env['res.partner'].search([('email', 'ilike', email_address)],
|
|
limit=1)
|
|
defaults = {
|
|
'name': name,
|
|
'amount': price,
|
|
'partner_id': partner.id
|
|
}
|
|
defaults.update(custom_values or {})
|
|
res = super(BusinessExpense, self).message_new(msg, custom_values=defaults)
|
|
return res
|
|
|
|
.. _reference/mixins/mail/activities:
|
|
|
|
Activities tracking
|
|
-------------------
|
|
|
|
Activities are actions users have to take on a document like making a phone call
|
|
or organizing a meeting. Activities come with the mail module as they are
|
|
integrated in the Chatter but are *not bundled with mail.thread*. Activities
|
|
are records of the ``mail.activity`` class, which have a type (``mail.activity.type``),
|
|
name, description, scheduled time (among others). Pending activities are visible
|
|
above the message history in the chatter widget.
|
|
|
|
You can integrate activities using the ``mail.activity.mixin`` class on your object
|
|
and the specific widgets to display them (via the field ``activity_ids``) in the form
|
|
view and kanban view of your records (``mail_activity`` and ``kanban_activity``
|
|
widgets, respectively).
|
|
|
|
.. admonition:: Example
|
|
|
|
Organizing a business trip is a tedious process and tracking needed activities
|
|
like ordering plane tickets or a cab for the airport could be useful. To do so,
|
|
we will add the activities mixin on our model and display the next planned activities
|
|
in the message history of our trip.
|
|
|
|
.. code-block:: python
|
|
|
|
class BusinessTrip(models.Model):
|
|
_name = 'business.trip'
|
|
_inherit = ['mail.thread', 'mail.activity.mixin']
|
|
_description = 'Business Trip'
|
|
|
|
name = fields.Char()
|
|
# [...]
|
|
|
|
We modify the form view of our trips to display their next activites:
|
|
|
|
.. code-block:: xml
|
|
|
|
<record id="businness_trip_form" model="ir.ui.view">
|
|
<field name="name">business.trip.form</field>
|
|
<field name="model">business.trip</field>
|
|
<field name="arch" type="xml">
|
|
<form string="Business Trip">
|
|
<!-- Your usual form view goes here -->
|
|
<div class="oe_chatter">
|
|
<field name="message_follower_ids" widget="mail_followers"/>
|
|
<field name="activity_ids" widget="mail_activity"/>
|
|
<field name="message_ids" widget="mail_thread"/>
|
|
</div>
|
|
</form>
|
|
</field>
|
|
</record>
|
|
|
|
You can find concrete examples of integration in the following models:
|
|
|
|
* ``crm.lead`` in the CRM (*crm*) Application
|
|
* ``sale.order`` in the Sales (*sale*) Application
|
|
* ``project.task`` in the Project (*poject*) Application
|
|
|
|
|
|
.. _reference/mixins/website:
|
|
|
|
Website features
|
|
================
|
|
|
|
.. _reference/mixins/website/utm:
|
|
|
|
Visitor tracking
|
|
----------------
|
|
|
|
The ``utm.mixin`` class can be used to track online marketing/communication
|
|
campaigns through arguments in links to specified resources. The mixin adds
|
|
3 fields to your model:
|
|
|
|
* ``campaign_id``: :class:`~flectra.fields.Many2one` field to a ``utm.campaign``
|
|
object (i.e. Christmas_Special, Fall_Collection, etc.)
|
|
* ``source_id``: :class:`~flectra.fields.Many2one` field to a ``utm.source``
|
|
object (i.e. Search Engine, mailing list, etc.)
|
|
* ``medium_id``: :class:`~flectra.fields.Many2one` field to a ``utm.medium``
|
|
object (i.e. Snail Mail, e-Mail, social network update, etc.)
|
|
|
|
These models have a single field ``name`` (i.e. they are simply there to
|
|
distinguish campaigns but don't have any specific behaviour).
|
|
|
|
Once a customer visits your website with these parameters set in the url
|
|
(i.e. http://www.flectrahq.com/?campaign_id=mixin_talk&source_id=www.flectrahq.com&medium_id=website),
|
|
three cookies are set in the visitor's website for these parameters.
|
|
Once a object that inherits the utm.mixin is created from the website (i.e. lead
|
|
form, job application, etc.), the utm.mixin code kicks in and fetches the values
|
|
from the cookies to set them in the new record. Once this is done, you can then
|
|
use the campaign/source/medium fields as any other field when defining reports
|
|
and views (group by, etc.).
|
|
|
|
To extend this behaviour, simply add a relational field to a simple model (the
|
|
model should support the *quick create* (i.e. call to ``create()`` with a single
|
|
``name`` value) and extend the function ``tracking_fields()``:
|
|
|
|
.. code-block:: python
|
|
|
|
class UtmMyTrack(models.Model):
|
|
_name = 'my_module.my_track'
|
|
_description = 'My Tracking Object'
|
|
|
|
name = fields.Char(string='Name', required=True)
|
|
|
|
|
|
class MyModel(models.Models):
|
|
_name = 'my_module.my_model'
|
|
_inherit = ['utm.mixin']
|
|
_description = 'My Tracked Object'
|
|
|
|
my_field = fields.Many2one('my_module.my_track', 'My Field')
|
|
|
|
@api.model
|
|
def tracking_fields(self):
|
|
result = super(MyModel, self).tracking_fields()
|
|
result.append([
|
|
# ("URL_PARAMETER", "FIELD_NAME_MIXIN", "NAME_IN_COOKIES")
|
|
('my_field', 'my_field', 'flectra_utm_my_field')
|
|
])
|
|
return result
|
|
|
|
This will tell the system to create a cookie named *flectra_utm_my_field* with the
|
|
value found in the url parameter ``my_field``; once a new record of this model is
|
|
created by a call from a website form, the generic override of the ``create()``
|
|
method of ``utm.mixin`` will fetch the default values for this field from the
|
|
cookie (and the ``my_module.my_track`` record will be creatwed on the fly if it
|
|
does not exist yet).
|
|
|
|
You can find concrete examples of integration in the following models:
|
|
|
|
* ``crm.lead`` in the CRM (*crm*) Application
|
|
* ``hr.applicant`` in the Recruitment Process (*hr_recruitment*) Application
|
|
* ``helpdesk.ticket`` in the Helpdesk (*helpdesk* - Flectra Enterprise only) Application
|
|
|
|
.. _reference/mixins/website/published:
|
|
|
|
Website visibility
|
|
------------------
|
|
|
|
You can quite easily add a website visibility toggle on any of your record. While
|
|
this mixin is quite easy to implement manually, it is the most often-used after
|
|
the ``mail.thread`` inheritance; a testament to its usefulness. The typical use
|
|
case for this mixin is any object that has a frontend-page; being able to control
|
|
the visibility of the page allows you to take your time while editing the page
|
|
and only publish it when you're satisfied.
|
|
|
|
To include the functionnality, you only need to inherit ``website.published.mixin``:
|
|
|
|
.. code-block:: python
|
|
|
|
class BlogPost(models.Model):
|
|
_name = "blog.post"
|
|
_description = "Blog Post"
|
|
_inherit = ['website.published.mixin']
|
|
|
|
This mixin adds 2 fields on your model:
|
|
|
|
* ``website_published``: :class:`~flectra.fields.Boolean` field which represents
|
|
the status of the publication
|
|
* ``website_url``: :class:`~flectra.fields.Char` field which represents
|
|
the URL through which the object is accessed
|
|
|
|
Note that this last field is a computed field and must be implemented for your class:
|
|
|
|
.. code-block:: python
|
|
|
|
def _compute_website_url(self):
|
|
for blog_post in self:
|
|
blog_post.website_url = "/blog/%s" % (log_post.blog_id)
|
|
|
|
Once the mechanism is in place, you just have to adapt your frontend and backend
|
|
views to make it accessible. In the backend, adding a button in the button box is
|
|
usually the way to go:
|
|
|
|
.. code-block:: xml
|
|
|
|
<button class="oe_stat_button" name="website_publish_button"
|
|
type="object" icon="fa-globe">
|
|
<field name="website_published" widget="website_button"/>
|
|
</button>
|
|
|
|
In the frontend, some security checks are needed to avoid showing 'Edition'
|
|
buttons to website visitors:
|
|
|
|
.. code-block:: xml
|
|
|
|
<div id="website_published_button" class="pull-right"
|
|
groups="base.group_website_publisher"> <!-- or any other meaningful group -->
|
|
<t t-call="website.publish_management">
|
|
<t t-set="object" t-value="blog_post"/>
|
|
<t t-set="publish_edit" t-value="True"/>
|
|
<t t-set="action" t-value="'blog.blog_post_action'"/>
|
|
</t>
|
|
</div>
|
|
|
|
Note that you must pass your object as the variable ``object`` to the template;
|
|
in this example, the ``blog.post`` record was passed as the ``blog_post`` variable
|
|
to the ``qweb`` rendering engine, it is necessary to specify this to the publish
|
|
management template. The ``publish_edit`` variable allow the frontend
|
|
button to link to the backend (allowing you to switch from frontend to backend
|
|
and vice-versa easily); if set, you must specify the full external id of the action
|
|
you want to call in the backend in the ``action`` variable (note that a Form View
|
|
must exist for the model).
|
|
|
|
The action ``website_publish_button`` is defined in the mixin and adapts its
|
|
behaviour to your object: if the class has a valid ``website_url`` compute function,
|
|
the user is redirected to the frontend when he clicks on the button; the user
|
|
can then publish the page directly from the frontend. This ensures
|
|
that no online publication can happen by accident. If there is not compute function,
|
|
the boolean ``website_published`` is simply triggered.
|
|
|
|
.. _reference/mixins/website/seo:
|
|
|
|
Website metadata
|
|
----------------
|
|
|
|
This simple mixin simply allows you to easily inject metadata in your frontend
|
|
pages.
|
|
|
|
.. code-block:: python
|
|
|
|
class BlogPost(models.Model):
|
|
_name = "blog.post"
|
|
_description = "Blog Post"
|
|
_inherit = ['website.seo.metadata', 'website.published.mixin']
|
|
|
|
This mixin adds 3 fields on your model:
|
|
|
|
* ``website_meta_title``: :class:`~flectra.fields.Char` field that allow you to set
|
|
an additional title to your page
|
|
* ``website_meta_description``: :class:`~flectra.fields.Char` field that contains a
|
|
short description of the page (sometimes used in search engines results)
|
|
* ``website_meta_keywords``: :class:`~flectra.fields.Char` field that contains some
|
|
keywords to help your page to be classified more precisely by search engines; the
|
|
"Promote" tool will help you select lexically-related keywords easily
|
|
|
|
These fields are editable in the frontend using the "Promote" tool from the Editor
|
|
toolbar. Setting these fields can help search engines to better index your pages.
|
|
Note that search engines do not base their results only on these metadata; the
|
|
best SEO practice should still be to get referenced by reliable sources.
|
|
|
|
.. _reference/mixins/misc:
|
|
|
|
Others
|
|
======
|
|
|
|
.. _reference/mixins/misc/rating:
|
|
|
|
Customer Rating
|
|
---------------
|
|
|
|
The rating mixin allows sending email to ask for customer rating, automatic
|
|
transitioning in a kanban processes and aggregating statistics on your ratings.
|
|
|
|
Adding rating on your model
|
|
'''''''''''''''''''''''''''
|
|
|
|
To add rating support, simply inherit the ``rating.mixin`` model:
|
|
|
|
.. code-block:: python
|
|
|
|
class MyModel(models.Models):
|
|
_name = 'my_module.my_model'
|
|
_inherit = ['rating.mixin', 'mail.thread']
|
|
|
|
user_id = fields.Many2one('res.users', 'Responsible')
|
|
partner_id = fields.Many2one('res.partner', 'Customer')
|
|
|
|
The behaviour of the mixin adapts to your model:
|
|
|
|
* The ``rating.rating`` record will be linked to the ``partner_id`` field of your
|
|
model (if the field is present).
|
|
|
|
- this behaviour can be overriden with the function ``rating_get_partner_id()``
|
|
if you use another field than ``partner_id``
|
|
|
|
* The ``rating.rating`` record will be linked to the partner of the ``user_id``
|
|
field of your model (if the field is present) (i.e. the partner who is rated)
|
|
|
|
- this behaviour can be overriden with the function ``rating_get_rated_partner_id()``
|
|
if you use another field than ``user_id`` (note that the function must return a
|
|
``res.partner``, for ``user_id`` the system automatically fetches the partner
|
|
of the user)
|
|
|
|
* The chatter history will display the rating event (if your model inherits from
|
|
``mail.thread``)
|
|
|
|
Send rating requests by e-mail
|
|
''''''''''''''''''''''''''''''
|
|
|
|
If you wish to send emails to request a rating, simply generate an e-mail with
|
|
links to the rating object. A very basic email template could look like this:
|
|
|
|
.. code-block:: xml
|
|
|
|
<record id="rating_my_model_email_template" model="mail.template">
|
|
<field name="name">My Model: Rating Request</field>
|
|
<field name="email_from">${object.rating_get_rated_partner_id().email or '' | safe}</field>
|
|
<field name="subject">Service Rating Request</field>
|
|
<field name="model_id" ref="my_module.model_my_model"/>
|
|
<field name="partner_to" >${object.rating_get_partner_id().id}</field>
|
|
<field name="auto_delete" eval="True"/>
|
|
<field name="body_html"><![CDATA[
|
|
% set access_token = object.rating_get_access_token()
|
|
<p>Hi,</p>
|
|
<p>How satsified are you?</p>
|
|
<ul>
|
|
<li><a href="/rating/${access_token}/10">Satisfied</a></li>
|
|
<li><a href="/rating/${access_token}/5">Not satisfied</a></li>
|
|
<li><a href="/rating/${access_token}/1">Very unsatisfied</a></li>
|
|
</ul>
|
|
]]></field>
|
|
</record>
|
|
|
|
Your customer will then receive an e-mail with links to a simple webpage allowing
|
|
them to provide a feedback on their interaction with your users (including a free-text
|
|
feedback message).
|
|
|
|
You can then quite easily integrate your ratings with your form view by defining
|
|
an action for the ratings:
|
|
|
|
.. code-block:: xml
|
|
|
|
<record id="rating_rating_action_my_model" model="ir.actions.act_window">
|
|
<field name="name">Customer Ratings</field>
|
|
<field name="res_model">rating.rating</field>
|
|
<field name="view_mode">kanban,pivot,graph</field>
|
|
<field name="domain">[('res_model', '=', 'my_module.my_model'), ('res_id', '=', active_id), ('consumed', '=', True)]</field>
|
|
</record>
|
|
|
|
<record id="my_module_my_model_view_form_inherit_rating" model="ir.ui.view">
|
|
<field name="name">my_module.my_model.view.form.inherit.rating</field>
|
|
<field name="model">my_module.my_model</field>
|
|
<field name="inherit_id" ref="my_module.my_model_view_form"/>
|
|
<field name="arch" type="xml">
|
|
<xpath expr="//div[@name='button_box']" position="inside">
|
|
<button name="%(rating_rating_action_my_model)d" type="action"
|
|
class="oe_stat_button" icon="fa-smile-o">
|
|
<field name="rating_count" string="Rating" widget="statinfo"/>
|
|
</button>
|
|
</xpath>
|
|
</field>
|
|
</record>
|
|
|
|
Note that there are default views (kanban,pivot,graph) for ratings which allow
|
|
you a quick bird's eye view of your customer ratings. |