TellAFriend

Summary: Gives Form to Send Page to Friend

Version: 2.1.3 (3.0.0 under development)

Prerequisites:

Status: Beta

Maintainer: BenWilson

Categories:

Discussion: TellAFriend-Talk

File: pmwiki-tellafriend-2.0.zip Δ

File: tellafriend-2.1.php Δ Stable

File: tellafriend-3.0.0.zip Δ (Development)

Abstract

When visitors visit a page they find interesting, they share the page with others. PmWiki does not provide native support for sharing pages with others via a web form. This recipe allows the site administrator to create a form interface allowing visitors to share pages, including robust email validation.

Significant Changes of Version 3.0.0

Version 3.0 is a ground-up rewrite of this recipe. This recipe relies on the XPertMailer package to send the email, rather than PHP's mail() function. The purpose for using the XPertMailer package is to incorporate that package's spam-filter friendly method of sending email.

This version also introduces a three-tiered approach to validating both the sender's email and the email addresses of recipients. This is done first by validating the format of the email address. Then, the domain of each email address is queried to determine whether it has a valid MX record. Having a valid MX record tells us that the domain receives email. If no such MX record exists, then the software seeks to verify that the domain itself exists. If the email address is validly formed and has either an MX record or valid domain, then the address is accepted.

Previous versions of this recipe required the site administrator to know HTML in order to define a different form than the one provided. Version 3 uses a wiki page instead, which allows the site administrator to write the form using PmWiki markup.

Installation

Installing the Software. To use Tell-A-Friend, you will need to expand the compressed file (i.e. the '.zip' file) in your wiki's cookbook directory (typically $FarmD/cookbook). This recipe creates a sub-directory where its files are stored. Then, include the script in the local/config.php file (e.g. include_once('path/to/TellAFriend/default.php');).

Setting Key Variables. Key variables to set include $TAFEmailAdministrator which is the administrator's email address. Additionally, Tell-A-Friend expects its form to be located on $SiteGroup/TAForm. The page may be changed by setting a local value to $TAFMailFormPage.

Create Form Page. Finally, the site administrator must create the form page. No form is provided by default. The default location for this is $SiteGroup/TAForm, but may be relocated. The following markup is a sample form that contains all fields Tell-A-Friend relies on to send email. Just cut-and-paste this markup into your Tell-A-Friend form page.

{$TAFErrors}
(:table id=taf border=0:)
(:cellnr:)Your Name
(:cell:)(:input form id=taf method=post:)
(:input text name='name' size=30:)
(:cellnr:)Your Email
(:cell:)(:input text name='email' size=30:)
(:cellnr:)Send To:
(:cell:)(:input text name='to' size=40:)
(:cellnr:)Send Copy to Self:
(:cell:)(:input checkbox chkSendSelf 1:)
(:cellnr:)Message:
(:cell:)(:input textarea name='text' cols=40 rows=5 noscroll=noscroll:)
(:input hidden name='ip' value='':)
(:input hidden name='action' value='taf':)
(:input submit name=post value="Go":)
(:input end:)
(:tableend:)

Locating the Form. Tell-A-Friend uses the standard PmWiki directive markup to position the form. In order to place the form, use the (:tellafriend:) markup on the page. If you want the form to appear on all pages of a group, place the markup on the GroupHeader or GroupFooter as approprite.

Known Issues

The current email validation assumes the presence of a function that may not exist on Win32 servers. When this problem presents itself, I will add in the code to make that work. I lack the means to test and time to implement fully. BenWilson August 21, 2006, at 06:33 PM

History

V.3.0.0 - BenWilson August 21, 2006, at 06:19 PM
- Ground-up rewrite.
- Three-tier email address validation.
- Utilization of wikipage to create form.
20041208 PmWiki 2.0.beta6 version
2004-02-12 Initial versions

Contributors

BrBrBr
Jeff Barke (jbarke@milwaukeedept.org)
BenWilson
- 2006-01-04 Patched to version 2.1,
- 2006-08-21 created version 3.0.0.