Parental Approval of Subscriptions
================================================

The Lyris extension "pap" perfoms the task of allowing parental approval
of subscription requests.  The idea is that a child requests to join a
mailing list, but is required to give their parent's email address so that
th e parent can approve of the subscription.  The child fills out a web
form giving their email address, and their parent's email address.  This
extension this sends an approval request to the parent, and a notification
to t he child. When the parent approves (or denies) the approval request,
the child's subscription is changed accordingly, and the child receives an
acknowledgement.

This documentation page explains how to install this Lyris extension on
your server. This is a good example of a Lyris extension script, and the
kind of functions you can perform with one. This extension is available at
n o cost.

Download and Extract the files
================================================
First, you will need to obtain the rdoc extension, by downloading pap.zip
from http://www.lyris.com/down/scripts.html

The pap extension files are stored in this ZIP archive, but work equally
well on Unix. Use Winzip or Pkunzip or 'unzip' (if you are on Unix) to
extract the files out of this archive into a directory, from which you
will r un your Lyris extensions.  On Windows, we recommend C:\lyris\ext
while on Unix, we recommend /opt/lyris/ext

Copy the file "lyris.plc" from your CGI-BIN (or scripts, if using IIS)
directory, into this directory.

If you are on Windows, and you used a directory other than c:\lyris\ext
you will need to edit rdoc.bat to reflect the directory path you used.
Also, if your installation of perl is not located in c:\perl5 you will
also ne ed to edit this file.

If you are on Unix, be sure to do a "chmod 700 /opt/lyris/ext/pap.pl" to
make the file executable.

Next, you will need to copy the "papsub.pl" script to your CGI-BIN
directory (or SCRIPTS, if you are using IIS).  If you are using Unix, be
sure to run "chmod 777 papsub.pl" to make the file executable.

Finally, copy the "papsub.html" file to an HTML document directory on your
web site.  This is an example of the web subscription form, that you can
modify, and if you like, embed in another web page.


Set the Extensions Directory
================================================
Go to the Server Config page of the Server Admin menu, and locate the
"Extensions Directory" option, which is in the "Programming Extensions"
group on the Server Config page.

Set this setting to be the directory where you placed the files from the
rdoc archive file.  If you followed our recommendations for default
directories, you would type "c:\lyris\ext\" on Windows, or
"/opt/lyris/ext/" on Unix.  Remember to include the final slash, or your
extensions will not work.

Save your new Server Config settings.

Edit the Subscription Form
================================================
Pull up the papsub.html file in a text editor.  You will need to change
the following pieces of information in the form, so that it works on your
site.

Where you see the text:

<input type=hidden name=goto_url value="http://xxxxx.xxxxxx.com/">

change the value="" portion to be a URL that you want the subscriber sent
to after they fill out the form.

Where you see the text:

<input type=hidden name=goto_text value="Click here to return to xxxxx">

change the value="" portion to be the text that you want the subscriber to
see after they fill out the form.

Where you see the text:

<INPUT TYPE="hidden" NAME="list" VALUE="signup-list1@xxxxx.xxxx.com">

change the value="" portion to be "signup-listname@youserver.com", that is
to say, to be the word "signup-" prepended to the list address of the
mailing list in question.

Note that you have the option of having this script offer check-boxes to
let the subscriber choose what lists they want to join, and to join
several lists if they like.  If you want to do this, remove the line
above, and replace it with lines like this:

<input type="checkbox" name="list"
Value="signup-list1@xxxxx.xxxx.com">List One<br>

Write a line like this one for each list that the subscriber can consider
joining.


Create a Template User
================================================
Go to the Members page of your Lyris web interface, and create a member
with the following settings:

Email address: template@template.com

Name: template

Status: confirm - awaiting confirmation from user

All new members of this mailing list, which use the parent approval
script, will be copied from this "template" member. You should set any
other settings that you think are appropriate.

Save the member.


Create the Documents
================================================
Use the Lyris web interface to go into the List Administrator menu, and
choose to create a new document.

You will need to create three documents for this extension to work
correctly.

First, you will need to have a "welcome" document that the person will
receive when the subscription is approved by the parent.  You define the
document in the list's "list info" page.

Next, you will need a "your subscription is pending" document, which tells
the child that the parent must now approve the subscription.

Here is an example of what we filled in for our sample document:

Name: list1-pending

Language: English

Type: RESPOND

Title: Your subscription request was received

Body: Your request to join the '$subst('Member.List')' mailing list has
been received.

An approval request has been sent to '$subst('Member.Additional')'.

When the approval for your subscription is received, you will become a
full member of the mailing list.  -----------------------------

The mail merge codes $subst('Member.List') and $subst('Member.Additional')
may be used.  The $subst('Member.Additional') refers to the parent's email
address, and is saved in the member's "Additional" field for archival p
urposes.

Finally, you will need a "your approval is needed" document, which is sent
to the parent.  

Here is an example of what we filled in for our sample document:

Name: list1-need-app

Language: English

Type: RESPOND

Title: Your approval is requested

Body: The email address '$subst('Member.EmailAddr')' has been entered for
a subscription to the '$subst('Member.List')' mailing list. 

This new subscription requires your approval before it will become active.

To approve of the subscription, simply reply to this message.  

Make sure that your message is addressed to
lyris-confirm-$subst('Member.MemberID')-@$subst('Site.Hostname')

You will receive notification that your confirmation has been approved.

If you do not want to approve the subscription, do nothing.  The email
address will be automatically removed. If you want to immediately reject
the subscription, forward this message to 
leave-$subst('Member.List')-$subst('Member.MemberID')-@$subst('Site.Hostname') .


-----------------------------

The mail merge codes $subst('Member.List'), $subst('Member.EmailAddr'), 
$subst('Member.List'),  $subst('Member.MemberID') and 
$subst('Site.Hostname') may be used.


Create the Autoresponder
================================================
From the List Administrator menu, choose the auto-responders menu, and
then choose to create an autoresponder.

In the create autoresponder page, put the email address you want the
autoresponder to use in "email address".  We recommend that you use the
word "signup-listname" as the email address.

In the "response" field, choose "nothing"

In the "run a program before" field, enter text that looks like this:

pap.bat $MESSAGEID list1 lyris@yourdomain.com yourdomain.com english
list1-pending list1-need-app

You will need to change the items on the command line to fit your needs.
The parameters are:

pap.bat: this is the program name to run. On Unix, this should be
"rdoc.pl"

$MESSAGEID: this is required, in order for the script to know what
incoming message to look at

list1: this is the name of the mailing list under which the documents have
been created.  

lyris@yourdomain.com: this is the email address that will be used in the
From: field when the extension sends a "your subscription is pending"
message to the child.

yourdomain.com: this is the hostname of your Lyris server, and is used to
build the From: address of the parental approval request.

english: the language that was used to create the documents.

list1-pending: the name of the document to send to the child.

list1-need-app: the name of the document to send to the parent.

Save the autoresponder.


Test the Autoresponder
================================================
Use your email program to send an email message to the autoresponder. Put
the parent's email address in the Subject line of your message.  For
example, your message might look like this:

From: me@somewhere.com

To: signup-list1@mydomain.com

Subject: myparent@elsewhere.com

You should receive a document in a few moments. If the extension does not
work correctly, run Lyris in the foreground, with debugging information
displayed, with the command "lyris start debug".  This will show you
information when the extension is run, and what the problem is.


Test the Web Signup Form
================================================
Next, use your web browser to display the papsub.html document.  Fill out
the forms, submit it, and test if it works.
