.. image:: https://travis-ci.org/collective/collective.dancing.png?branch=master :target: http://travis-ci.org/collective/collective.dancing

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

Personalisation Singing & Dancing allows a channel to define optional collectors or sections which a user can optional subscribe to. Scheduled daily or weekly newsletters can then include additional content personalised to those segments of the channel.

External subscriber database Optionally instead of using the builtin subscriber database and subscription forms you can use another product such as Plomino of PloneFormGen. Configure a path to a script to list the subscribers is is all that is needed to intergrate S&D with your external subscriber database.

Automatic sending Any Plone content item can be sent at a scheduled time using the "Send as newsletter" feature. These can be sent to the whole subscriber list or to a specific section. Content rules can be configured to send an item as a newsletter immediately under certain conditions including if it matches a of Singing & Dancing's collection based collector.

.. image:: http://danielnouri.org/media/singing-dancing.jpg :alt: Singing & Dancing Logo by Giuseppe Zizza

User Manual

The Singing & Dancing user manual is available here: http://www.webtide.co.za/how-to/singing-dancing-user-manual

Installation

Installation of Singing & Dancing uses 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 buildout that's built and ready to run.

Singing & Dancing is available as Python eggs on PyPI_.

To install Singing & Dancing, add it to your buildout by following these steps:

Plone 3.x

1) Edit your buildout.cfg file and look for the [buildout] section. Add an extends = option in that section like the following::

 [buildout]
 extends = https://svn.plone.org/svn/collective/collective.dancing/buildout-extends/0.9.0.cfg
 parts =
     zope2
     ...

 Should you already have an ``extends =`` line, add the new line at
 the end of the other extends files.  For Plone 3.2.2, your
 ``[buildout]`` section might start like this::

 [buildout]
 extends =
     http://dist.plone.org/release/3.2.2/versions.cfg
     https://svn.plone.org/svn/collective/collective.dancing/buildout-extends/0.9.0.cfg
 parts =
     zope2
     ...

2) Next, you'll need to add collective.dancing to the eggs and zcml options in your [instance] section. Which should then look like this::

 [instance]
 ...
 eggs =
     ${buildout:eggs}
     ...
     collective.dancing
 zcml =
     ...
     collective.dancing

Note: When you are using Plone > 3.3 you can skipt the zcml part, because z3c.autoinclude is shipped with Plone 3.3.x by default.

3) Remove all additional-fake-eggs and skip-fake-eggs options from your [zope2] section, if any. (This is so you don't overrride the ones defined in the S&D extends file that we added in step 1.)

Plone 4.x

1) On Plone 4 you don't need to extend your buildout configuration using `extends=.... You'll need to addcollective.dancingto theeggs in your[instance]`` section. Which should then look like this::
```
 [instance]
 ...
 eggs =
     ${buildout:eggs}
     ...
     collective.dancing
```
2) Please use version pins out of versions.cfg file which is included in package if you have package conflicts or strange errors.

Once you're done editing your buildout configuration, don't forget to run your buildout again before you start up Zope::

$ ./bin/buildout -v

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 the above instructions not work for you, contact us_.

NOTE: If you're upgrading your buildout from an older version where you included version dependencies of S&D by hand, remove the develop-eggs directory inside your buildout and re-run buildout.

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.
Since version 0.7.0 of collective.singing we don't support older versions of z3c.form by default. Radio button and checkbox widget hidden templates are already included in more recent z3c.form versions. ( > 2.3.3 as described here http://pypi.python.org/pypi/z3c.form#id14)

If you want to use an old version (for example the popular 1.9.0 which was pinned in older buildout-extends files) you have to manually include a zcml file located in collective.singing.browser.widgets.zcml which registers the missing templates for these widgets::
```
<include package="collective.singing.browser" file="widgets.zcml" />
```
This fixed https://bugs.launchpad.net/singing-dancing/+bug/620608.

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 Mailing-list 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 =

# 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

Or, if your site is behind Apache using a Virtual Host, the zope.conf clock server configuration would be ::

zope-conf-additional =

# 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

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! Feel free to extend S&D and send us a pull-request on github. Since all collective and plone packages moved to github we prefer reporting issues on github_ too.

If you have an older installation you may also want to have a look to our mailing list or old issue tracker on launchpad.

We also have an IRC channel called #singing-dancing on Freenode_.

Donate

Developing software as Open Source can be a thankless task sometimes. If you're a happy user of Singing & Dancing, and you'd like to show your appreciation, you might want to donate via PayPal_.

There's other ways to contribute to the project if you're not a developer; one is to post a message to the mailing list_ describing any successes or problems that you have with the software. That's the only way we can know if S&D is working correctly for you.

Another is to add a line to the sites using S&D_. Please fork S&D and update SITES_USING_SINGING_AND_DANCING.rst in docs directory. After finishing you can send us a pull request, and we'll merge it.

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

git clone https://github.com/collective/collective.dancing singing-dancing-dev

When the checkout is complete, you can find the doctests in *.txt files in the src/collective.singing/collective/singing/ and collective/dancing/ directories. There's also a documentation area for use cases and manuals in docs/.

Get in touch with us if you need help or have comments. See the Contact us_ section.

.. _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/ .. _prefer reporting issues on github: https://github.com/collective/collective.dancing/issues .. _old issue tracker on launchpad: 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 .. _donate via PayPal: http://ur1.ca/2d41 .. _sites using S&D: https://github.com/collective/collective.dancing/blob/master/docs/SITES_USING_SINGING_AND_DANCING.rst .. _interfaces.py: https://github.com/collective/collective.singing/blob/master/collective/singing/interfaces.py

collective / collective.dancing

readme