• View
• Edit
• History
• Print

MailForm

Basic setup

To just get a basic form that can be used to send mail, simply install the Cookbook:PmForm module and then add the following lines to a local customization file (e.g., local/config.php):

    include_once("$FarmD/cookbook/pmform.php");
    $PmForm['maildemo'] = 'mailto=mailform-demo@pobox.com form=#mailform fmt=#mailpost';

(for multiple addresses, use quotes around all of them and commas in between)

    $PmForm['maildemo'] = 'mailto="mailform-demo@pobox.com, anotheraddress@samplemail.com, a@a.com" form=#mailform fmt=#mailpost';

Then, wherever you want a form to appear to send mail to pmichaud@pobox.com, use the directive

    (:pmform maildemo:)

The "maildemo" portion of this directive is called the target, and it indicates that the mail is to be sent according to the options given by the corresponding entry in the $PmForm array. Within the 'maildemo' entry, "mailto=" specifies the recipient address for the email, "form=" specifies the form template to be displayed by the (:pmform maildemo:) directive, and "fmt=" specifies the template for the email to be sent.

Example pmform directive

(:pmform maildemo:)

Your address: Subject: Message:

The above mailform actually works -- see mailform.txt to see what the mail looked like when it was received.

Customized templates

The "form=" and "fmt=" options specify pages or page sections to be used for displaying the form and formatting the form output. If only a section identifier is given (e.g., "form=#mailform"), then PmForm looks in the Site.PmFormTemplates and Site.LocalTemplates pages for the template.

The "form=" option specifies the template to use for the form displayed by the (:pmform:) directive. Usually this is built using PmWiki's (:input:) directives.

[[#mailform]]
(:template defaults successpage='' :)
(:input pmform target={$$target} successpage={$$successpage} :)
(:input default request=1:)
(:messages:)
||width='' 
||$[Your address]: ||(:input text from size=30:) ||
||$[Subject]:      ||(:input text subject size=30:) ||
$[Message]:\\
(:input textarea text rows=8 cols=60:)\\
{$Captcha} (:input captcha:) \\
(:input submit name=post value='$[Send]':)
(:input end:)
[[#mailformend]]

The (:input pmform:) line specifies that this is a form to be handled by the PmForm module, and that it's to process the form according to whatever target was given by the (:pmform:) directive. Here, the form contains three fields to be filled in by the sender: the sender's address ("from"), the message subject ("subject"), and the text of the message itself ("text").

The "fmt=" option specifies the template to use for sending the email based on the inputs provided by the form. For example, the #mailform template that comes with PmForm contains:

[[#mailpost]]
(:template require from errmsg="$[Missing 'from' address]" :)
(:template require subject errmsg="$[Missing message subject]" :)
(:template require text errmsg="$[Message text required]" :) 
(:template require if="captcha" errmsg="$[Captcha required]" :)

{$$text}

==========
Sent via PmForm at {$$PageUrl}
[[#mailpostend]] 

The (:template require:) directives are used to specify certain conditions that must be met before the mail can be set. For the above, this template requires that the "from", "subject", and "text" fields supplied by the sender are non-empty (and specifies error messages to display if they aren't).

The remainder of the template specifies the body of the email to be sent by PmForm. The {$$text} field is replaced by the message text coming from the input form, and {$$PageUrl} is substituted with the url to the current page. (The "from" and "subject" fields are automatically handled by PmForm.:)

The {$$...} template substitutions may contain any arbitrary page variables or input fields coming from the form.

Comments

Is it possible to put the "form=" and "fmt=" parameters directly into the (:pmform:) directive? (so that modifying the local configuration file is not necessary)

I just took a quick look at the code, and it doesn't seem to support that. However, it does seem that the target name can be the name of a text field on the page. (I'm not sure if thats the source page or the target page though), so that one should be able to do something like:

 (:pmform foo:)
 ...
 foo: mailto=mailform-demo@pobox.com form=#mailform fmt=#mailpost

and have that work.

Define email in LocalTemplates page

After messing around, adapting the config file with PmFormPageFmt, allowed me to define the target in the LocalTemplates page.

To provide some very basic email validity testing (which is better than none), change line 151 of pmform.php from

    $errors = PmFormMail($pagename, $msgtmpl, $opt, $safe_opt);

to

    if (strpos($opt['from'],'@')) $errors = PmFormMail($pagename, $msgtmpl, $opt, $safe_opt);
    else $errors = "Please enter a valid email address.";

Ben Stallings? December 08, 2008, at 07:33 PM