Metadata-Version: 1.0
Name: collective.dancing
Version: 0.5.1
Summary: The all-singing all-dancing newsletter product for Plone.
Home-page: http://plone.org/products/dancing
Author: Daniel Nouri, Thomas Clement Mogensen and contributors
Author-email: singing-dancing@googlegroups.com
License: GPL
Description: =================
        Singing & Dancing
        =================
        
        .. contents::
        
        What is it?
        ===========
        
        *Singing & Dancing* is the next generation newsletter Product for
        Plone.  It's an out of the box solution that works without
        modification for most of your use cases.  And should you find
        something that Singing & Dancing can't do, it's built to be easily
        extended via plug-ins using the Zope 3 Component Architecture.
        
        Features
        ========
        
        Modern and extensible
        Singing & Dancing builds on the latest and greatest efforts in the
        Zope and Plone world.  It makes heavy use of the excellent
        ``z3c.form`` library and the Zope 3 Component Architecture.  This
        allows you to easily plug in and extend Singing & Dancing to fit
        your needs.
        
        Well tested
        An extensive suite of automated tests make Singing & Dancing
        exceptionally stable and reliable.  We currently have 200+ tests.
        Singing & Dancing is not gonna leave you in the lurch!
        
        Fully managable through the Plone interface
        Singing & Dancing is fully usable out of the box.  An extensive
        set of forms reachable through the configuration panel let you as
        the user configure many details of your newsletters, like *when*
        they're sent (periodically or manually), *what* is sent (through the
        use of the *Smart Folder* interface, or manually), and to whom.
        
        Subscriptions
        Singing & Dancing uses *confirmed subscription*, i.e. subscribers
        receive an e-mail to confirm their subscription.  Users can
        subscribe via a standard subscription form that lists all available
        newsletters in the site, or through individual subscription forms,
        e.g. in portlets.
        
        Future
        ------
        
        A couple of features that we're going to implement in the near future:
        
        Newsletter templates
        Take complete control over how the newsletters look that are sent
        out.  Create your own template or one of the templates that come
        pre-installed with the Singing & Dancing.  Manage newsletter
        templates in a pool for easy reuse.
        
        .. image:: http://danielnouri.org/media/singing-dancing.jpg
        :alt: Singing & Dancing Logo by Giuseppe Zizza
        
        Screenshots
        ===========
        
        A `walk-through with screenshots`_ is available online, which should
        give you a good idea of what Singing & Dancing is capable of, and also
        guide you through the steps necessary to get you set up and dancing!
        
        Installation
        ============
        
        Singing & Dancing is available as `Python eggs on PyPI`_.  To install,
        you can simply depend_ on the ``collective.dancing`` package in your
        own site policy package, and add *fake zope eggs* to your zope2
        install section in your buildout_ configuration, as explained below.
        
        Alternatively, add ``collective.dancing`` to the list of eggs in your
        ``buildout.cfg`` if you don't have your own package.  This is what we
        explain below.
        
        Sadly, we don't support Repoze_ at this poiint.
        
        Installing S&D with Buildout
        ----------------------------
        
        If you don't know what buildout is or `how to create a buildout`_,
        `follow this tutorial`_ first.
        
        These instructions assume that you already have a Plone 3 buildout
        that's built and ready to run.
        
        1) Edit your buildout.cfg file and look for the ``eggs`` key in the
        ``instance`` section.  Add ``collective.dancing`` to that list.
        Your list will look something like this::
        
        eggs =
        ${buildout:eggs}
        ${plone:eggs}
        collective.dancing
        
        In the same section, look for the ``zcml`` key.  Add
        ``collective.dancing`` here, too::
        
        zcml = collective.dancing
        
        2) Still in your buildout configuration file, look for the ``[zope2]``
        section (which uses the ``plone.recipe.zope2install`` recipe), and
        add the following lines to it::
        
        fake-zope-eggs = true
        additional-fake-eggs = ZODB3
        skip-fake-eggs =
        zope.testing
        zope.component
        zope.i18n
        
        3) Now that we're done editing the buildout configuration file, we can
        run buildout again::
        
        $ ./bin/buildout -v
        
        4) That's it!  You can now start up your Zope instance, and then
        install Singing & Dancing in your Plone site by visiting the
        *Add-on Products* site control panel.
        
        Should these instructions not work for you, `contact us`_.
        
        It's installed.  What's next?
        -----------------------------
        
        You'll now have an entry in the control panel to *Singing & Dancing*.
        This will lead you to to the advanced configuration panel of S&D.
        
        Note that there's already a default newsletter set up for your
        convenience.  You can create a *Channel subscribe portlet* to enable
        your users to subscribe to this channel, or you can point them to
        http://yoursite/portal_newsletters/channels/default-channel/subscribe.html
        
        To send out a newsletter, go to any portal object, like the Plone
        front page, and click *Actions -> Send as newsletter*.
        
        The advanced configuration panel of S&D gives you many more ways to
        send newsletters, like periodically and from automatically collected
        content.
        
        Processing the message queue
        ----------------------------
        
        One important thing to note is that S&D usually queues messages in its
        own message queue before sending them out.  You might have noticed
        that when you send out a newsletter, S&D tells you that it queued the
        messages.
        
        In a production setup, you would normally process the message queue
        periodically using the built-in Zope ClockServer_.  While you're
        testing, you can visit the *Statistics* screen in the S&D advanced
        configuration panel and manually flush the queues.  If your mail
        configuration in Plone is set up correctly, you should be sending mail
        out now.
        
        To set up ClockServer to trigger the processing automatically for you,
        add this stanza to the Zope 2 ``instance`` section of your buildout
        configuration and rerun ``bin/buildout -v``::
        
        zope-conf-additional =
        <clock-server>
        method /portal/@@dancing.utils/tick_and_dispatch
        period 300
        user admin
        password admin
        host localhost
        </clock-server>
        
        This will process the message queue every five minutes.  It assumes
        that your Plone site is called ``portal`` and that your username and
        password are ``admin``.
        
        **Note**: You must not set up this ClockServer on more than one
        instance.  The processing makes sure it's not invoked twice at the
        same time by using file locking.
        
        Upgrade
        =======
        
        If you're upgrading your version of Singing & Dancing, it might be
        that you need to run an upgrade of the database.  In the
        ``portal_setup`` tool in the ZMI, visit the *Upgrades* tab and run any
        available new upgrades for the ``collective.dancing:default`` profile.
        
        
        Contact us
        ==========
        
        If you have a question, or comment, get in touch with us!  Our
        `mailing list`_ is a good place to do so. If you find a bug, please
        `let us know`_. We also have an IRC channel called
        ``#singing-dancing`` on Freenode_.
        
        Developers
        ==========
        
        Singing & Dancing is built from scratch to be extensible.  All
        components described in the `interfaces.py`_ file in
        ``collective.singing`` are pluggable.
        
        Developer documentation exists in the form of doctests and Zope 3
        interfaces in the source tree.  To check out the development buildout,
        type this into your terminal::
        
        svn co http://svn.plone.org/svn/collective/collective.dancing/trunk-buildout singing-dancing-dev
        
        When the checkout is complete, you can find the doctests in ``*.txt``
        files in the ``src/collective.singing/collective/singing/`` and
        ``src/collective.dancing/collective/dancing/`` directories.  There's
        also a documentation area for use cases and manuals in
        ``src/collective.dancing/docs/``.
        
        The latest version of collective.dancing itself can also be found in
        the `Subversion repository`_.
        
        Get in touch with us if you need help or have comments.  See the
        `Contact us`_ section.
        
        
        .. _walk-through with screenshots: http://groups.google.com/group/singing-dancing/web/singing-dancing-screenshots
        .. _Python eggs on PyPI: http://pypi.python.org/pypi/collective.dancing
        .. _depend: http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies
        .. _buildout: http://pypi.python.org/pypi/zc.buildout
        .. _Repoze: http://repoze.org
        .. _how to create a buildout: http://plone.org/documentation/tutorial/buildout/creating-a-buildout-for-your-project
        .. _follow this tutorial: http://plone.org/documentation/tutorial/buildout
        .. _ClockServer: http://plope.com/software/ClockServer/
        .. _let us know: http://bugs.launchpad.net/singing-dancing/+filebug
        .. _mailing list: http://groups.google.com/group/singing-dancing
        .. _Freenode: http://freenode.net
        .. _interfaces.py: http://dev.plone.org/collective/browser/collective.singing/trunk/collective/singing/interfaces.py
        .. _Subversion repository: http://svn.plone.org/svn/collective/collective.dancing/trunk#egg=collective.dancing-dev
        
        History
        =======
        
        Version 0.5.2 - Unreleased
        --------------------------
        
        Version 0.5.1 - 2008-08-15
        --------------------------
        
        - Fixed a bug where a collector would have a ``Title`` property; this
        should be a method. [malthe]
        
        - Added permissions to send, preview and manage newsletter. No upgrade
        steps required - just reinstall. By default - send and preview is
        allowed to reviewer and manager role, manage newsletters for
        managers only. [saily]
        
        Version 0.5.0 - 2008-07-29
        --------------------------
        
        - Display a more user friendly error message when the user attempts to
        add duplicate subscriptions.
        [miziodel, nouri]
        
        - List of subscribers can now be uploaded and downloaded in CSV format!
        [skatja]
        
        - Depend on 0.3 or higher of plone.app.z3cform.
        [nouri]
        
        Version 0.4.1 - 2008-07-23
        --------------------------
        
        - Fix ``RuntimeError: maximum recursion depth exceeded`` error in
        ``Module collective.dancing.browser.portlets.channelsubscribe, line
        253, in channel`` when displaying portlets that were created prior
        to 0.4b4.
        [nouri]
        
        Version 0.4 - 2008-07-23
        ------------------------
        
        New features
        ~~~~~~~~~~~~
        
        - Added subject, confirmation_subject and forgot_secret_subject to
        vars of composer for easy customization.  Defaults are unchanged.
        [tmog]
        
        - Added sender name, sender address and reply-to address as per
        composer configuration. Composer configuration is now available
        in the new Composers fieldset of the channel edit view.
        [tmog]
        
        - Allow for easier subclassing of HTMLComposer.  The ``_vars()``
        method is now more generally applicable and easily to override.
        [nouri]
        
        - Made adding thirdparty Channels possible. This works the same as
        with Collectors - you simply implement you custom channel and add
        a factory to the collective.dancing.channel.channels list.
        Preview and edit forms are now class methods on ManageChannelView
        to make it easier to subclass for your custom channels.
        [tmog]
        
        - Pass on raw item as received from the collector to the composer
        (template).  Making use of this raw item will obviously bind the
        implementation of the composer to that of the collector.  However,
        it's considered useful for custom implementations that need total
        control and that know what collector they'll be using.
        
        This required an API change in IComposer.render(); the ``items``
        argument is now a list of 2-tuples instead of a list of formatted
        items.
        [nouri]
        
        - Added Polish translation by Barbara Struk
        [naro]
        
        - Added another type of scheduler: TimedScheduler.  This one allows to
        schedule a number of send-outs with an exact datetime.  Its main use
        is for the "send newsletter" form on a context where we want to
        specify a send-out date in the future.
        [nouri]
        
        - The confirmation view will now confirm pending subscriptions to any
        channel.  This saves us from having to send a separate confirmation
        e-mail for every channel a user subscribes to.  This feature isn't
        used anywhere in S&D core at this point, but it's useful if you're
        writing custom subscription forms.
        [nouri]
        
        - Added SubjectsCollectorBase template class that you can use to
        create a collector based on a vocabulary.  This vocabulary may come
        from anywhere, like from ATVocabularyManager or from the list of all
        subjects/tags available in your site.
        [nouri]
        
        - Text fields will now per default not be included in the resulting
        message if there are no sibling collectors that produced items.
        E.g. if you have a heading text and a sibling topic collector, the
        heading won't appear if the topic didn't return any items.
        [nouri]
        
        Bugfixes
        ~~~~~~~~
        
        - Updated installation instructions to use the ``fake-zope-eggs``
        feature of the ``plone.recipe.zope2install`` instead of
        ``fakezope2eggs``.  Also, added ``skip-fake-eggs`` to accommodate
        latest changes in ``plone.z3cform``.
        
        - Use ``CompositeQueue`` instead of the simple zc.queue.Queue for
        queueing and archiving mails.  This should help with memory bloat
        when there's a lot of messages in the queue.
        [nouri]
        
        - Don't attempt to do any workflow transition with ATTopic items
        created in the collector; the default workflow will do fine, and we
        avoid errors when using workflows other than the default one.
        [nouri]
        
        - Don't bail if no items are available for preview.
        [malthe]
        
        Version 0.3 - 2008-06-03
        ------------------------
        
        New features
        ~~~~~~~~~~~~
        
        - Add translations to German.
        [saily]
        
        - Added preview also to channel view.  This was previously only
        available for the "send as newsletter" action.
        [malthe]
        
        - Refactored channels management view and the dedicated channel view.
        Big improvements to usability of the channel view.
        [malthe]
        
        - Added capability to embed stylesheets in outgoing mail.  Right now,
        this is a simple text field that can be set on the channel's composer.
        We're now making use of the StoneAgeHTML library to embed styles in
        the individual HTML elements instead of providing styles in the
        ``<head>`` of the HTML document.  This gives us much better support
        with quirky e-mail clients out there.
        [malthe]
        
        In the future, we want to extend this to allow administrators to
        select themes for individual channels by browsing and selecting from a
        list of registered styles.
        
        - Added Czech translation.
        [naro]
        
        - Refactored ``mail.py`` to create ``MIMEMultipart`` based messages.
        This allows us to easily adapt the mail sending process to embed
        images and the like.
        [naro]
        
        - Added a "reference collector".  This allows you to select individual
        portal items to be sent out, as opposed to items collected by a Smart
        Folder or the like.
        [malthe]
        
        Bugfixes
        ~~~~~~~~
        
        - S&D 0.3b2 introduced an incompatible change with channels created in
        0.3b1 and earlier.  I added a GenericSetup upgrade step to fix this.
        The relevant code is in the ``collective.dancing.upgrade`` module.
        
        If you're using a legacy database with channels that were created
        before version 0.3b2, you'll need to run this upgrade step, or
        you'll see this error::
        
        TypeError: ('object.__new__(HTMLComposer) is not safe, use persistent.Persistent.__new__()', <function _reconstructor at ...>, (<class 'collective.dancing.composer.HTMLComposer'>, <type 'object'>, None))
        
        Refer to the Upgrade_ section for details on how to run upgrades.
        [nouri]
        
        - Add ``metadata.xml`` to make QuickInstaller happy with version
        numbers.
        [naro]
        
        - Back to using checkboxes for multi selection instead of ``select``.
        [nouri]
        
        - Make HTMLComposer and channel.composers persistent so that changes
        to template and composers are conveniently persisted.
        [nouri]
        
        - Use ``zc.lockfile`` to lock the queue processing (sending out of mail)
        instead of excessively using ``transaction.commit()``, which caused
        massive ZODB bloat when a lot of messages were involved.
        [nouri]
        
        - Use ``email.Header`` for message header formatting.  This allows for
        better internationalization in headers of outgoing e-mails.
        [naro]
        
        - In-browser preview now displays what would really be sent out,
        i.e. after collectors and transforms could do their thing.  Before, it
        used to only display the context item as mail.
        [malthe]
        
        Version 0.2 - 2008-05-06
        ------------------------
        
        - Add an 'Already subscribed?" section to the "My subscriptions"
        page to retrieve your password.
        [nouri]
        
        - added i18n:domain to browser/controlpanel-links.pt, removed extra quotes
        from browser/channel.py, updated pot and danish translation
        [bartholdy]
        
        - updated .pot and danish translation
        [bartholdy]
        
        - apparently triplequoted strings do not get translated ..
        this takes care of
        https://bugs.launchpad.net/singing-dancing/+bug/218448
        [bartholdy]
        
        - Don't use locale-dependent 'string.letters' when creating the
        ISalt utility.  This fixes
        https://bugs.launchpad.net/singing-dancing/+bug/217823
        [nouri]
        
        - Extended portlet with optinal footertext
        [bartholdy]
        
        - Added functionality to show a preview in the browser
        [malthe]
        
Keywords: zope plone notification newsletter
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
