diff --git a/docs/Makefile b/docs/Makefile index b9c82fc..dde2ef1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -43,6 +43,7 @@ clean: readme: which pandoc &> /dev/null && pandoc ../README.md -o ../README.rst + which pandoc &> /dev/null && pandoc ../mailjet/contrib/django_mailjet/README.md -o ../mailjet/contrib/django_mailjet/README.rst html: readme $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/conf.py b/docs/conf.py index a0bdb85..ba9446e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,9 @@ import sys, os os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings' +from django.conf import settings +settings.configure() + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. diff --git a/docs/django.rst b/docs/django.rst new file mode 100644 index 0000000..56643f3 --- /dev/null +++ b/docs/django.rst @@ -0,0 +1,2 @@ +.. include:: ../mailjet/contrib/django_mailjet/README.rst + diff --git a/docs/index.rst b/docs/index.rst index a12dbd9..cab4b95 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 4 usage + django mailjet Indices and tables diff --git a/docs/mailjet.rst b/docs/mailjet.rst index 52336c4..a671a3e 100644 --- a/docs/mailjet.rst +++ b/docs/mailjet.rst @@ -56,4 +56,3 @@ Subpackages mailjet.contrib.django_mailjet - diff --git a/mailjet/contrib/django_mailjet/README.md b/mailjet/contrib/django_mailjet/README.md index 336819e..e113658 100644 --- a/mailjet/contrib/django_mailjet/README.md +++ b/mailjet/contrib/django_mailjet/README.md @@ -1,3 +1,6 @@ +Django integration +------------------ + Introduction ============ @@ -13,11 +16,11 @@ Installation In `settings.py`: - - set `MAILJET_LIST_NAME` and `MAILJET_LIST_LABEL`, note that - it may not contain non-alphanumeric characters, those are used as - defaults for `mailjet.contrib.django_mailjet.forms.SubscriptionForm`, - - add to `INSTALLED_APPS`: `mailjet.contrib.django_mailjet` - for templates to be loadable. +- set `MAILJET_LIST_NAME` and `MAILJET_LIST_LABEL`, note that + it may not contain non-alphanumeric characters, those are used as + defaults for `mailjet.contrib.django_mailjet.forms.SubscriptionForm`, +- add to `INSTALLED_APPS`: `mailjet.contrib.django_mailjet` + for templates to be loadable. Include `mailjet.contrib.django_mailjet.urls` in `urls.py`, ie.: diff --git a/mailjet/contrib/django_mailjet/forms.py b/mailjet/contrib/django_mailjet/forms.py index 8ecc90f..c56d99c 100644 --- a/mailjet/contrib/django_mailjet/forms.py +++ b/mailjet/contrib/django_mailjet/forms.py @@ -6,15 +6,22 @@ class SubscriptionForm(forms.Form): + """ Simple subscription form """ email = forms.EmailField() def __init__(self, list_name=None, list_label=None, *args, **kwargs): + """ + If `list_name` and `list_label` are None, then + `settings.MAILJET_LIST_NAME` and `settings.MAILJET_LIST_LABEL` will be + used. + """ self.list_name = list_name or settings.MAILJET_LIST_NAME self.list_label = list_label or settings.MAILJET_LIST_LABEL super(SubscriptionForm, self).__init__(*args, **kwargs) def clean_email(self): + """ Raise ValidationError if the contact exists. """ contacts = self.api.lists.contacts(id=self.list_id)['result'] for contact in contacts: @@ -25,14 +32,17 @@ def clean_email(self): return self.cleaned_data['email'] def save(self): + """ Call `add_contact()` """ self.add_contact() def add_contact(self): + """ Create a contact with using the email on the list. """ self.api.lists.addcontact(contact=self.cleaned_data['email'], id=self.list_id, method='POST') @property def api(self): + """ Get or create an Api() instance using django settings. """ api = getattr(self, '_api', None) if api is None: @@ -40,8 +50,10 @@ def api(self): return self._api + @property def list_id(self): + """ Get or create the list id. """ list_id = getattr(self, '_list_id', None) if list_id is None: diff --git a/mailjet/contrib/django_mailjet/templates/newsletter/base.html b/mailjet/contrib/django_mailjet/templates/django_mailjet/base.html similarity index 100% rename from mailjet/contrib/django_mailjet/templates/newsletter/base.html rename to mailjet/contrib/django_mailjet/templates/django_mailjet/base.html diff --git a/mailjet/contrib/django_mailjet/templates/newsletter/subscription.html b/mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_form.html similarity index 66% rename from mailjet/contrib/django_mailjet/templates/newsletter/subscription.html rename to mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_form.html index 8b3de0e..d899d49 100644 --- a/mailjet/contrib/django_mailjet/templates/newsletter/subscription.html +++ b/mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_form.html @@ -1,11 +1,10 @@ -{% extends 'newsletter/base.html' %} +{% extends 'django_mailjet/base.html' %} {% load i18n %} {% block body %}
- {{ form.email.errors }} - {{ form.email }} + {{ form.as_p }} {% csrf_token %}
diff --git a/mailjet/contrib/django_mailjet/templates/newsletter/subscription_success.html b/mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_success.html similarity index 73% rename from mailjet/contrib/django_mailjet/templates/newsletter/subscription_success.html rename to mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_success.html index dff32cd..2dee9be 100644 --- a/mailjet/contrib/django_mailjet/templates/newsletter/subscription_success.html +++ b/mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_success.html @@ -1,4 +1,4 @@ -{% extends 'newsletter/base.html' %} +{% extends 'django_mailjet/base.html' %} {% load i18n %} diff --git a/mailjet/contrib/django_mailjet/urls.py b/mailjet/contrib/django_mailjet/urls.py index 60332a9..c3fbea5 100644 --- a/mailjet/contrib/django_mailjet/urls.py +++ b/mailjet/contrib/django_mailjet/urls.py @@ -1,3 +1,13 @@ +""" +Defines basic urls. + +django_mailjet_subscription_form + Url to the basic form view: SubscriptionView. + +django_mailjet_subscription_success + Url to the basic success template. +""" + from django.conf.urls import patterns, url from django.views import generic @@ -5,8 +15,8 @@ urlpatterns = patterns('newsletter.views', url(r'subscription/$', views.SubscriptionView.as_view(), - name='newsletter_subscription'), + name='django_mailjet_subscription_form'), url(r'subscription/success/$', generic.TemplateView.as_view( - template_name='newsletter/subscription_success.html'), - name='newsletter_subscription_success'), + template_name='django_mailjet/subscription_success.html'), + name='django_mailjet_subscription_success'), ) diff --git a/mailjet/contrib/django_mailjet/views.py b/mailjet/contrib/django_mailjet/views.py index 8743f26..4a9ba40 100644 --- a/mailjet/contrib/django_mailjet/views.py +++ b/mailjet/contrib/django_mailjet/views.py @@ -7,10 +7,12 @@ class SubscriptionView(generic.FormView): + """ Basic subscription views """ form_class = SubscriptionForm - template_name = 'newsletter/subscription.html' - success_url = reverse_lazy('newsletter_subscription_success') + template_name = 'django_mailjet/subscription_form.html' + success_url = reverse_lazy('django_mailjet_subscription_success') def form_valid(self, form): + """ Call `form.save()` and super itself. """ form.save() return super(SubscriptionView, self).form_valid(form)