APC Action Applications - Home Page

Frequently Asked Questions v2

 

Topic: Reader Management

0. Password-protected public editing
1. Alerts/Mailman Integration
2. What is Reader Management?
3. How does a user retrieve a forgotten password from reader managment?
4. How do I create a Reader Mamagement logout function?
5. How do I set up Htaccess permissions sync with Reader Management?
6. How to integrate APC-AA with email
7. How to create a simple email alert module
8. How to create a form allowing anonymous posting from public website?

Items posted from a public website may be protected by a password. Suppose you have a field with ID "password.......x" (just like password.......1) in your slice and this field is visible on the public posting page. The user fills in the password when creating a new item. When using the script fillform to edit a public posted item on public pages, the password is not re-filled (all other fields are). But the script filler.php3 does not store the changes if the user does not refill the password correctly.

The scripts recognize the password field by ID "password.......x" - you can add such field in standard way on "Slice Admin" -> "Fields" page - derived from "Password" field template (the Reader Management slices already have such field in its default configuration).

From Mitra (mitra[at]earth.path.net):

I am using alerts/mailman integration, - its one of the most painful AA admin procedures, basically you have to create an alert that goes to a mailman group. Here are the steps (note that I've SIMPLIFIED it, removing sub-steps).

This presumes you have:

  1. In the slice you want to send mail from:
  2. Create Alerts Slice and change settings as follows
  3. Go to mailman, create a mailing list - set yourself (a human) as the owner, set to moderate new subscribers
  4. Go to your Reader Management slice (see note)
  5. Now try and add an item to your slice,

Note that in practice you can only have ONE functioning reader management slice in an entire AA installation since it has email unique - apparently there are historical reasons for this, but it is unclear if there are current reasons.

This is essentially an admin nightmare, do anything even slightly wrong and the mail won't go through, and its very hard to debug.

I believe this could and should be dramatically simplified, we don't have the development resources to build our own mailing list manager in competition to all mailman's functions, better would be to allow an Alerts View to send mail direct to a mailing address - typically the email address of the mailman list.

Reader Management is a special kind of slice that is designed to contain data about subscribed "readers" (aka public web site users). A Reader Management slice can be used to send automated email alerts of new AA items, personalize page views, send bulk target emails, and generally act as a contact database. Anonymous forms can be set-up to allow users to change their subscriptions and contact data in the Reader slice.

1) Go to /apc-aa/misc/forgotten_pwd.php3 (may vary depending where AA is installed)
2) Enter either the username or email address
3) Check the email you will receive in case the user has been found and it's you
4) Visit the url in the email - in fact it's the same but with the temporary key that will let you change the password
5) Change your password

Note: The key expires after 90 minutes

If you realy think you need a logout, you have to create a special directory
  and Logout page under the restricted area of your website. I've set up a little
example here http://marek.greennet.org.uk/protect/http://marek.greennet.org.uk/protect/">http://marek.greennet.org.uk/protect/>

type jason:jason and you get in. Than you can click on logout ant it will
  take you to the logout page. The trick is that the page is under the same realm,
  so in fact you relogin as user "logout" with password "logout"


http://logout:logout@marek.greennet.org.uk/protect/logout/logout.htmlhttp://logout:logout@marek.greennet.org.uk/protect/logout/logout.html">http://logout:logout@marek.greennet.org.uk/protect/logout/logout.html>

The .htaccess file for the /protect/logout area looks like this



 

AuthType Basic

  AuthName "Authenticate yourself"

    AuthUserFile /home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw

    Require user logout



The /home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw contains only
  user logout (the file was created using htpasswd), and only this user is allowed
  here.


Htaccess is updated by AuthMySQL module on the Apache server. The access is granted directly from AA (from auth_group and auth_user tables)

You need to:

1) Install mod_auth_mysql (http://modauthmysql.sourceforge.net/)

(This module is standard part of RedHat Linux distribution (rpm mod_auth_mysql). Be carefull, because there are at least two different modules with the same name but with different httpd.conf options and features. We need the described one and not the one described by Ram: http://actionapps.org/faq/detail.shtml?x=1673 !!!)

2) Then you need set auth_group...... field in Reader managment slice as described here: http://actionapps.org/apc-aa/doc/reader.html#d0e236

3) Set the apache to accept MySQL authentication - something like modifying httpd.conf file:

<Directory /data/www/htdocs/actionapps.org>

AllowOverride AuthConfig FileInfo Options Limit

