Package: boletin
.. contents::================================Boletin, a Django newsletter app================================Boletin is a generic newsletter application for Django projects, which allowsfor automatically generating and sending newsletters, with optional humanreviewing process if so desired.Boletin means "bulletin" or "newsletter" in Spanish.Features========* Complete subscription/desubscription process, with confirmation emails.* Completely decoupled, no need to modify your own code to use it, only``settings.py`` and redefine templates as needed.* Newsletters in HTML and plain text in the same email.* Three different periods: daily, weekly and monthly newsletters, easilyconfigurable.* Integrated with Django's admin.* Optional reviewing process (in the admin).* Cron scripts included.* Unit tests included.Installation============1. Include ``boletin`` in ``settings.INSTALLED_APPS``.2. Create DB tables with ``python manage.py syncdb``.3. Configure settings (see `Configuration`_ section).4. Install cron scripts in the system's cron installation for automatednewsletter creation and (optionally) automated sending.See "Cron configuration" below for more information.Configuration=============You can configure many aspects of the behavior of the application viasettings variables. Mandatory variables are marked with (*).NEWSLETTER_EMAIL (*)--------------------Email address from where to send the newsletter. Newsletter recipientswill see this address in the e-mail message "From" field.Default: None, it's mandatory.Example::NEWSLETTER_EMAIL = 'newsletter@example.com'NEWSLETTER_REVIEWER_EMAIL-------------------------Email address for the newsletter reviewer. When a newsletter is generated,an e-mail will be sent to this address prompting to the revision of thenewsletter.Default: None.Example::NEWSLETTER_REVIEWER_EMAIL = 'reviewer@example.com'NEWSLETTER_REVIEWER_ADMIN_LINK------------------------------Relative URL suffix for newsletter objects in the admin application. The sitedomain and the newsletter id will be, respectively, prepended and appended tothis string. This setting is optional; if not defined, the e-mail message tothe reviewer will not include a link to the admin application.Default: None.Example::NEWSLETTER_REVIEWER_ADMIN_LINK = '/admin/boletin/newsletter/'NEWSLETTER_GENERATOR_FUNCTION (*)---------------------------------This variable is a string pointing to a function inside the project whichwill be responsible for retrieving content for inclusion in each newsletter.The function must receive two parameters: ``from_date`` and ``to_date``, which definethe datetime range of the newsletter being created.Default: None, it's mandatory.Example::NEWSLETTER_GENERATOR_FUNCTION = 'portal.newsletter.generate_content'And the content of portal/newsletter.py::from app1.models import FooModelfrom app2.models import BarModeldef generate_content(from_date, to_date):app1 = FooModel.objects.filter(date__gte=from_date, date__lte=to_date)app2 = BarModel.objects.filter(date__gte=from_date, date__lte=to_date)return {'app1': app1, 'app2': app2}NEWSLETTER_PERIODS------------------Available newsletter periods in the project. It's a list with one or more of'D' (daily), 'W' (weekly) and 'M' (monthly).Default: ``['W']`` (only weekly newsletter)Example::NEWSLETTER_PERIODS = ['D', 'W', 'M'] # daily, weekly and monthly newslettersManagement commands===================Three management commands are included:* ``createnewsletter``* ``sendnewsletter``* ``shownewsletter``Createnewsletter----------------Generate a new newsletter for the given period (daily, weekly or monthly), bothin HTML and plain text. It renders the `templates`_ ``newsletter_email.html``and ``newsletter_email.txt``.Options:* ``-d``, ``--daily``: daily period.* ``-w``, ``--weekly``: weekly period.* ``-m``, ``--monthly``: monthly period.* ``-p``, ``--print``: print the created newsletter to stdout.* ``-r``, ``--regenerate``: create the newsletter again if it already exists.One and only one of ``-d``, ``-w`` or ``-m`` must be given.Sendnewsletter--------------Send newsletters to subscribers.Options:* ``-n``, ``--newsletter``: send only the newsletter with the given ID.* ``-f``, ``--force-unreviewed``: send unreviewed newsletters.Without parameters all **reviewed** newsletters with pending sendings aresent. Use the ``-f`` switch to send unreviewed newsletters (useful for acompletely automatic newsletter system). Use the ``-n`` switch to send anspecific newsletter. The `shownewsletters`_ command should be useful to seecreated newsletters, their IDs and pending statuses.Shownewsletters---------------Show stored newsletters, with their object ID (*different than their newsletternumber*) and pending status.Options:* ``-p``, ``--only-pending``: show only newsletters with pending sendings.Templates=========Default templates are provided for the subscription and unsubscription process,but you should redefine at least ``newsletter_email.txt`` and``newsletter_email.html``.  You can redefine any template creating a newsletterdir inside your templates directory, copying the app template inside it andchanging that copy.The available templates are:* ``newsletter_base.html``: base template for the subscription andunsubscription process, except email templates.* ``newsletter_confirm_email.txt``: email template for confirming subscription.* ``newsletter_confirm.html``: page telling the user the subscriptionconfirmation email has been sent to her email address.* ``newsletter_email.html``: email template of a newsletter in email format.You should redefine this depending on the context returned by the``NEWSLETTER_GENERATOR_FUNCTION``.* ``newsletter_email.txt``: same as newsletter_email.html, but in plain text.* ``newsletter.html``: subscription/unsubscription form.* ``newsletter_success.html``: subscription success page.* ``newsletter_unsubscription_confirm_email.txt``: same asnewsletter_confirm_email, but for unsubscription.* ``newsletter_unsubscription_confirm.html``: same as newsletter_confirm,but for unsubscription.* ``newsletter_unsubscription_success.html``: same as newsletter_success,but for unsubscription.Cron configuration==================There are several crontab files inside the ``cron`` directory that you cansimply include in your system-wide cron configuration to have automaticnewsletter creation and/or sending. The ``createnewsletter`` and``sendnewsletter`` commands are smart enough to ignore petitions for unallowedperiods (i.e. not configured in `NEWSLETTER_PERIODS`_).Development===========You can get the last bleeding edge version of boletin by doing a checkout oftrunk in its subversion repository::svn checkout https://svnpub.yaco.es/djangoapps/boletin/trunk boletinBug reports, patches and suggestions are more than welcome. Just putthem in our Trac system and use the 'boletin' component when you filltickets::https://tracpub.yaco.es/djangoapps/Changes=======0.5.1 (2009-05-20)------------------- Fixed several bugs that rendered the application unusable. They all came fromthe fact that the application changed name just before release, and some importswere left unchanged.0.5.0 (2009-05-18)------------------- Initial release