You are here: Home How To Singing & Dancing User Manual

Singing & Dancing User Manual

A user manual for Singing & Dancing, the newsletter product for Plone, the open source Content Management System

 

Logo of Singing &  Dancing, the newsletter product for Plone, the open source content management system

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:

S&D Site Setup

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Click on the 'Singing & Dancing' (S&D) link, which will lead you to the S&D menu, shown in the screen-shot below:

S&D Configuration

 

2  Mailing-list administration

 

S&D 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:


S&D Add Mailing List

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.

S&D Edit Mailing List

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


S&D Upload List of Subscribers

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


S&D Edit Mailing List 2

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


S&D Edit Mailing List Composer

 

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

S&D Edit Mailing List Composer2

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


S&D Preview

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

S&D Collector Block Collection

Click on Edit the Smart Folder.

S&D Collector Block Criteria

You can make a selection from the combination of a Field name and Criteria type. The following combinations are available.

 

Field Name
DescriptionCriteria TypeDescription
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

Text

List of values

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

List of values

Selection from the Plone user list

Enter a text string

Enter a list of values

Tags

Select values from list

Text

List of values

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

Relative Date

List of values

Select Content Type

Select referenced content

Select values from list

Integer value or range

Text

Selection

Limiting content to logged in user

Specific dates

eg Day, Week, Month

Enter a list of values

Selection eg News item


Selection from the Plone user list

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.

S&D Collector Block Criteria1

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.

S&D Collector Block Criteria2

Select the Effective Date in the Field name drop-down menu and Relative date in the Criteria type drop-down menu. Click Add criteria.

S&D Collector Block Criteria3

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.

S&D Collector Block Criteria4

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.

S&D Rich text1

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.

S&D Rich text2

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.

S&D Content Selection


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.

S&D Content Selection2


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

S&D Mailing List Administration

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.

S&D Scheduler
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.

S&D Collector Administration

 

  • 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

S&D 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.

S&D Statistics

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:

S&D Send Site Content

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.

S&D Send Site Content2

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.

S&D Send Site Content Preview

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.

S&D Subscribing to Newsletter

From the Add portlet drop-down menu select the Mailing-list subscribe portlet and the following screen-shot will appear.

S&D Subscribing to Newsletter2

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:

S&D Subscribing to Newsletter3

Select the content from the Sections list, and click Add. Your portlet is now complete, and looks like the following:

S&D Subscribing to Newsletter4

If you click on the 'The Woodpecker' link from the screen-shot above, you will be sent to the following page:

S&D Subscribing to Newsletter5

The content above, is created in the Section 2.1.2 Edit of this manual.

 

Sources:

 

Creative Commons LicenceCreative Commons license logo

Singing & Dancing Manual by Joris Goudriaan is licensed
under a Creative Commons Attribution 3.0 Unported License.