User Tools

Site Tools

Translations of this page:

plugin:rssfeed

RSS Feed

Compatible with version

phplist 3

plugin Send campaigns that automatically use content from RSS or Atom feeds.

Last updated on
2015-08-21
Repository
Source
By Duncan Cameron

Purpose

This plugin lets you create campaigns that include content from RSS and Atom feeds and are automatically repeated at regular intervals.
So, for example, you can have a campaign that is sent every day at 09:00 which contains items from an RSS feed that were published in the previous day.

Installation

See the README file on the GitHub page https://github.com/bramley/phplist-plugin-rssfeed for how to install and configure the plugin.

Usage

Creating an RSS campaign

Add an RSS feed

The plugin adds a tab to the Send a campaign page on which you specify the URL of the RSS feed.
You should validate the URL first, by opening it in a browser, to ensure that it is valid and returns what you expect.
Additionally you can choose whether feed items should be displayed in ascending order of publication date (oldest first) or in descending order (latest first).
Optionally, you can also enter a custom RSS template specifically for this campaign. This will be useful it you want to include placeholders for custom tags.

Enter the RSS placeholder in the message content or the message template

You must include the [RSS] placeholder in the message area on the Content tab. You can include other markup if necessary.

Starting in release 2.4.2 of the plugin, the [RSS] placeholder can be included in the message template instead of the message content.

RSS campaign schedule

The plugin uses the standard phplist repeat processing to automatically create and schedule a new campaign.
The repeat interval that you select is also used by the plugin in selecting the feed items to include in a campaign. For a repeat interval of one day the plugin selects feed items that have been published in the past day. Similarly for the other repeat intervals.

To enable repeat processing add this line to your config.php file

define('USE_REPETITION',1);

When composing a campaign, on the Scheduling tab you need to enter

  • the embargo date/time
  • the repeat interval
  • the repeat until date/time


Together these provide the delivery schedule for the RSS campaign. The embargo is when the first campaign will be sent. After then it will be repeated at the repeat interval keeping the same time of day/day of week. phplist will continue repeating the campaign up to the repeat until date.
Each campaign will include recent feed items in the content. If there are no recent items then the campaign will not be sent.

The repeat frequency can be hourly, daily, weekly, fortnightly, or four-weekly. Which interval is suitable depends on the content that you are using and how often it changes. Probably daily or weekly are the most suitable.

When the campaign is being sent, the plugin selects feed items based on the repeat interval:

  • 'day' - items whose published date is within the past 24 hours
  • 'week' - items whose published date is within the past 7 days
  • 'fortnightly' - items whose published date is within the past 14 days
  • 'four-weekly' - items whose published date is within the past 28 days

How the plugin selects items

The plugin selects items to be included using the items' publication date, the embargo date/time of the campaign, and the repeat interval. phplist treats the embargo date/time as being in the database server's local time zone. When fetching items from a feed the plugin converts the published date/time to the server's local time zone so that it can be compared directly with the embargo.

If a campaign repeats at 09:00 each day, then it will include items published from 09:00 the previous day, with the embargo time and items pubished times being treated as being in the server's local time zone. Feeds do not always provide items in order of publication date, so this will not necessarily select the items most recently provided.

When there are no, or insufficient items, to be included then the plugin will modify the campaign's embargo date/time by adding the repeat interval instead of allowing phplist to send a campaign to no subscribers. For example, a daily campaign at 09:00 will be changed to 09:00 on the next day, with the campaign status remaining at “submitted”. The plugin adds an entry to the phplist event log when it does this.

Campaign subject

The subject of the message can be automatically set to the title of the latest feed item using a placeholder

  • [RSSITEM:TITLE]

So, for example, when creating the campaign the subject is entered as:

but the emails are sent with the title of the latest feed item


Additionally, when there is more than one item in the generated email, some optional text can be appended.
For example, specifying the additional text , and more the emails are sent with a subject


The additional text is entered within the RSS group on the Settings page.

Formatting the feed items

When phplist is building the email to be sent the plugin replaces the [RSS] placeholder in the message content by the available feed items, each of which is formatted using an RSS template. The default RSS template is specfied on the Settings page, but each campaign can have a custom RSS template, which is entered on the RSS tab.

The template consists of html containing placeholders that will be replaced by fields from the item:

  • [CONTENT]
  • [TITLE]
  • [URL]
  • [PUBLISHED]

The published date is formatted using a configuration setting. The default is to display as dd/mm/yyyy hh:mm.

Additionally, placeholders for custom tags can be included. The placeholders must match exactly the custom tags entered on the Settings page.

Using the default template, a formatted item has the item title as a link, with the published date beneath, followed by the item content and a horizontal line. As an example

As the formatted feed items are within the message content, which itself may be within a message template, the RSS item template can use styles defined in the message or the message template.

These placeholders are available only in the RSS item HTML template, not generally within the message or message template.

The template is on the Settings page in the RSS Settings group.

Send a test message

To include items from the feed in a test message you will need to have retrieved some feed items. After entering the feed URL you can save the campaign, retrieve feed items, and then switch back to editing the campaign to send a test message.

If there are no items for the feed then the plugin will include some test items.

HTML and plain text format messages

The plugin treats items as being in HTML format and will generate the plain text version of the RSS content from the HTML version using a phplist function HTML2Text().

