salmon/view.py

   1 """
   2 These are helper functions that make it easier to work with either Jinja2 or
   3 Mako templates.  You MUST configure it by setting salmon.view.LOADER to one of
   4 the template loaders in your boot module. Remember to install Jinja2 or Mako
   5 first though!
   6
   7 After that these functions should just work.
   8 """
   9 from salmon import mail
  10
  11 LOADER = None
  12
  13
  14 def load(template):
  15     """
  16     Uses the registered loader to load the template you ask for.
  17     It assumes that your loader works like Jinja2 or Mako in that
  18     it has a LOADER.get_template() method that returns the template.
  19     """
  20     if LOADER is None:
  21         raise TypeError("You haven't set salmon.view.LOADER to a loader yet.")
  22     return LOADER.get_template(template)
  23
  24
  25 def render(variables, template):
  26     """
  27     Takes the variables given and renders the template for you.
  28     Assumes the template returned by load() will have a .render()
  29     method that takes the variables as a dict.
  30
  31     Use this if you just want to render a single template and don't
  32     want it to be a message.  Use render_message if the contents
  33     of the template are to be interpreted as a message with headers
  34     and a body.
  35     """
  36     return load(template).render(variables)
  37
  38
  39 def respond(variables, Body=None, Html=None, **kwd):
  40     """
  41     Does the grunt work of cooking up a MailResponse that's based
  42     on a template.  The only difference from the salmon.mail.MailResponse
  43     class and this (apart from variables passed to a template) are that
  44     instead of giving actual Body or Html parameters with contents,
  45     you give the name of a template to render.  The kwd variables are
  46     the remaining keyword arguments to MailResponse of From/To/Subject.
  47
  48     For example, to render a template for the body and a .html for the Html
  49     attachment, and to indicate the From/To/Subject do this::
  50
  51         msg = view.respond(locals(), Body='template.txt',
  52                           Html='template.html',
  53                           From='test@test.com',
  54                           To='receiver@test.com',
  55                           Subject='Test body from "%(person)s".')
  56
  57     In this case you're using locals() to gather the variables needed for
  58     the 'template.txt' and 'template.html' templates.  Each template is
  59     setup to be a text/plain or text/html attachment.  The From/To/Subject
  60     are setup as needed.  Finally, the locals() are also available as
  61     simple Python keyword templates in the From/To/Subject so you can pass
  62     in variables to modify those when needed (as in the %(person)s in Subject).
  63     """
  64
  65     if Body is None and Html is None:
  66         raise TypeError("You need to give either the Body or Html template of the mail.")
  67
  68     for key in kwd:
  69         kwd[key] = kwd[key] % variables
  70
  71     msg = mail.MailResponse(**kwd)
  72
  73     if Body:
  74         msg.Body = render(variables, Body)
  75
  76     if Html:
  77         msg.Html = render(variables, Html)
  78
  79     return msg
  80
  81
  82 def attach(msg, variables, template, filename=None, content_type=None,
  83            disposition=None):
  84     """
  85     Useful for rendering an attachment and then attaching it to the message
  86     given.  All the parameters that are in salmon.mail.MailResponse.attach
  87     are there as usual.
  88     """
  89     data = render(variables, template)
  90
  91     msg.attach(filename=filename, data=data, content_type=content_type,
  92                disposition=disposition)