Ocyan plugin oscar_communications
=================================

Invoice compatibility dependency
-------------------------------

This plugin depends on ``ocyan.plugin.oscar_invoices``, the first-party
MandelBlogStack compatibility distribution that supplies the historical
``oscar_invoices`` Django app. Do not install the legacy
``django-oscar-invoices`` distribution alongside it: both own the same Python
package and Django app label.

The supported runtime line is Python 3.12, Django 5.2, Django Oscar 4.1 and
Wagtail 7.

Installation
------------
Add `ocyan.plugin.oscar_communications` to your projects dependencies.

Usage
-----
All communications oscar does are defined in this plugin.

Options / Configuration
-----------------------

1. Attach an invoice to the order confirmation email
++++++++++++++++++++++++++++++++++++++++++++++++++++

In fendergui you can select to send order confirmation emails with an attached
invoice. If this is required, you should make sure to fill out the required
models in ``/manage/oscar_invoices/``. Make sure to use a LARGE logo because
the invoice pdf will be generated at quite high resolution.

You need to create 2 models:

1. One Business entity
2. One Business entity address (leave out anything you don't want on the invoice)

2. Send shipping confirmation email
+++++++++++++++++++++++++++++++++++

Select the ``Shipping email`` options in fendergui.
Whatever the user enters in the ``Reference`` field below the shipping event
dropdown, will be used as the tracking code, as long as it starts with ``http``.

If you want to enable the user to enter only the tracking code, you can set
the ``Tracking url template`` as well, it should be a django template with
one variable named ``code``::

    http://track-and-trace.com/?uid={{ code }}
    https://ups.com/{{ code}}/nl/?intl=true

whatever.

3. Work on email templates
++++++++++++++++++++++++++

It is very difficult to work on the *on disk* email templates because you can
not preview them directly. We've added some views that make this possible:

The *3217* in the url is an order number

    http://127.0.0.1:8000/en/admin/communications/order-email/3217/ORDER_PLACED/
    http://127.0.0.1:8000/en/admin/communications/order-email/3217/ORDER_PLACED.html
    http://127.0.0.1:8000/en/admin/communications/order-email/3217/ORDER_PLACED.txt


The superuser in the url is a user

    http://127.0.0.1:8000/en/admin/communications/user-email/superuser/REGISTRATION/
    http://127.0.0.1:8000/en/admin/communications/user-email/superuser/REGISTRATION.html
    http://127.0.0.1:8000/en/admin/communications/user-email/superuser/REGISTRATION.txt


Passing arguments to the url will give the email extra context.
For example the url below wil override the new_email with the email address that's passed in the url.

    http://127.0.0.1:8000/admin/communications/user-email/superuser/EMAIL_CHANGED/?new_email=viggo@mandelblog.com

In the following url we add a tracking_url to the context of the shipping email which will result in showing the tracking link.

    http://127.0.0.1:8000/admin/communications/order-email/100001/shipped/?tracking_url=https://mandelblog.com

4. Creating custom emails for a specific order status
++++++++++++++++++++++++++
To create a custom email for a specific order status, you'll have to do the following:
- Go to <domain>/manage/customer/communicationeventtype/ and click on the "add communication event type" button.
- At code and name, enter in the following: ```ORDER_STATUS_<some-order-status>```, so for example it would be ```ORDER_STATUS_CANCELLED``` for the status cancelled.
- Fill in the subject, txt template and html template.
- Done.

Inside the projects settings, you can set additional settings for this specific status email:
```python
# "CANCELLED" is an example, this can be any order status.
ORDER_STATUS_CANCELLED_BCC_ADMINS = True
ORDER_STATUS_CANCELLED_ATTACH_INVOICE = True
```

By default both these values are set to False.
