Rework email sending framework to be clearer

More comments added.

oscar/apps/checkout/mixins.py

@@ -256,7 +256,8 @@ class OrderPlacementMixin(CheckoutSessionMixin):
         try:
             event_type = CommunicationEventType.objects.get(code=code)
         except CommunicationEventType.DoesNotExist:
-            # No event in database, attempt to find templates for this type
+            # No event-type in database, attempt to find templates for this type
+            # and render them immediately to get the messages
             messages = CommunicationEventType.objects.get_and_render(code, ctx)
             event_type = None
         else:

oscar/apps/customer/abstract_models.py

@@ -29,39 +29,39 @@ class AbstractEmail(models.Model):
 
 
 class AbstractCommunicationEventType(models.Model):
-    
+
     # Code used for looking up this event programmatically.
     # eg. PASSWORD_RESET
     code = models.SlugField(_('Code'), max_length=128)
-    
+
     # Name is the friendly description of an event for use in the admin
     name = models.CharField(_('Name'), max_length=255)
-    
+
     # We allow communication types to be categorised
     ORDER_RELATED = _('Order related')
     USER_RELATED = _('User related')
     category = models.CharField(_('Category'), max_length=255, default=ORDER_RELATED)
-    
+
     # Template content for emails
     email_subject_template = models.CharField(_('Email Subject Template'), max_length=255, blank=True)
     email_body_template = models.TextField(_('Email Body Template'), blank=True, null=True)
     email_body_html_template = models.TextField(_('Email Body HTML Temlate'), blank=True, null=True,
         help_text=_("HTML template"))
-    
+
     # Template content for SMS messages
     sms_template = models.CharField(_('SMS Template'), max_length=170, blank=True, help_text=_("SMS template"))
-    
+
     date_created = models.DateTimeField(auto_now_add=True)
     date_updated = models.DateTimeField(auto_now=True)
-    
+
     objects = CommunicationTypeManager()
-    
+
     # File templates
     email_subject_template_file = 'customer/emails/commtype_%s_subject.txt'
     email_body_template_file = 'customer/emails/commtype_%s_body.txt'
     email_body_html_template_file = 'customer/emails/commtype_%s_body.html'
     sms_template_file = 'customer/sms/commtype_%s_body.txt'
-    
+
     class Meta:
         abstract = True
         verbose_name = _("Communication Event Type")
@@ -71,16 +71,11 @@ class AbstractCommunicationEventType(models.Model):
         """
         Return a dict of templates with the context merged in
 
-        We look first at the field templates but fail over to 
-        a set of file templates.  
+        We look first at the field templates but fail over to
+        a set of file templates that follow a conventional path.
         """
-        if ctx is None:
-            ctx = {}
-
-        # Pass base URL for serving images within HTML emails
-        ctx['static_base_url'] = getattr(settings, 'OSCAR_STATIC_BASE_URL', None)
-
         code = self.code.lower()
+
         # Build a dict of message name to Template instance
         templates = {'subject': 'email_subject_template',
                      'body': 'email_body_template',
@@ -89,14 +84,21 @@ class AbstractCommunicationEventType(models.Model):
         for name, attr_name in templates.items():
             field = getattr(self, attr_name, None)
             if field:
+                # Template content is in a model field
                 templates[name] = Template(field)
             else:
+                # Model field is empty - look for a file template
                 template_name = getattr(self, "%s_file" % attr_name) % code
                 try:
                     templates[name] = get_template(template_name)
                 except TemplateDoesNotExist:
                     templates[name] = None
-        
+
+        # Pass base URL for serving images within HTML emails
+        if ctx is None:
+            ctx = {}
+        ctx['static_base_url'] = getattr(settings, 'OSCAR_STATIC_BASE_URL', None)
+
         messages = {}
         for name, template in templates.items():
             messages[name] = template.render(Context(ctx)) if template else ''
@@ -105,13 +107,12 @@ class AbstractCommunicationEventType(models.Model):
         messages['subject'] = messages['subject'].replace("\n", "")
 
         return messages
-        
+
     def __unicode__(self):
-        return self.name   
-    
+        return self.name
+
     def is_order_related(self):
         return self.category == self.ORDER_RELATED
-    
+
     def is_user_related(self):
-        return self.category == self.USER_RELATED 
-    
+        return self.category == self.USER_RELATED

oscar/apps/customer/managers.py

@@ -2,10 +2,14 @@ from django.db import models
 
 
 class CommunicationTypeManager(models.Manager):
-    
+
     def get_and_render(self, code, context):
         """
-        Return a dictionary of rendered messages, ready for sending
+        Return a dictionary of rendered messages, ready for sending.
+
+        This method wraps around whether an instance of this event-type exists
+        in the database.  If not, then an instance is created on the fly and
+        used to generate the message contents.
         """
         try:
             commtype = self.get(code=code)