Alerts

Jakub Adámek

Econnect

$Id: alerts.html 4861 2024-02-01 15:10:11Z honzam $

Revision History
Revision 1.1	18.4.2003
Updated the Step-by-step tutorial. Added a tip about links.
Revision 1.0	5.4.2003
Extracted from the Reader Management document and enhanced.

1. Introduction

2. Email content

2.1. View Type Alerts Selection Set

3. Alerts module

4. Sending emails

5. Step by step tutorial

6. Tips

Note

This file was created from the DocBook XML source. Please do modifications in the source, not here.

Abstract

This document describes the Alerts module. It is necessary you understand how readers are managed by the Reader Management slices first.

1. Introduction

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.

2. Email content

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

2.1. View 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.php 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.

3. Alerts module

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.

4. Sending emails

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

5. Step by step tutorial

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.

Update to the new AA version from Subversion (svn) and run sql_update.php3
Create “My Readers”:
1. Create a new slice from the “Reader Management Minimal” template with the name “My Readers”
2. Set “Allow anonymous posting” to “Active”
3. Set “Allow anonymous editing” to “Authorized by a password field” (with Authorization, use “Readers, authorized by HTTP auth”)
Create selections:
1. In your favorite test slice, create a view with type “Alerts Digest”. Fill something intelligent into the design, particularly the “Odd Rows” field. Fill also the “Fulltext URL” field.
2. Fill the Selection 1 and 2 Description with “My Selection 1” and 2. Do not fill conds[], you can play with them when you are an Alerts-master
Create and set Alerts:
1. Create a new Alerts module
2. Fill the name “My Alerts”. Fill the form URL with some web folder to which you have access, e.g. http://have_access_to/myalerts.shtml
3. Click on Selections and insert My Selection 1 and 2 into the Alerts
4. Click on Reader management, change to My Readers
5. Click on Add or refresh fields. A message “2 field(s) added” appears.
Copy show_result.php
1. Copy the script from doc/script/show_result.php to the same location where you created myalerts.shtml.
Create the anonymous form:
1. Move to My Readers
2. In Slice Admin - Fields uncheck Show for Username and check Required for Email. Perhaps also uncheck Required for Password. (With Authorization, do nothing, the defaults are OK)
3. Choose Slice Admin - Anonymous Form Wizard
4. Fill the OK and Error URL with the same URL described above, similar to http://have_access_to/myalerts.shtml
5. Fill the URL of yours show_result.php and check the box “Use a PHP script ...”
6. Uncheck all fields except of Email, Password, How often and Selections
7. Click on Show form and copy the form HTML to the file http://have_access_to/myalerts.shtml
Subscribe to Alerts:
1. 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
2. Click on Send, a message appears.
3. Check email and confirm your subscription: Click on the link received in the Welcome email
Send alerts:
1. Go to My Alerts, Send emails. Choose “daily” and click on “Go!” at “Send example”. You should receive a digest of all items added in the last 24 hours to your favorite test slice. If there are no such items, add some: go to Selections, click on My Selection 1, this moves you to your favorite test slice.
2. Try the same with “Send now alerts to all users”. Note this will store the time into the database and if you click again on this button, no mail will be sent because no message was added between the two runs.
Add items to your favorite test slice and test that you receive them

6. Tips

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.