Newsletter plugin

Plugin for Django CMS QE providing newsletter. It allows users to subscribe (simply add email to database) and also possibility to sync with external sources like MailChimp.

Usage

Add plugin from section Generic called Newsletter subscription form.

To synchronize emails with MailChimp, generate a api_key on MailChimp and set it with MailChimp username (which you can find or set in profile settings) in admin interface in Сonstance. Then you can synchronize mailing lists in list of mailing lists in admin interface and use those lists in your plugin.

API

Django CMS

class cms_qe_newsletter.cms_plugins.NewsletterPlugin(model=None, admin_site=None)

Newsletter Django-CMS plugin. Allow add the form with subscriptions on a page.

form

alias of django.forms.widgets.NewsletterPluginForm

model

alias of cms_qe_newsletter.models.NewsletterPluginModel

class cms_qe_newsletter.models.NewsletterPluginModel(*args, **kwargs)

Configuration model for newsletter plugin. Allows to set: * Title * Mail lists on mailchimp to which subscribers will be added * Show or hide full name * Require full name or not

Parameters:

• id (AutoField) –
• path (CharField) –
• depth (PositiveIntegerField) –
• numchild (PositiveIntegerField) –
• placeholder_id (ForeignKey to Placeholder) –
• parent_id (ForeignKey to CMSPlugin) –
• position (PositiveSmallIntegerField) –
• language (CharField) –
• plugin_type (CharField) –
• creation_date (DateTimeField) –
• changed_date (DateTimeField) –
• cmsplugin_ptr_id (OneToOneField to CMSPlugin) –
• title (CharField) – The title of subscribes that will be shown to users
• fullname_show (BooleanField) –
• fullname_require (BooleanField) –
• mailing_lists (ManyToManyField) –

exception DoesNotExist

exception MultipleObjectsReturned

clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

Models

class cms_qe_newsletter.models.MailingList(*args, **kwargs)

Mailing list model which also synchronize with external services like Mailchimp. If external_id is not set then subscriber is not synchronized.

Parameters:

• id (BigAutoField) –
• name (CharField) –
• external_service (PositiveSmallIntegerField) –
• external_id (CharField) –

exception DoesNotExist

exception MultipleObjectsReturned

clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

class cms_qe_newsletter.models.Subscriber(*args, **kwargs)

Subscriber model which also synchronize with external services like Mailchimp. If external_id is not set then subscriber is not synchronized.

Parameters:

• id (BigAutoField) –
• mailing_list_id (ForeignKey to MailingList) –
• email (EmailField) –
• first_name (CharField) –
• last_name (CharField) –
• external_id (CharField) –

exception DoesNotExist

exception MultipleObjectsReturned

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

subscribe()

Called before save to create task to sync action with external service.

unsubscribe()

Called before delete to create task to sync action with external service.

class cms_qe_newsletter.models.SubscribeTask(*args, **kwargs)

Item for task queue for subscribing and unsubscribing members on the external service like Mailchimp. The queue can is processed by cms-qe-newsletter-sync command.

Parameters:

• id (BigAutoField) –
• mailing_list_id (ForeignKey to MailingList) –
• email (EmailField) –
• first_name (CharField) –
• last_name (CharField) –
• external_id (CharField) –
• type (PositiveSmallIntegerField) –
• created (DateTimeField) –
• attempts (PositiveSmallIntegerField) –
• last_error (TextField) –

exception DoesNotExist

exception MultipleObjectsReturned

should_process() → bool

Checks whether task should be tried to process. With less attempts it tries more often, with more attempts it waits more time to not overwhelm resources.

Views

cms_qe_newsletter.views.update_lists(request)

Download mailing lists from external services like Mailchimp.

Used in administration in custom button “Synchronize mailing list from external sources”.

Manage

class cms_qe_newsletter.management.commands.cms_qe_newsletter_sync.Command(stdout=None, stderr=None, no_color=False, force_color=False)

Command processes the queue to subscribing and unsubscribing on the external services. Usage of command with manage.py:

python -m manage.py cms_qe_newsletter_sync

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

Services

cms_qe_newsletter.external_services.sync.sync_mailing_lists()

Download mailing lists from external services like Mailchimp.

cms_qe_newsletter.external_services.sync.sync_task(task)

Processing task returning tuple of status (True for success, False for some failure and None for warnings) and message.

cms_qe_newsletter.external_services.sync.sync_tasks()

Processing tasks yielding same tuple as sync_task() function.

Mailchimp

class cms_qe_newsletter.external_services.mailchimp.client.MailChimpClient

Helper class to communicate with MailChimp.

get_lists() → collections.abc.Iterable[str]

Returns:List of lists with fields id and name.

subscribe(mailing_list_id, email, first_name, last_name) → None

Add a subscriber and return the id (subscriber_hash).

unsubscribe(mailing_list_id, subscriber_hash) → None

Remove a subscriber.

exception cms_qe_newsletter.external_services.mailchimp.client.MailchimpIsNotSetException