Metadata-Version: 2.1
Name: tgapp-mailtemplates
Version: 0.15.0
Summary: Email template management for web applications
Home-page: https://github.com/axant/tgapp-mailtemplates
Author: Marco Bosio
Author-email: marco.bosio@axant.it
License: UNKNOWN
Description: .. image:: https://travis-ci.org/axant/tgapp-mailtemplates.svg?branch=master
           :target: https://travis-ci.org/axant/tgapp-mailtemplates
        
        About mailtemplates
        -------------------------
        
        mailtemplates is a Pluggable application for TurboGears2.
        
        mailtemplates provides a dashboard meant for managers of your website (whoever has the ``mailtemplates`` permission) allowing them to customize the templates of the email that are sent from your application.
        
        the templates are stored in a database and both ``sqlalchemy`` and ``ming`` are supported.
        
        kajiki is the template engine used.
        
        Installing
        -------------------------------
        
        mailtemplates can work with ``tgext.asyncjob`` or ``tgext.asyncjob``
        you can choose by installing with the right bundle::
        
            pip install "mailtemplates[asyncjob]"
        
        or::
        
            pip install "mailtemplates[celery]"
        
        if you just want to send emails in a syncronous context then install the base package and plug with ``async_sender`` set to ``None``
        
        Plugging mailtemplates
        ----------------------------
        
        In your application *config/app_cfg.py* import **plug**::
        
            from tgext.pluggable import plug
        
        Then at the *end of the file* call plug with mailtemplates::
        
            plug(base_config, 'mailtemplates')
        
        For configure your default language for email templates, add the ISO 3166-2 code as parameter of the `plug` call::
        
             plug(base_config, 'mailtemplates', default_language='IT')
        
        If not specified, 'EN' will be the default language for you app.
        
        If you intend to use tgext.celery then plug and configure it **before** plugging mailtemplates with ``async_sender`` option::
        
            plug(base_config, 'mailtemplates', async_sender='tgext.celery')
        
        and in your ``.ini`` file add under ``celery.CELERY_INCLUDE`` ``mailtemplates.lib.celery_tasks``::
        
            celery.CELERY_INCLUDE = myapp.lib.celery.tasks mailtemplates.lib.celery_tasks
        
        
        You will be able to access the plugged application at
        *http://localhost:8080/mailtemplates*.
        
        Sending emails
        --------------
        
        access to the dashboard and create a mail model, then you can use::
        
            from mailtemplates.lib import send_email
            send_email(
              recipients=['address@example.com'],
              sender=config.get('mail.username'),
              mail_model_name='test',
              data=dict(test='test string'),
              send_async=True,
            )
        
        in your controllers to actually send the email.
        
        details of params of ``send_email``
        
        - recipients: An array representing the email address of the recipient of the email
        - sender: A string representing the email address of the sender of the email
        - mail_model_name: The name of the MailModel representing an email
        - translation: The language of a TemplateTranslation (e.g. 'EN'). If omitted, the
          default language provided while plugging mailtemplates is used
        - data: A dictionary representing the variables used in the email template, like ${name}
        - send_async: The email will sent asynchronously if this flag is True
        
        Note on send_async
        --------------------
        
        if you are already in an asyncronous context then you can't use tgext.asyncjob with send_async=True,
        but you're already in an asyncronous context, so you can just use send_async=False.
        If you really need to send email asynchronously from an already asyncronous context, then use tgext.celery
        
Keywords: turbogears2.application
Platform: UNKNOWN
Provides-Extra: testing
Provides-Extra: asyncjob
Provides-Extra: celery
