<commit_before>=========================
The MailFactory Interface
=========================

In daily work email branding is important because it will call your
custommer to action.

MailFactory comes with a little tool that helps you to test your emails.

To do that, we generate a Django Form so that you may provide a context for
your email.

Here's how you can customize your administration form.


Enabling MailFactory administration
===================================

You just need to enable the urls:

:file:`project/urls.py`:

.. code-block:: python

    urlpatterns = (
        # ...
        url(r'^admin/mails/', include('mail_factory.urls')),
        url(r'^admin/', include(admin.site.urls)),
        # ...
    )

Then you can connect to `/admin/mails/
<http://127.0.0.1:8000/admin/mails/>`_ to try out your emails.


Registering a specific form
===========================

These two calls are equivalent:

.. code-block:: python

    from mail_factory import factory, BaseMail


    class InvitationMail(BaseMail):
        template_name = "invitation"
        params = ['user']

    factory.register(InvitationMail)

.. code-block:: python

    from mail_factory import factory, MailForm, BaseMail


    class InvitationMail(BaseMail):
        template_name = "invitation"
        params = ['user']

    factory.register(InvitationMail, MailForm)


Creating a custom MailForm
==========================

We may also want to build a very specific form for our email.

Let's say we have a *share this page* email, with a custom message:

.. code-block:: python

    from mail_factory import factory, BaseMail, MailForm


    class SharePageMail(BaseMail):
        template_name = "share_page"
        params = ['user', 'message', 'date']


    class SharePageMailForm(MailForm):
        user = forms.ModelChoiceField(queryset=User.objects.all())
        message = forms.CharField(widget=forms.Textarea)
        date = forms.DateTimeField()

        class Meta:
            mail_class = SharePageMail


    factory.register(SharePageMail, SharePageMailForm)


Creating your application custom MailForm
=========================================

Let's create a project wide BaseMailForm that uses a ``ModelChoiceField`` on
the ``auth.models.User`` each time a ``user`` param is needed in the email.
<commit_msg>#1 - Add initial data documentation<commit_after>=========================
The MailFactory Interface
=========================

In daily work email branding is important because it will call your
custommer to action.

MailFactory comes with a little tool that helps you to test your emails.

To do that, we generate a Django Form so that you may provide a context for
your email.

Here's how you can customize your administration form.


Enabling MailFactory administration
===================================

You just need to enable the urls:

:file:`project/urls.py`:

.. code-block:: python

    urlpatterns = (
        # ...
        url(r'^admin/mails/', include('mail_factory.urls')),
        url(r'^admin/', include(admin.site.urls)),
        # ...
    )

Then you can connect to `/admin/mails/
<http://127.0.0.1:8000/admin/mails/>`_ to try out your emails.


Registering a specific form
===========================

These two calls are equivalent:

.. code-block:: python

    from mail_factory import factory, BaseMail


    class InvitationMail(BaseMail):
        template_name = "invitation"
        params = ['user']

    factory.register(InvitationMail)

.. code-block:: python

    from mail_factory import factory, MailForm, BaseMail


    class InvitationMail(BaseMail):
        template_name = "invitation"
        params = ['user']

    factory.register(InvitationMail, MailForm)


Creating a custom MailForm
==========================

We may also want to build a very specific form for our email.

Let's say we have a *share this page* email, with a custom message:

.. code-block:: python

    from mail_factory import factory, BaseMail, MailForm


    class SharePageMail(BaseMail):
        template_name = "share_page"
        params = ['user', 'message', 'date']


    class SharePageMailForm(MailForm):
        user = forms.ModelChoiceField(queryset=User.objects.all())
        message = forms.CharField(widget=forms.Textarea)
        date = forms.DateTimeField()

        class Meta:
            mail_class = SharePageMail


    factory.register(SharePageMail, SharePageMailForm)


Define form initial data
========================

You can define ``Meta.initial`` to automatically provide a context for
your mail.

.. code-block:: python

    # -*- coding: utf-8 -*-
    from django.conf import settings
    from django.core.urlresolvers import reverse_lazy as reverse
    
    from mail_factory import factory, MailForm
    from postbox.core.mails import BaseMail
    
    import datetime
    import uuid
    from django import forms
    
    
    class ShareBucketMail(BaseMail):
        template_name = 'share_bucket'
        params = ['first_name', 'last_name', 'comment', 'expiration_date',
                  'activation_url']
    
    
    def activation_url():
        return '%s%s' % (
            settings.SITE_URL, reverse('share:index',
                                       args=[str(uuid.uuid4()).replace('-', '')]))


    class ShareBucketForm(MailForm):
        expiration_date = forms.DateField()
    
        class Meta:
            initial = {'first_name': 'Thibaut',
                       'last_name': 'Dupont',
                       'comment': 'I shared with you documents we talked about.',
                       'expiration_date': datetime.date.today,
                       'activation_url': activation_url}
            mail_class = ShareBucketMail
    
    factory.register(ShareBucketMail, ShareBucketForm)

Then the mail form will be autopopulated with this data.


Creating your application custom MailForm
=========================================

Let's create a project wide BaseMailForm that uses a ``ModelChoiceField`` on
the ``auth.models.User`` each time a ``user`` param is needed in the email.

{'fraction_non_alphanumeric': 0.14806902218570256, 'fraction_numerical': 0.0037797863599013967, 'mean_word_length': 3.101078167115903, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1519723', 'n_tokens_mistral': 1677, 'n_tokens_neox': 1563, 'n_words': 536}