*******************************
collective.dancing blueprints
*******************************

.. contents::

This package contains several blueprints for collective.transmogrifier
pipelines, dedicated to the Plone product collective.dancing.

Installation
************

Requirements
------------
 * Singing & Dancing - http://pypi.python.org/pypi/collective.dancing
 * tested with Plone 3.3.4

See docs/INSTALL.txt for installation instructions.

Credits
*******

Makina Corpus

Detailed Documentation
**********************

ImportSubscriber section
==========================

A ImportSubscriber section allows you to add subscribers to a collective.dancing
channel.

The ImportSubscriber blueprint name is ``collective.blueprint.dancing.importsubscriber``.

To determine the subscriber informations, the ImportSubscriber section inspects
each item and looks for the keys email, channel-id and composer-id, as described
below. Any item missing the ``email`` keys will be skipped.

If the key ``channel-id`` is missing, the ImportSubscriber section looks for the
option ``default-channel-id``. This option defaults to ``default-channel``.

If the key ``composer-id`` is missing, the ImportSubscriber section looks for
the option ``default-composer-id``. This option defaults to ``html``.

For each key, the corresponding information will be found among the following:

* ``_collective.blueprint.dancing.importsubscriber_[sectionname]_[key]``
* ``_collective.blueprint.dancing.importsubscriber_[key]``
* ``_[sectionname]_[key]``
* ``_[key]``

where ``[sectionname]`` is replaced with the name given to the current section,
and ``[key]`` is replaced by ``email``, ``channel-id`` or ``composer-id``. This
allows you to target the right section precisely if needed.

Alternatively, you can specify what key to use for each information by
specifying the``[key]-key`` option, which should be a list of keys to try (one
key per line; use a ``re:`` or ``regexp:`` prefix to specify regular
expressions).

    >>> import pprint

    >>> importsubscriber = """
    ... [transmogrifier]
    ... pipeline =
    ...     source
    ...     importsubscriber
    ...     importsubscriber2
    ...     printer
    ...
    ... [source]
    ... blueprint = collective.blueprint.dancing.tests.importsubscribersource
    ...
    ... [importsubscriber]
    ... blueprint = collective.blueprint.dancing.importsubscriber
    ...
    ... [importsubscriber2]
    ... blueprint = collective.blueprint.dancing.importsubscriber
    ... default-channel-id=mychannel
    ... default-composer-id=mycomposer
    ...
    ... [printer]
    ... blueprint = collective.transmogrifier.sections.tests.pprinter
    ... """
    >>> registerConfig(u'collective.blueprint.dancing.tests.importsubscriber',
    ...                importsubscriber)

    >>> transmogrifier(u'collective.blueprint.dancing.tests.importsubscriber')
    [('_email', 'foo@foo.com')]
    [('_email', 'bar@bar.com')]
    [('_email', 'existing@email.com')]

    >>> pprint.pprint(plone.subscribers)
    (u'foo@foo.com -channel:default-channel - composer:html',
     u'foo@foo.com -channel:mychannel - composer:mycomposer',
     u'bar@bar.com -channel:default-channel - composer:html',
     u'bar@bar.com -channel:mychannel - composer:mycomposer')


Change History
**************

(name of developer listed in brackets)

0.1 - 2009-02-10
================

- Added ImportSubscriber section. See importsubscriber.txt.
  [sylvainb]


Download
********