# Authentication

AuthMySQLHost localhost

AuthMySQLUser aa_db_user

AuthMySQLPassword aa_db_password

AuthMySQLDB aa_db

AuthMySQLUserTable auth_user

AuthMySQLGroupTable auth_group

AuthMySQLNameField username

AuthMySQLPasswordField passwd

AuthMySQLGroupField groups

AuthMySQLNoPasswd off

AuthMySQLCryptedPasswords On

</Directory>

 

4) Protect the directory by .htaccess file or by similar lines in httpd.conf file:

AuthType Basic

AuthName "ActionApps Ariel Members Area"

<Limit GET>

require group ariel_members

</Limit>

or

AuthType Basic

AuthName "ActionApps Ariel Parnters Area"

<Limit GET>

require group ariel_partners

</Limit>

5) Done.

 

There are several places where APC-AA sends mail, and it can be confusing, especially since it is really easy to configure them wrongly so they don't work, and little help for figuring out why. Lets consider 4 cases. The Bugs and Weaknesses of each method are shown because they may help pick which method to use, and also help guide as to places for further development.

Slice Admin or Editor wants notification of new items added to Hold bin, or edited or whatever.

Use the Email Notification functionality, here you can specify different messages to be sent when messages are added / edited to Active / Hold bins, and different recipient lists, so for example you can create a message to an Editor whenever a new message arrives in a Hold bin, and maybe a different message to the sysadmin when an item is moved into the Active bin (usually by the Editor). The message could be just something like "An item has been posted in Xyz slice" or by using aliases can include any fields of the item posted.

Bug/Weakness: You can't use aliases in Subject line, this might be fixed in some version (but is unlikely to be a priority!)
Limitation: The members of the list can only be changed by a slice admin, so don't use this for Alerts ...

A number of people want to receive items posted to a slice

Use a reader management slice (see doc/reader.html) in conjunction with Alerts (doc/alerts.html).

Bug/Weakness: its complex to setup, and frequently people don't succeed, if you don't follow the Tutorial Step by Step (in doc/alerts.html) you probably won't get it to work.

Bug/Weakness: In particular it requires creating an anonymous form, which depends very much on the way its being used (e.g. called from something.shtml or site.php3). One possible development fix would be creating a PHP3 script that took the slice-id of an Alerts module as a parameter and did this much more simply.

Bug/Weakness: documentation says 5.3a: View with type "Alerts Digest", when it means "Alerts Selection Set".

A number of people want to be in an email discussion, i.e. all posting to each other.

Use a Reader Management Slice (see doc/reader.html) in conjunction with Mailman, APC-AA is used to manage the mailman list

Bug/Weakness: you can no longer manage the lists (subscribe/unsubscribe) by email to the Mailman account once you've done this, mailman will almost certainly be sending out email telling the users they can!

Bug/Weakness: You have to understand both apc-aa AND mailman to get this to work since doc/reader.html refers to tasks that require knowing where to find and how to configure mailman.

Bug/Weakness: There is no link between information in a slice, or discussions, and the email discussion, i.e. this is not - like yahoo groups - a web OR mail interface to the same set of data.

Reports of failure (Jason Diceman) partly due to server setup

People wish to receive copies of new comments in Discussions by Email

See "FAQ/Discussions as Mail List", this allows a field in each item to specify a mailing list.

Bug/Weakness: This field has to be added to every item, it can't be specified at the slice level (make the field Required but not Shown and set a default). This is particularly difficult if you want to retrofit discussions to an existing slice, or something coming in over RSS.

Bug/Weakness: This can only go to a single email address, so you have to manage the list somewhere else outside APC-AA (there is no way to for example link it to Alerts).

Bug/Weakness: It doesn't appear to work, sends blank emails.

Summary


Template for Email Who gets the email How sent Bugs, Limitation and further development
Notification Admin -> Slice -> Email Notification Directly from script updating

Can't use aliases in Subject line
Can't self-manage recipients

Alerts Admin -> Slice -> Views -> Alerts View Readers from Reader slice, who can choose which to recieve By Cron Complex to setup (anon forms)
Email Discussion Not applicable - its email to email Members managed by Reader Management slice Mailman handles all sending

Requires understanding mailman to setup, reports of failure partly due to server setup
Cant subscribe/unsubscribe by email
No slice -> email or email -> slice

