<commit_before>========
Cookbook
========

Categorized contact form
------------------------

Although the ``category`` field was removed from the default form class in
1.0, you can bring it back to your form using the following subclass::

    from envelope.forms import ContactForm

    from django import forms
    from django.utils.translation import ugettext_lazy as _


    class CategorizedContactForm(ContactForm):
        CATEGORY_CHOICES = (
            ('', _("Choose")),
            (10, _("A general question regarding the website")),
            # ... any other choices you can imagine
            (None, _("Other")),
        )
        category = forms.ChoiceField(label=_("Category"), choices=CATEGORY_CHOICES)

        def __init__(self, *args, **kwargs):
            """
            Category choice will be rendered above the subject field.
            """
            super(CategorizedContactForm, self).__init__(*args, **kwargs)
            self.fields.keyOrder = [
                'sender', 'email', 'category', 'subject', 'message',
            ]

        def get_context(self):
            """
            Adds full category description to template variables in order
            to display the category in email body.
            """
            context = super(CategorizedContactForm, self).get_context()
            context['category'] = self.get_category_display()
            return context

        def get_category_display(self):
            """
            Returns the displayed name of the selected category.
            """
            try:
                category = int(self.cleaned_data['category'])
            except (AttributeError, ValueError, KeyError):
                category = None
            return dict(self.CATEGORY_CHOICES).get(category)
<commit_msg>django-braces example in the cookbook.<commit_after>========
Cookbook
========

Success and error messages
--------------------------

Starting from release 1.0, :class:`envelope.views.ContactView` does not set any
`messages`_ since these were customized by most users anyway. We encourage
you to use the excellent `django-braces`_ app which provides a
`FormMessagesMixin`_ designed specifically for this purpose.

.. _`messages`: https://docs.djangoproject.com/en/dev/ref/contrib/messages/
.. _`django-braces`: https://github.com/brack3t/django-braces
.. _`FormMessagesMixin`: http://django-braces.readthedocs.org/en/latest/form.html#formmessagesmixin

The following example shows how to add the mixin to ``ContactView``::

    from braces.views import FormMessagesMixin
    from envelope.views import ContactView

    from django.utils.translation import ugettext_lazy as _


    class MyContactView(FormMessagesMixin, ContactView):
        form_invalid_message = _(u"There was en error in the contact form.")
        form_valid_message = _(u"Thank you for your message.")

Categorized contact form
------------------------

Although the ``category`` field was removed from the default form class in
1.0, you can bring it back to your form using the following subclass::

    from envelope.forms import ContactForm

    from django import forms
    from django.utils.translation import ugettext_lazy as _


    class CategorizedContactForm(ContactForm):
        CATEGORY_CHOICES = (
            ('', _("Choose")),
            (10, _("A general question regarding the website")),
            # ... any other choices you can imagine
            (None, _("Other")),
        )
        category = forms.ChoiceField(label=_("Category"), choices=CATEGORY_CHOICES)

        def __init__(self, *args, **kwargs):
            """
            Category choice will be rendered above the subject field.
            """
            super(CategorizedContactForm, self).__init__(*args, **kwargs)
            self.fields.keyOrder = [
                'sender', 'email', 'category', 'subject', 'message',
            ]

        def get_context(self):
            """
            Adds full category description to template variables in order
            to display the category in email body.
            """
            context = super(CategorizedContactForm, self).get_context()
            context['category'] = self.get_category_display()
            return context

        def get_category_display(self):
            """
            Returns the displayed name of the selected category.
            """
            try:
                category = int(self.cleaned_data['category'])
            except (AttributeError, ValueError, KeyError):
                category = None
            return dict(self.CATEGORY_CHOICES).get(category)

{'fraction_non_alphanumeric': 0.11257848019051743, 'fraction_numerical': 0.0023814678501840225, 'mean_word_length': 2.2905982905982905, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7273873', 'n_tokens_mistral': 1180, 'n_tokens_neox': 1139, 'n_words': 358}