Metadata-Version: 1.1
Name: django-emailmessagetemplates
Version: 0.1.2
Summary: A Django app that allows users to edit email content with an easy-to-integrate developer API.
Home-page: https://github.com/mcoconnor/django-emailmessagetemplates
Author: Michael OConnor
Author-email: michael@mcoconnor.net
License: BSD
Description: Django Email Templates
        ======================
        
        © 2016 Michael O’Connor, http://www.mcoconnor.net
        https://github.com/mcoconnor/django-emailmessagetemplates
        
        In many cases, users will want to be able to edit the emails sent by
        your application without having to go to developers to change hard-coded
        email content. This package provides a Django app that allows users to
        edit email content with an easy-to-integrate developer API.
        
        Requirements
        ------------
        
        Django Email Templates supports versions 1.4-1.9 of Django under Python
        2.6 and 2.7.
        
        | |Build Status| |Coverage Status|
        
        -  `django-appconf`_ is the only external dependency.
        -  `html2text`_ is required to use the text autogeneration
           functionality.
        -  `South`_ is supported but not required (for Django<1.7).
        
        Installation
        ------------
        
        Django Email Templates is a standard Django app. 
        
        To add it to a project, just include ``'emailmessagetemplates'`` in the 
        ``INSTALLED_APPS`` section of your ``settings.py`` file.
        
        If you would like to use text version autogeneration for HTML templates, 
        include the `text_autogen` extras in your install (e.g. 
        ``pip install django-emailmessagetemplates[text_autogen]``) or ensure 
        you've installed ``html2text`` separately.
        
        Usage
        -----
        
        The central piece of functionality in this app is the
        EmailMessageTemplate class, which is a Django model that also inherits
        from Django’s ``EmailMultiAlternatives`` class. Usage is derived from
        its parents: to select a template to send, query for it as a model. To
        send an email, first populate the message with the template context,
        recipients, and other data, and then call the ``send`` method. For
        example:
        
        ::
            from emailmessagetemplates.models import EmailMessageTemplate
            
            t = EmailMessageTemplate.objects.get(name='Hello World')
            t.context = {'a':'hello','b':'world'}
            t.to = ['michael@mcoconnor.net',]
            t.attach_file('/docs/Hello.pdf')
            t.send()
        
        Email templates support the same attributes that
        ``EmailMultiAlternatives``\ s do, including ``to``, ``cc``, ``bcc``,
        ``from_email``, ``headers``, and ``attachments``.
        
        HTML/Multipart Messages
        -----------------------
        
        Django Email Templates can either send plain text emails or HTML
        formatted messages with plain-text alternative content. To enable HTML
        emails, the ``EMAILMESSAGETEMPLATES_ALLOW_HTML_MESSAGES`` setting must
        be set to ``True``, and the ``type`` field on the
        ``EmailMessageTemplate`` instance must be set to ‘HTML’. Plain text
        alternative can either be auto-generated from the rendered HTML body
        content (via the HTML2Text library, which converts the message to
        Markdown) or by manually maintaining a separate plain text body
        template.
        
        Convenience Functions
        ---------------------
        
        The email convenience functions provided by Django replicated for
        message templates. These include ``send_mail``, ``send_mass_mail``,
        ``mail_admins``, ``mail_managers`` and are used similarly:
        
        ::
            from emailmessagetemplates.utils import send_mail, send_mass_mail, \
                mail_admins, mail_managers
            
            send_mail(name, related_object=None, context={}, from_email=None,
                      recipient_list=[], fail_silently=False, auth_user=None,
                      auth_password=None, connection=None)
        
            send_mass_mail(name, related_object=None, datatuple=(), fail_silently=False,
                           auth_user=None, auth_password=None, connection=None)  
        
            mail_admins(name, related_object=None, context={}, fail_silently=False,
                        connection=None)
                            
            mail_managers(name, related_object=None, context={}, fail_silently=False,
                          connection=None)
        
        Differences from ``EmailMultiAlternatives``
        -------------------------------------------
        
        While ``EmailMessageTemplate`` behaves like Django’s
        ``EmailMultiAlternatives`` in many ways, there are some differences:
        
        -  Subject and body values cannot be set directly; instead they’re
           constructed from templates saved in the model rendered against the
           specified context
        -  If ``from_email`` is not specified when a message is prepared, the
           value defaults first to the ``sender`` set on the template model,
           then to the ``EMAILMESSAGETEMPLATES_DEFAULT_FROM_EMAIL`` setting
        -  Values required by the message (e.g the recipients) cannot be set in
           the ``EmailMessageTemplate`` constructor like they are for
           ``EmailMessage`` (since normally you will retrieve an existing model
           instance rather than constructing one). Instead, they must be set
           individually on the instance.
        -  An HTML alternative is automatically added for messages with an HTML
           type (when HTML messages are permitted by application settings). A
           plain text alternative is also provided, either generated from a
           separate template or autogenerated from the HTML content.
        
        Settings
        --------
        
        **EMAILMESSAGETEMPLATES_DEFAULT_FROM_EMAIL**
        
        Default: The ``DEFAULT_FROM_EMAIL`` value from your project’s settings.
        
        The default email address to use for message sent from templates. This
        is can be overridden on a per-template basis by setting the ``sender``
        field on the template model instance. It can be overridden on a
        per-email basis by setting the ``from_email`` attribute on an
        instantiated ``EmailMessageTemaple`` object or using the ``from_email``
        argument to any of the convenience functions.
        
        **EMAILMESSAGETEMPLATES_ALLOW_HTML_MESSAGES**
        
        Default: False
        
        If true, templates can produce HTML-formatted messages and provide
        plain-text alternative content. Enabling this option will display
        additional fields in the Django admin form and will enable HTML
        generation for templates that have a ``type`` of ``text/html``.
        
        Migrations
        ----------
        
        Django-emailmessagetemplates provides database migrations using both
        South and Django’s built-in migration system. You can apply the
        migrations as follows:
        
        **If you’re using Django >= 1.7 and the built-in migration system:**
        
        ::
        
            python manage.py migrate emailmessagetemplates   
        
        **If you’re using Django < 1.7 and South >= 1.0:**
        
        ::
        
            python manage.py syncdb
            python manage.py migrate emailmessagetemplates   
        
        **If you’re using Django < 1.7 and South < 1.0:**
        
        Include ``emailmessagetemplates`` in your ``SOUTH_MIGRATION_MODULES``
        setting, like
        
        ::
        
            SOUTH_MIGRATION_MODULES = {
                'emailmessagetemplates': 'emailmessagetemplates.south_migrations',
            }
        
        The run the standard migration commands:
        
        ::
        
            python manage.py syncdb
            python manage.py migrate emailmessagetemplates   
        
        .. _django-appconf: https://pypi.python.org/pypi/django-appconf/0.6
        .. _html2text: https://pypi.python.org/pypi/html2text
        .. _South: http://south.aeracode.org/
        
        .. |Build Status| image:: https://travis-ci.org/mcoconnor/django-emailmessagetemplates.svg?branch=master
           :target: https://travis-ci.org/mcoconnor/django-emailmessagetemplates
        .. |Coverage Status| image:: https://coveralls.io/repos/mcoconnor/django-emailmessagetemplates/badge.svg?branch=master
           :target: https://coveralls.io/r/mcoconnor/django-emailmessagetemplates?branch=master
        
        
        
        History
        -------
        
        0.1.2 (2016-5-6)
        ++++++++++++++++++
        
        * Update for Django>=1.9
        
        0.1.1 (2015-3-19)
        ++++++++++++++++++
        
        * Fix packaging errors
        * Add South initial migration
        
        0.1.0 (2015-3-18)
        ++++++++++++++++++
        
        * First release on PyPI.
Keywords: django,email,template
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Operating System :: OS Independent
Classifier: Environment :: Web Environment