Discussion -> Email Admin -> Slice -> Views -> Discussion to Email One hard-coded email address Not sure, probably cron. Doesn't integrate with Alerts so no recipient management at all
Doesn't seem to work (Mitra).
Has to be added to each item in slice.

Note:

There is no integration for receiving email, although there has been discussion (where?) about posting articles by mail

This a tutorial for creating a simple alert module and subscription form, similar to the Sandbox subscription demo at http://actionapps.org/reader_mngmt/sandbox_subscribe.shtml. The alert is for all new items in a slice and the subscription require s only email address and sending frequency inputs, no password or selection of slices in this version. Subscribers can update their alert settings (e.g. change email address, modify frequency, and unsubscribe) by clicking on a unique link at the bottom of each alert they recieve.

The tutorial assumes you are already comfrotable creating and administrating slices and designing views in ActionApps.

Step 1: Create a Reader Management Slice

First you must have a Reader Management slice to store subscriber information. If you already hace a Reader slice, then you can skip this step, but keep in mind the Reader slice used in this example is called "My Readers".

  1. AA > New Slice: 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”

You now have a Readers slice called "My Readers" that will store each alert subscriber as one item. It also possible to add more fields to store additional data about your subscribers, but that's another tutorial (coming soon).

Next we need to select what items subscribers can be alerted to.

Step 2: Create a Selection of Items to be “Alerted”

An alert modules requires selections from slices. A selection is a condition on an alerts view of a slice. It's a bit confusing but will make more sense once we go through the complete alert module production process.

In this case, we have selected to alert users about new items from the important slice called “My Slice”.