Retrieving RSS feed items

The plugin needs to periodically get new items from the feed. This can be done manually, using menu Campaigns > Fetch RSS items, or it can be automated using a cron job. The command will be similar to this for phplist release 3.0.9 or later, or if you are using php-cli with an earlier release of phplist (but adjust for the directory in which phplist is installed)

php /home/xxx/public_html/lists/admin/index.php -p get -m RssFeedPlugin -c /home/xxx/public_html/lists/config/config.php

You can also run the command as a remote page if you have a limited cron capability. This approach fetches the page using a linux command such as wget or curl. The URL requires the “Secret for remote processing” value from the phplist Settings page. This method requires phpList 3.3.7 or later.

wget -O rssget.out 'https://mysite.com/lists/admin/?page=get&pi=RssFeedPlugin&secret=xxxxxxxx'

You do not need to run the command very often, maybe once or twice a day should be sufficient. However to ensure that a campaign is sent with the most recent items it should be run just before processing the message queue.

Viewing RSS feed items

You can view feeds and their items using menu Campaigns > RSS feeds

A feed is shown as active if it is being used by a campaign that has “draft” or “submitted” status.

The number of items is a link to a page that displays the items' content.

Deleting RSS feed items

Once feed items have been included in a campaign there is no need to keep them in the phplist database. To delete items older than a number of days use the menu Campaigns > Delete outdated RSS items.

The command can also be automated using a cron job. The command will be similar to this (but adjust for the directory in which phplist is installed). The -d parameter is the number of days for which to keep feed items.

php /home/xxx/public_html/lists/admin/index.php -p delete -m RssFeedPlugin -d 99 -c /home/xxx/public_html/lists/config/config.php

You can also run the command as a remote page if you have a limited cron capability. This approach fetches the page using a linux command such as wget or curl. The URL requires the Secret for remote processing value from the phplist Settings page. The days parameter is the number of days for which to keep items. This method requires phpList 3.3.7 or later.

wget -O rssdelete.out 'https://mysite.com/lists/admin/?page=delete&pi=RssFeedPlugin&days=99&secret=xxxxxxxx'

View email in browser

The plugin can be used with the View in Browser plugin to provide a link that displays the campaign in a browser. You should use the placeholders provided by the View in Browser plugin [VIEWBROWSER] and [VIEWBROWSERURL].

To avoid any problem with incompatible plugin versions you should upgrade to the latest version of this plugin and of the View in Browser plugin.

Custom tags

In addition to the standard tags in an RSS feed, the plugin can capture the values of custom tags. You can then use the value of a custom tag in the RSS template.
The set of custom tags needs to be entered on the Settings page, one tag per line. Each custom tag should be specified exactly as it appears in the RSS feed.

In an RSS template you can include a placeholder for the custom tag

[cppopvault:img]

Example

We will create an RSS campaign for a feed that updates often, so that a repeat interval of one hour can be used.

http://feeds.bbci.co.uk/news/uk/rss.xml?edition=uk

To test the sending of the RSS campaign, create a list that contains a few of your own email addresses.

Then create a campaign.
On the Content tab, enter [RSS] in the message area. You can also include other layout in the message.
On the Lists tab select the new list that you have created
On the Scheduling tab, choose “hour” for the repeat interval, and “repeat until” the end of the current day.
Leave the embargo as the default (the start of the current hour).

On the RSS tab enter the feed URL
http://feeds.bbci.co.uk/news/uk/rss.xml?edition=uk

On the Finish tab submit the campaign.

You can now manually fetch items from the feed using the menu System > Fetch RSS items and then view the items using menu Campaigns > RSS feeds. Confirm that some items have been received whose published date is within the past hour. If not, then periodically repeat this step until there are some items.

If all looks ok then process the queue through the browser. Because the campaign's embargo is in the past it will be sent immediately and will include some of the feed items.
When the message queue has been processed you can check that a new campaign has been created. The Active view of the Campaigns page should show a new campaign whose embargo is one hour after that of the original campaign.

You can then repeat the Fetch RSS items and process queue periodically. So long as the feed supplies new items then each campaign will be sent with recent items and a new campaign created.

Alternatively you can create cron jobs to automate the RSS item retrieval and the phplist queue processing. Create a cron job that runs processqueue once an hour on the hour, and then shortly after, say at 3 minutes past the hour.

php /home/xxx/public_html/lists/admin/index.php -p processqueue -c /home/xxx/public_html/lists/config/config.php

Create another cron job that runs the plugin's get page once an hour just before process queue, say at 58 minutes past the hour

php /home/xxx/public_html/lists/admin/index.php -p get -m RssFeedPlugin -c /home/xxx/public_html/lists/config/config.php

Configuration

The plugin adds an RSS group to the Settings page where you can enter:

  • The minimum number of items to be included in a campaign. The default is 1.
  • The maximum number of items to be included in a campaign. The default is 30.
  • The item HTML template.
  • Text to append when the title of the latest item is used in the subject.
  • Additional feed elements that should be included in each item's data.
  • The format to be used to display the published date.

Change Log

plugin/rssfeed.txt · Last modified: 2018/12/10 13:09 by duncanc

Resources
Contact Us

e: info@phplist.com

Boring Bit

phpList is a registered limited company

UK Company No. 07582966

VAT Registration 122 0788 37

© phpList 2016