$Id: alerts.html 2644 2008-07-02 14:57:47Z honzam $
|Updated the Step by step tutorial. Added a tip about links.|
|Extracted from the Reader Management document and enhanced.|
This file was created from the DocBook XML source. Please do modifications in the source, not here.
This document describes the Alerts module. It is necessary you understand how readers are managed by the Reader Management slices first.
AA Alerts are designed to deliver new AA items to users by e-mail. Slice Administrators choose the design and which kind of items from which slices to include. Readers subscribe for receiving the news and select how often: immediately when the news becomes Active (in the meaning of the bins in Item Manager) or a daily, weekly or monthly digest.
Anonymous forms (see doc) allow users to change their subscriptions. Users are identified by e-mail and they must confirm their e-mail address by a confirmation code received by e-mail to make sure the address is working.
This section describes how are chosen the new items which appear in the email.
One Alerts module is one email from the reader's point of view. A set of Selections is assigned to the module. The Selections are defined in views of type “Alerts Selection Set”.
You define this view in the slices, from which you want to send new items. The first check box, “Group by selections”, will be explained later. The view defines the Selections, which have a description and a set of the powerful conds and sort parameters, the same as are used with slice.php3 in search forms. You can e.g. create one selection for each category. When you open an Alerts view, there are always two empty pairs of boxes for two new Selections. If you want to define more Selections, store the view settings and reopen it.
You can add Selections from several views and several slices to one Alerts module. Readers may choose which selections they want to receive. Some items may pass the conds conditions of several Selections. If you check “Group by selections”, the view is generated for each Selection and some items may appear several times in the email. If you leave “Group by selections” unchecked, first all items which pass the reader's Selections are collected and the view is generated only once for all of them.
The setting “Fulltext URL” links to the page where is an item viewed when the reader clicks on its headline in the email. Of course if you do not add a linked headline to the view design, this setting is not used.
The Alerts module appears like other regular modules in the slice select box. It offers these pages:
Table 1. Alerts menu
|Settings||Core settings for the Alerts module, see below.|
|Selections||Choose which selections you want to show and their order. Selections are defined in views of type Alerts Selection Set in the slices from which you want to send new items. Each selection has a description and a set of the Mind that if some item appears in several selections, it will be repeated in the mail. Try to make selections mutually exclusive.|
|Send emails||You can manually send the digest to all readers. And you can send an example email to yourself to see exactly what readers receive.|
|Reader Management||Sets the Reader Management Slice which feeds this Alerts. Allows to add, delete and refresh the Alerts-specific fields to the slice. When you change the list on the Selections page, use Sync to refresh the appropriate constant group in the Reader Management Slice.|
|Email Templates||Allows to edit all email templates.|
The fields added by Sync with reader slice are:
Table 2. Alerts specific fields
|how often||How often the reader receives a digest: instant (each new item in one e-mail), daily, weekly, monthly.|
|choose selections||Multiple checkboxes allowing to choose which selections from the collection the reader wants to read. New parameters of the Multiple Checkboxes field Input type allow to view them in a table, see the Parameter Wizard.|
You may show how often or choose selections in the anonymous forms or you may set defaults by hidden fields.
The core settings in Alerts Admin - Settings include these special fields:
Table 3. Alerts Settings
|form URL||The URL to your pages with the “Change personal details” form. This URL is used to create the _#COLLFORM alias.|
|welcome email||A link to the email template for a message sent to new users on subscription. The edit icon on the right allows you to jump to the email edit form.|
|alert email||A link to the email template of the alert sent instant / daily / ... and containing new items.|
The email templates (welcome and alert) are stored in the common table email and are defined using aliases and alias functions. This allows a completely free design. The formatted new items are added by the _#FILTERS_ alias. If you want to send different texts to readers with different “how often”, use the switch function on the alias _#HOWOFTEN. To allow readers to confirm their email and change their personal settings, use the alias _#COLLFORM, which is the URL you filled in Alerts Admin - Settings, with an additional 9 letters parameter containing the access code.
An example of both email types is added by sql_update.
There are two ways of sending the emails: regularly by cron or manually.
The cron items are added to the cron table automatically by sql_update.php3. You must set up cron on your server, see FAQ. There are four items for the four different frequencies (instant, daily, weekly, monthly). The info when were which Alerts module emails generated is stored in the table alerts_collection_howoften. The emails are created so that readers see the HTML version in e-mail clients supporting HTML and the text version in clients supporting text only. The text form is created by deleting all HTML tags. Technically speaking, it is a MIME multi-part/alternative message with a text part and a HTML part.
If you want to send emails manually, use the “Send emails” page in the Alerts module.
Here is a tutorial, describing in steps how you can try the Alerts module.
WARNING: The result does not use Authorization, the personal info is protected by a password. You should use other settings on several places when using Authorization.
Create “My Readers”:
Create and set Alerts:
Create the anonymous form:
Fill the URL of yours show_result.php3 and check the box “Use a PHP script ...”
Subscribe to Alerts:
Go to the address http://have_access_to/myalerts.shtml and fill in your email address, the password “abcde”, how often “daily” and choose one of the filters
Click on Send, a message appears.
Check email and confirm your subscription: Click on the link received in the Welcome email
Alerts-only reader management: You do not need the username, but the email is required. Change these Fields settings. Perhaps you even do not need to password-protect the reader personal info. Change also the “Allow anonymous posting / editing” slice settings.
Filtering readers who are not yet confirmed: Change the design of the Item Manager in Slice Admin to show the alias _#MAILCONF. This alias shows “yes” or “no”. But it is created by the f_c function and the values in the database are 0 or 1. Thus give “0” and not “no” into the Search box.
Filtering readers receiving a selection: Add the Alerts Selections to Item Manager. Create an alias using the function f_h with the parameter , (comma). You will see the selection IDs prefixed by f. Now you understand why you should enter something like “f45” into the Search box.
Links between Alerts and the related slices. Several links help to jump quickly between the modules. In Alerts, on page Reader management, you can click on the slice name. On page Selections, there are links to all selections and to all slices containing these selections. There are backward links also: On the Item Manager page.