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 3.x 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:

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

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

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.

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.

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.

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
• Products/Five/i18n.zcml uses namespace package in configure package directive
• 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.