Metadata-Version: 2.4
Name: ocyan.plugin.oscar_communications
Version: 2.0.6
Summary: Oscar communications and invoice notification integration.
Author-email: Mandel <info@mandelblog.com>
License-Expression: LicenseRef-Proprietary
Classifier: Framework :: Ocyan
Classifier: Environment :: Plugins
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: ocyan.core<2,>=1.2.13
Requires-Dist: Django<5.3,>=5.2
Requires-Dist: django-oscar<4.2,>=4.1
Requires-Dist: ocyan.plugin.oscar_invoices==0.3.1
Requires-Dist: django-compressor
Requires-Dist: ocyan.plugin.oscar<3,>=2.0.5
Requires-Dist: ocyan.plugin.oscar_shipping<2,>=1.3.2
Requires-Dist: ocyan.plugin.oscar_order<3,>=2.0.2
Requires-Dist: ocyan.plugin.wagtail_utils
Requires-Dist: wagtail<8,>=7.4
Requires-Dist: WeasyPrint
Requires-Dist: django-sequences
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: ruff; extra == "test"
Requires-Dist: build; extra == "test"

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.

Static asset lifecycle
----------------------

Dashboard communication records are not populated automatically during
``migrate``. Rendering their HTML templates requires the collected
``communications/email.scss`` asset, while migrations must remain independent
of static-file storage. After running ``collectstatic`` with the intended
project settings, populate records explicitly with
``manage.py populate_dashboard_emails``. Projects that intentionally seed
these records during migration can opt in with
``OCYAN_OSCAR_COMMUNICATIONS_POPULATE_DASHBOARD_EMAILS_ON_MIGRATE = True``;
their settings must provide a valid, already-collected static manifest.

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.
