=================
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.

.. 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.

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
         zope.sendmail

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.

Troubleshooting
---------------

Should these instructions not work for you, `contact us`_.

Here's a list of the most common stumbling blocks:

   - `ValueError: too many values to unpack <https://bugs.launchpad.net/singing-dancing/+bug/253377>`_

   - `Products/Five/i18n.zcml uses namespace package in configure package directive <https://bugs.launchpad.net/zope2/+bug/228254>`_

   - Should you see ``ImportError: Module
     zope.app.component.metaconfigure has no global defaultLayer``
     when starting up, make sure you have
     ``plone.recipe.zope2install`` >= 2.2.  You may use buildout's
     ``versions`` feature to tell it which version to use.

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 clear 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>
        # plonesite is your plone path
        method /plonesite/@@dancing.utils/tick_and_dispatch
        period 300
        user admin
        password admin
        # You need your *real* host here
        host www.mysite.com 
      </clock-server>
      
Or, if your site is behind Apache using a Virtual Host, 
the zope.conf clock server configuration would be ::

  zope-conf-additional = 
      <clock-server>
        # plonesite is your plone path
        # www.mysite.com your site url
        method /VirtualHostBase/http/www.mysite.com:80/plonesite/VirtualHostRoot/@@dancing.utils/tick_and_dispatch
        period 300
        user admin
        password admin
      </clock-server>

    

This will process the message queue every five minutes.  It assumes
that your Plone site's ID is ``portal``, that your username and
password are ``admin``, and that your site is called
``www.mysite.com``.

**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.  This file locking won't work if you
configure the clock server on two different servers.

Configuring zope.sendmail to send out messages
----------------------------------------------

Singing & Dancing uses `zope.sendmail`_ to send out its mail.  S&D
comes with a default configuration for ``zope.sendmail`` in its
``collective/dancing/mail.zcml`` file.  This configuration will read
SMTP parameters from your Plone site.

Be warned however, that this default configuration is not suitable for
high-volume newsletters.  The aforementioned configuration file
contains an example configuration using ``mail:queuedDelivery`` that
works much more reliably when dealing with a large number of mails.

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
.. _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
.. _zope.sendmail: http://pypi.python.org/pypi/zope.sendmail
.. _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