In My Slice, create a new view, type “Alerts Selection Set”. Set field vaules as:

    Alerts Selection Set: “My Slice alert views”

    Group by selections (ignore for now)

    Alerts Selection 1 Description: “All My Slice Items”

    conds[] (ignore for now)

    Alerts Selection 2 Description and conds[] (ignore for now)

    Fulltext URL: (URL of fulltext view use for _#HDLN_URL)

    Fill the rest of the fields as a simple listing view, probably similar to your index view.

    Click Update

You now have an alerts selection called “All My Slice Items”. Once you are more comfortable with alerts, you can add more selections that use conds[] to allow users to filter in only certain types of items, but that's another tutorial (coming soon).

Step 3: Create an Alerts Module

Next step is to create an alerts module that will send your newly created alert selection.

  1. AA > Create New > Alert, settings:
  2. Selections > Insert “All My Slice Items” from the menu (notice there are also shortcut links at the bottom for quick access to the slices with alerts and editing the alert views).
  3. Click on Reader management, Synchronization with Reader Management Slice, change to “My Readers“ (the page will refresh)
  4. Click on 'Add or refresh fields' at the bottom. A message “2 field(s) added” appears.

Your alert module now contains alert selection "All My Slice Items" and My Readers slice contains two new input fields: “How Often” and “Selections”. You can goto the My Readers fields admin page to see these new fields. If they don't show up, go back to alert module > Reader Management and click on ‘Add or refresh fields’.

More selections can be added later. Everytime you add a section you will need to go back to your alert module > Reader management and click on ‘Add or refresh fields’.

You can now test your alert module by subcribing yourself using: My Readers > Add New Item: input your email address, check "email confirmed", set "How Often" to "instant" and check "Selections: All My Slice Items"

Then go to My Slice and add a new item. You should shortly there after receive an emal from the alert module announcing the new addition. You will notice the alert module messages use ECN related text by default. You can customize your welcome and alert messages at any time (see Step 5). But first let's set-up some public subscription forms...

Step 4: Create a Subscribe Form (and Related Pages)

To allow users to subscribe to your alerts, you will need to create a form using ‘Anonymous Form Wizard’. You should also have an OK page that tells users to check their inbox for an email confirmation and a another page with an anonymous form for updating subscription settings. Thus you will need to create three files, e.g.:

http://mysite.com/myalerts/subscribe.shtml - Invitation to subscribe using anonymous form.

http://mysite.com/myalerts/subscribe_ok.shtml - A notice telling users to "Check your inbox for an email confirmation".

http://mysite.com/myalerts/update.shtml - A subscrition settings update page using anonymous form, accessed only from a link within alert messages generated using _#COLLFORM alias (set in Alerts Admin - Settings: form URL.

To create the required anonymous form for the subscribe.shtml and update.shtml pages...

  1. Within My Readers > Slice Admin > fields: check Required for 'Email' and uncheck Required and Show for 'Password'.
  2. Slice Admin > Anonymous Form Wizard
  3. Copy the form HTML and paste into the file subscribe.shtml. Add some preable text and upload to the URL you specified.
  4. Upload subscribe_ok.shtml to specified URL.
  5. Paste the same form HTML in to update.shtml. In the <form> change the value of the two hidden fileds "err_url" and "ok_url" to the update.shtml URL. Upload.

You should now have a page for users to subscribe to the alert (e.g. origianl sandbox alert subscribe form) that when submitted correctly leads to the OK page saying "Check your inbox for an email confirmation". In the confirmation/welcome email there should be link with unique ID pointing to the the update.shtml URL. When visited, this page will confirm the email address and allow thye user to modify their subscription settings, inluding change their setting to "not subscribed".

You should test this subscritpion process, including updating subscription settings. Add some new items to My Slice and check that subscribers receive them as expeceted.

Make Forms Pretty

You may also want to simplify the anonymous form by hiding the selection check box and possibly the "how often" select box. To hide the selection checkbox, just change the input type from "checkbox" to "hidden", and remove the surrounding text. To hide the "how often" select box you need to create a hidden input with the name and one value pulled from the "how often" select box. The final cleaned up form could look like the sandbox alert subscribe form.

You may also want to similarily modify the update, see sandbox alert update form.

Step 5: Customize Your Alert Messages

If you haven't already, you will want to customize the alert welcome message (sent once upon subscription for email confirmation) and the alert message template.

Alert Welcome Message

Like any important text, you should probably use a word processor to write and check spelling of the message to sent. You can use HTML or plain text. You will want to include:

To update the test, go to you Alert Module > Settings and click edit icon beside welcome email select box. Both the subject and body processes aliases and {} commands.

Alert Message Template

The alert message template is edited the same as Welcome Message, except that _#FILTERS_ will be replace by the views of the new selections. You will want to include:

The views of selections can accessed through My Alerts Module > Selections > click on selection name. It is probably best to put the introduction to each slice's items within the top HTML for each slices Alerts Selection Set view. This is more important when there are multiple selection options within an alert module.


Tips

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.

Customize Result Messages

To customize result messages, (i.e.. confirmation, error or update messages at the top right of anonymous forms) use show_results.php3: Copy the script from doc/script/show_result.php3 to the same location where you created myalerts.shtml.
When creating anon form: Fill the URL of yours show_result.php3 and check the box “Use a PHP script ...”

1. General usage of Anonymous Forms
2. Filler and fillform
3. Creating Anonymous Forms with the Wizard
4. Editing with anonymous forms
5. Tips and tricks
6. Reader management specifics
7. Show results

Abstract

Explains the basic idea, creation and settings of Anonymous forms. The name anonymous is in some cases not accurate, as the form is used for reader personal info and the readers must be authorized to edit their own info.

See also: doc/reader.html, doc/alerts.html, doc/script/show_result.php3

1. General usage of Anonymous Forms

Anonymous forms are similar in function and design to the Add / Edit item page. The main difference is they are placed outside of the AA Control Panel and thus do not provide the AA authorization and have a design of their own.

The most common usage is to allow web readers to suggest new content. After filling the Anonymous form it is sent to the Holding Bin and a Thank you page appears. But you can also allow readers to edit items with the Anonymous form.

2. Filler and fillform

Two scripts handle the anonymous forms. The first, filler.php3, stores the info coming from the form into the database. It also validates the data and prooves permissions to edit or update the item. The second, fillform.php3, refills the data into the form shown to the reader. It retrieves the data from database or in some special cases directly from filler.

3. Creating Anonymous Forms with the Wizard

In the previous AA versions until version 2.4, the process of creating Anonymous forms was very simple: Copy the code of the Add item page with only a few necessary changes. But as the form now allows to edit items and to use several options for it, a new wizard was created. This wizard creates the HTML code for a complete form with the SSI include of fillform.php3 necessary to edit items. The resulting form differs depending on whether Anonymous editing is allowed or not.

You may change these settings in the wizard or later in hidden fields:

Table 1. Wizard settings

err_url The URL to which the script filler.php3 jumps when some error occurs. It may be the same page on which the form is shown.
ok_url Like err_url, for successful changes.
show_result The URL of a PHP script which receives the results from filler.php3. This allows for a completely free design of how the errors are presented to the user. See below.

If you are interested to know more about what the form contains, here are some remarks:

4. Editing with anonymous forms

If you want to edit items with anonymous forms, first you must allow to choose which item to edit. You can create a view and add a link to the headlines, which links to the anonymous form and contains the parameter my_item_id=11a7cc0908d77c22bf2c7ca43cdd8480. Another approach is used in Reader management slices, see below.

You must choose the correct setting in Slice Admin - Settings - Allow anonymous editing of items, which is used by the filler.php3 script on an item update request. The options are:

Table 2. Anonymous editing options

Not allowed Never allow to update items
All items Always allow
Only items posted anonymously For items posted anonymously, filler always sets the ITEM_FLAG_ANONYMOUS_EDITABLE flag. By choosing this option you allow only items with this flag set to be edited.
Only items posted anonymously and not edited in AA Similar to the previous one, but when you edit the item in the control panel, the flag is cleared and thus the item is no more allowed to be edited anonymously.
Authorized by a password field filler looks for a field of type Password (with Id beginning with password....) and requests the password sent by the user to match. The password may be set on item creation. If the field is not flagged required, an empty password may be used. The new Field Input Type, Field Insert Function and Field Validate Functions Password and Change Password provide the usual edit boxes for changing, deleting and entering password, which is stored encrypted. The disadvantage is the password must be sent on every update.
Readers, authorized by HTTP auth This is a special option, useful only for Reader management slices. The username given to the browser on HTTP authentification is looked for in the database. Each reader may edit only his or her personal info.

5. Tips and tricks

6. Reader management specifics

Each reader has her or his own item in the Reader management slice. Thus the HTTP authentication described above may be used directly to determine which item (reader personal details) to show in the form.

In this case two forms are needed, one being the publicly accessible subscribe form and the second being the HTTP protected Change personal details form. Because the fields on both the forms may be the same, you can use one form and include it into two different .shtml pages.

For webs not using Auth we need a way to ensure nobody not only edits but even views the data. This is achieved by assigning a special Access Code (see the Reader management documentation) to each reader, which must be added to the URL in order that the data are prefilled. The password authorization described above is than used on item update.

7. Show results

Sending the data to AA results in adding the data into database or in an error. Some of the errors may be excluded in advance by Javascript validation (function proove_fields). But some of them, like a username being already used, can not.

By default, the fillform.php3 script shows standard error messages. They always appear at the place where fillform.php3 is SSI-included in your shtml page.

You may create your own PHP script (see an example in doc/script/show_result.php3) and send its URL as a value of a show_result variable. Add it as a parameter to the fillform.php3 SSI include created by the Wizard, e.g.

<!--#include virtual="/aaa/fillform.php3?show_result=http://ecn.cz/show_result.php3&form=..."-->

An array $result with the results will be sent to the PHP script and you may print appropriate messages, see the example.

The $result array content is created at various places in filler.php3 array. Look there for accurate info. At this moment the messages are:

Table 3. Results from filler.php3

fatal Fatal error. Several messages related to the slice, not to the particular item. These errors help on creating the web page.
validate Array with not validated fields, field_id => message, e.g. headline........ => This username is already used created on field validation. You may create your own messages depending on the field_id.
permissions Missing permissions. Depending on the setting for Anonymous editing (see above), this item did not fullfill the requirements.
store Some error in StoreItem. Usually this points to an inner AA error.
success No error. The operation was successfully done. The value is insert or update (i.e. $result["success"] == "insert" or $result["success"] == "update" in the show results script).
email_confirmed Added by fillform.php3 on Reader management slices: When the reader successfully confirms his or her email by using the URL sent in an email, fillform adds a message email_confirmed => OK. This message is added only when the email has not yet been confirmed.
unsubscribed Added by fillform.php3 on Reader management slices: When the reader unsubscribes from Alerts (which is achieved by setting How often to an empty value).

Discussion: A similar result may be achieved by adding several fields to the form, e.g. fields

err_page[validate][username......]="err_username.shtml"
err_page[validate][*]="err_validate.shtml"
err_page[*]="err_unrecognized.shtml"

and by creating the .shtml pages with a static message concerning the particular error. The main advantage of this approach is the web administrator may not know PHP. The disadvantage is the necessity of creating many pages but using SSI includes the pages could look only like:

<!--#include file="err_top.shtml"-->
The username you entered has already been used. Please try another username.
<!--#include file="err_bottom.shtml"-->

 

This FAQ interface was developed by Jason at Commons.ca

APC: Internet and ICTs for social justice and development APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development