Documentation needed for email notification system

[David Seddon]

I've been unable to find any documentation on the email notification system.

After quite a bit of detective work I was able to establish that certain emails have a code (e.g. 'ORDER_PLACED').  If you create a communication event type with that code in the admin backend, then you will be able to leverage the Content > Email Templates UI from the Dashboard, which seems great.

What I haven't been able to establish yet:

- How to override the default email template in code, rather than in the database.  For example, I have placed the following file in my templates directory: 'customer/emails/commtype_order_placed_body.txt'  However this is not used when sending the email out.  I would expect it to.

- What the behaviour is relating to html versus plain text.  When is one sent out rather than another?

[David Seddon]

EDIT: overriding the template in code is indeed working, I hadn't realised the email was in html.

[Maik Hoepfel]

Hi David,

I fully agree that the docs are lacking in that regard. The notification system itself could do with an overhaul; that's on our list, but not with a high priority. Please let me know any problems or stumbling blocks you encounter; I'll make sure to address them in the docs.

The email sending code is in https://github.com/tangentlabs/django-oscar/blob/master/oscar/apps/customer/alerts/utils.py#L48 At first glance, it looks like only text notifications are sent out via email, and the HTML templates are used for notifications displayed on the site.

Cheers,

Maik

[David Seddon]

Thanks Maik,

Cool, I'll take a look at the code for that bit.

I think that even just a few lines giving an overview of the notifications system might be useful - it's not even mentioned at the moment.  If I end up needing to get my head around it in more detail then I'll post up a draft of what I learn!

David

[Maik Hoepfel]

Hi David,

did you manage to get your head around it? :) I'd be interested in your stumbling points, and would happily accept a pull request (even for a draft) and finish it up.

Regards,

Maik

[David Seddon]

Hi Maik,

Sorry for the delay - see below for draft of what I understand about the system.  Hope it's useful.

David

Communicating to customers via email
====================================

Oscar provides the ability to customise the emails sent out to customers.

There are two main ways this can be achieved, either in code (via template files) or in the database (via Dashboard > Content > Email templates).

Communications API
------------------

First, it's important to understand a little about how the Communications API works.

Oscar has a model called a CommunicationEventType.  When preparing an email to send out to a customer, the client code will do something like this:

    commtype_code = 'SOME_EVENT'
    context = {'customer': customer, 'something_else': 'Some more context.'}

    try:
            event_type = CommunicationEventType.objects.get(code=commtype_code)
        except CommunicationEventType.DoesNotExist:
            messages = CommunicationEventType.objects.get_and_render(commtype_code, ctx)
        else:
            messages = event_type.get_messages(ctx)
   
What's happening here is:

  - The code defines an arbitrary communication type code to be treated as the reference for this particular type of communication.  For example, the communication type code used when sending an order email confirmation is 'ORDER_PLACED'.
  - The database is checked for a CommunicationEventType with this communication type code.  If it does, it renders the messages using that model instance, passing in some context.
  - Otherwise, it uses the get_and_render() method to render the messages, which uses templates instead.

So, your first step when customising the emails sent out is to work out what communication type code is being used to send out the email.  The easiest way to work this out is usually to look through  the email templates in templates/oscar/customer/emails: if the email template is called, say, commtype_order_placed_body.html, then the code will be ORDER_PLACED.  (See 'Customising through code' below.)

Customising through code
------------------------

Customising emails through code uses Django's standard template inheritance.

The first step is to locate the template for the particular email, which is usually in templates/oscar/customer/emails.  Then, in a template directory that takes precedence over the oscar templates directory, copy the file and customise it.  For example, to override the templates/oscar/customer/emails/commtype_order_placed_body.html, create the file customer/emails/commtype_order_placed_body.html in your template directory.

Note that usually emails have three template files associated with them: the email subject line (commtype_CODE_subject.txt), the html version (commtype_CODE_body.html) and the text version (commtype_CODE_body.txt).  Usually you will want to make sure you override BOTH the html and the text version.

Customising through code will not work if there is a template defined in the database instead (see below).


Customising through the database
--------------------------------

Oscar provides a dashboard interface to allow admins to customise the emails.

To enable this for a particular communication event type, log in to the admin site and create a new Communication Event Type.  The code you use is the important thing: it needs to match the communication event code used when rendering the messages.  For example, to override the order confirmation email, you need to create a Communication Event Type with a code 'ORDER_PLACED'.

Once you have created the Communication Event Type, you can edit it using the (much better) dashboard interface at Dashboard > Content > Email templates.

If you have an email template defined in the database it will override any template files.

[Maik Hoepfel]

Hi David,

I finally got around to adding it. I only did markup changes and
committed it in
https://github.com/tangentlabs/django-oscar/commit/0605344418a55af6cb41d41ad6466e53e78608c6.
I tried setting you as author, but couldn't because you have no commits
on Oscar yet :( I gave all credit in the commit message though.

Thank you very much,

Maik

> --
> https://github.com/tangentlabs/django-oscar
> http://django-oscar.readthedocs.org/en/latest/
> https://twitter.com/django_oscar
> ---
> You received this message because you are subscribed to a topic in the
> Google Groups "django-oscar" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/django-oscar/LmSQo-CNMr0/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> django-oscar...@googlegroups.com.
> Visit this group at http://groups.google.com/group/django-oscar.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-oscar/0199e48c-7971-45d1-b4d3-fa4ec671f9b2%40googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>



Maik Hoepfel


Tangent Snowball
84-86 Great Portland Street
London
W1W 7NR




www.tangentsnowball.com

Tangent Snowball is a registered trading name of Tangent Marketing Services Limited
Registered Office: 84-86 Great Portland Street, London W1W 7NR
Registered in England Wales Number 4323657

This message contains confidential information and is intended only for the individual named.
If you are not the named addressee you should not disseminate, distribute or copy this e-mail.
Please notify the sender immediately by e-mail if you have received this e-mail by mistake
and delete this e-mail from your system.

[David Seddon]

Pleasure! Thanks Maik.