Singing & Dancing User Manual
Table of Contents
1 Plone Site Setup
2 Mailing-list administration
2.1 Edit Mailing-list
2.1.1 Subscriptions
2.1.2 Edit
2.1.3 Composers
2.1.4 Preview
2.2 Edit Newsletter Content
2.2.1 Collector block
2.2.2 Rich text
2.2.3 Content selection
2.3 Scheduler
3 Collector Administration
4 Global settings
5 Statistics
6 Send Site Content as Newsletter
6.1 Send
6.2 Preview
7 Subscribing to Newsletter
1 Plone Site Setup
Singing&Dancing (S&D) can be found, if you have Plone Manager rights, in the Site Set-up area (e.g.www.yourdomain.com//plone_control_panel) of your Plone website, under the 'Add-on Configuration' section:
Click on the 'Singing & Dancing' (S&D) link, which will lead you to the S&D menu, shown in the screen-shot below:
2 Mailing-list administration
In the screen-shot above, you have the following links to set-up:
- Title: The Woodpecker – the name of the newsletter or channel to be sent.
- Collector (what): SearchNews – a collector in S&D allows you to add content to the newsletter.
- Scheduler (when): Manual scheduler – in the example above the newsletter is sent adhoc but the following options are available:
- Weekly scheduler
- Daily scheduler
- Manual scheduler
- Timed scheduler
- Subscribeable: where the visitors to the site can subscribe to the newsletter through a portlet.
To add a new newsletter, you complete the following form and click Add:
In the Mailing-list administration screen (Section 2.1 Mailing-list administration) click on The Woodpecker (Title of Newsletter)
2.1 Edit Mailing-list
2.1.1 Subscriptions
In the Subscription section you can search and add individual email addresses or mass upload multiple email addresses.
- Search subscribers: enter an email address that you want to find amongst your newsletter's subscribers and click Search.
- Add: to add individual new email addresses to your subscriber list enter the email address in the e-mail address field and click Add.
- Subscribers: upload a comma separated value (CSV) file with a list of your subscribers. Subscribers already present in the database with be overwritten. Each line should contain an email address.
- Purge list: delete list of subscribers before importing the CSV file.
- Remove subscribers in list: only remove the newsletter subscribers that are listed in the CSV file.
- CSV contains a header row: to be used if your CSV file contains field headers.
- CSV delimiter: set the text delimiter to match your CSV file type.
2.1.2 Edit
Editing the newsletter's properties, you will see the following screen-shot.
- Title: The Woodpecker – the name of the newsletter or channel to be sent
- Collector (what): SearchNews – a collector in S&D allows you to add content to the newsletter.
- Scheduler (when): Manual scheduler – in the example above the newsletter is sent adhoc but the following options are available:
- Hourly
- Daily
- Weekly
- Monthly
- Description: description of the newsletter. This description is shown when you click on the newsletter link within the newsletter subscription portlet.
- Subscribeable: where the visitors to the site can subscribe to the newsletter through a portlet.
- Keep a record of sent messages: Tracking of sent newsletters which is currently not recommended for large volumes of messages due to storage requirements.
When making changes to any of the above fields click Apply.
2.1.3 Composers
Here you can change how the newsletter looks and what other information should be displayed in your newsletter.
- From name: The name that is shown in the “From” name field when the newsletter is received from the subscriber.
- From addresses: The email address that is shown in the “From” email field when the newsletter is received from the subscriber.
- Message subject: You can construct auto-populated fields for the newsletter. For a list of options see table below.
- Reply-to address: The email address to be used when replying by the subscriber to the newsletter.
Note: If you don’t enter anything here the site administrators name and email as configured in Plone will be used.
- Header text: Text that will be included first in all the newsletters sent.
- Footer text: Text that will appear last in the newsletter.
- CSS Stylesheet: Changes to CSS stylesheet that affects the HTML styling of the newsletter.
- Template: Select what template you want from the drop down menu. Control the newsletters look and feel with a specific design for your newsletters.
For the subject, footer and header you can insert dynamic text that will be generated when the newsletter is sent. The variables available are:
| Variable | What it results in |
|---|---|
| ${channel} |
The channel id, eg newsletter |
| ${channel_title} |
The channel title, eg The Woodpecker |
| ${site_url} |
The URL to the site, eg http://www.yoursite.com/ |
| ${site_title} |
The title of the site, eg YourSite.com |
| ${subject} |
The subject as defined in the subject field |
| ${stylesheet} |
The CSS stylesheet |
| ${from_addr} |
The address in the From address field |
| ${to_addr} |
The address the mail is sent to |
| ${unsubscribe_url} |
A link to an unsubscribe form |
| ${my_subscriptions_url} |
A link with an overview of all the subscriptions of the recipie |
2.1.4 Preview
S&D allows you to preview your newsletter in your browser before sending it to your subscribers.
- Include collector items: Whether the preview should include the content set by The Collector linked to your newsletter.
2.2 Edit Newsletter Content
There are two ways of creating content for your newsletter. One is through constructing the newsletter through the Collector administration, with the option of selecting a collector block, rich text block or content selection block which will be discussed in this section. The second is by sending a Plone site content item which will be discussed in Section 6 Send Site Content as Newsletter.
2.2.1 Collector block
A Collector block allows you to use Plone smart folders to aggregate published content on your site. 
Click on Edit the Smart Folder. 
You can make a selection from the combination of a Field name and Criteria type. The following combinations are available.
| Field Name | Description | Criteria Type | Description |
|---|---|---|---|
| Creation Date |
Date that content is created on |
Relative Date Date Range |
eg Day, Week, Month Specific dates |
| Creator |
The creator of the content |
Select values from list Restrict to current user |
Selection from the Plone user list Limiting content to logged in user Enter a text string Enter a list of values |
| Description |
Uses Plone content description field |
Text |
Enter text string |
| Effective Date |
Date that content is published on |
Relative Date Date Range |
eg Day, Week, Month Specific dates |
| End Date |
Date that the Event content type ends |
Relative Date Date Range |
eg Day, Week, Month Specific dates |
| Item Type |
Selection of Plone content types |
Select Content Type |
Selection eg News item |
| Location |
The physical location of the content in the Plone site |
Location in site Location is site relative to current location |
|
| Modification Date |
Date that content is modified |
Relative Date Date Range |
eg Day, Week, Month Specific dates |
|
Related to |
Select referenced content | ||
| Search Text |
Text |
Enter text string | |
| Short Name |
Text List of values |
Enter text string Enter a list of values |
|
| Start Date |
Date that the Event content type starts |
Relative Date Date Range |
eg Day, Week, Month Specific dates |
| State |
Plone status (private, published) |
Select values from list Text |
Selection from the Plone user list Enter a text string Enter a list of values |
| Tags |
Select values from list Text |
Selection from the Plone user list Enter a text string Enter a list of values |
|
| Title |
Plone content title |
Boolean (True/False) Restrict to current user Date Range List of values Select Content Type Select referenced content Text |
Selection Limiting content to logged in user Specific dates eg Day, Week, Month Enter a list of values Enter a text string |
For the purpose of this manual we will go through the steps to aggregate last month's news items from the Plone site. We selected Item type from the Field name drop-down menu and click Add criteria and the following screen-shot will appear.
Select News item from the Values selection list. Click and under operator name. Click the tick box left of the Item Type and Save. Now we are going to set a time period for the news items to be collected under Add New Search Criteria. 
Select the Effective Date in the Field name drop-down menu and Relative date in the Criteria type drop-down menu. Click Add criteria.
The Effective Date section is now added to the criteria for collection. Select 1 Month from the Which day drop-down menu. Select in the past from the In the past or future drop-down menu. Select Less than from the More or less drop-down menu. Tick the Effective Date box and Save.
The above criteria that any news items less than a month old that is published will now automatically be included in the newsletter's collector. The only remaining thing to do is set the sort order in which these news items appear.
From the Set Sort Order section, select Effective Date from the Field name drop-down menu and Save.
2.2.2 Rich text
A Rich text block allows you to compose a block using your default Plone editor.
To add a Rich text block, select Rich text from the Type drop-down menu and add a Title. Click Apply and the following screen-shot will appear.
Add your content in the Rich text block. You can change the order of your blocks by clicking on Move block up or remove the block by clicking on Remove block. Click Apply at the bottom of the page.
2.2.3 Content selection
S&D allows you to search and select for published content on your site through the Content selection option.
To add content, select Content selection from the Type drop-down menu and add a Title. Click Apply and the following screen-shot will appear.
Enter a search query to find content under Items and all the published content that has the word “Security” in it, will appear in a list of search results. Tick the items you want to add to your newsletter and click Apply at the bottom of the page.
Note:
- Once an object is selected and a new search has been done, the selected item is retained. This allows you to add and retain content against different search queries.
- The results of the search query is restricted to title, description, body and any keywords added. It does not search Plone content items i.e. using the search term “news item” does not return Plone news item content types, only Plone content where the words “news” and “item” are used in the fields mentioned above.
2.3 Scheduler
The scheduler allows you to send the newsletter at set intervals (weekly, daily, timed) or ad hoc (manual).
Select the Scheduler (when) type from the drop-down menu, in this case Manual scheduler. Tick the select box and Apply changes.
Click on the Manual scheduler and the following screen-shot will appear.
To put the newsletter in the sending queue, click Trigger now.
To send the newsletter at set intervals select one of the interval options; weekly, daily, timed, from the drop-down menu. Tick the select box and Apply changes. A similar screen-shot as above will appear, where you can set the starting date for the interval.
3 Collector Administration
The Collector Administration allows you to create different newsletter body contents.
- Title: The name for the content of your newsletter
- Add:
- Title: Give a new title for the content section of your newsletter.
- Type: When adding a new title there is only one default type available which is Collector block. Click Add.
By default S&D adds a Collector block but you can also add a Rich text and Content selection block discussed below.
Click on the blue link “Newsletter Content” in the screen-shot above and see Section 2.2 Edit Newsletter Content.
4 Global settings
In Global settings set whether you want to use a single from subscription by clicking yes or no and Apply.
5 Statistics
Allows you to have an overview of your different newsletters and the status thereof. i.e. sent, in queue, failed messages etc.
The screen-shot above shows 4 messages in queue as triggered in the manual Section 2.3. Scheduler.
To send the newsletters, tick the select box next to the newsletter you want to send. Click Send queued messages now. A message appear above the table informing you of the success or failure of the sent newsletters.
6 Send Site Content as Newsletter
S&D allows you to send any published Plone content such as news items, events and pages by using the Actions drop-down menu as shown in the screen-shot below:
Click Send on newsletter from the Actions drop-down menu.
6.1 Send
From the Send sub-menu you can send the content item to your mailing-list associated with your newsletter.
From the mailing-list to send this through, select in this case “The Woodpecker” and chose whether you want to Include collector items by selecting yes or no. Select a Scheduled time to Send the newsletter. To add the newsletter to the queue click Send. To send a newsletter see Section 5 Statistics.
6.2 Preview
You can also Preview this page before sending the newsletter.
From the mailing-list to send this through, select in this case “The Woodpecker” and chose whether you want to Include collector items by selecting yes or no.
You can preview it in your browser, by clicking Show preview or by sending it to a specific email address by adding the email address in Address to send the preview to and clicking Send preview.
7 Subscribing to Newsletter
To add a subscription portlet for your newsletter, go to the root of your Plone site and click on Manage Portlets and the screen-shot will appear.
From the Add portlet drop-down menu select the Mailing-list subscribe portlet and the following screen-shot will appear.
Fill in the fields as you want the portlet to appear, select the Mailing-list to enable subscriptions to, and click Add. You will now return to the manage portlet view. If you click again on the Mailing-list subscribe portlet, you will notice that now that a newsletter has been selected, the following additional section is exposed, where you can select the sections that are subscribeable under the Newsletter selected:
Select the content from the Sections list, and click Add. Your portlet is now complete, and looks like the following:
If you click on the 'The Woodpecker' link from the screen-shot above, you will be sent to the following page:
The content above, is created in the Section 2.1.2 Edit of this manual.
Sources:
- http://groups.google.com/group/singing-dancing/web/singing-dancing-screenshots
- http://packages.python.org/collective.dancing/
Singing & Dancing Manual by Joris Goudriaan is licensed
under a Creative Commons Attribution 3.0 Unported License.
