forked from collective/collective.dancing
headnet/collective.dancing
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
================= 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 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 add ``collective.dancing`` to the ``eggs`` in your ``[instance]`` section. Which should then look like this:: [instance] ... eggs = ${buildout:eggs} ... collective.dancing 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. Make sure to also check out our `guide with screenshots`_ for more details. 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_. 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 screenshot to the `sites using S&D`_. 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 on `github`_. Get in touch with us if you need help or have comments. See the `Contact us`_ section. .. _guide 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 .. _donate via PayPal: http://ur1.ca/2d41 .. _sites using S&D: http://ur1.ca/2d4p .. _interfaces.py: http://dev.plone.org/collective/browser/collective.singing/trunk/collective/singing/interfaces.py .. _github: https://github.com/collective/collective.dancing
About
New repository for singing & dancing
Resources
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published
Languages
- Python 99.2%
- Shell 0.8%