NP_MailForm.php

This plugin allows you to add forms to your skins or items that will be mailed to a given address or addresses when submitted by site visitors. Spam fighting measures can be implemented on each form. File uploads are permitted.

It is based on a plugin I wrote to have employment applications submitted on-line that would be mailed to a backend system for processing.

This plugin includes the htmlMimeMail package (http://www.phpguru.org/), © Copyright 2004 Richard Heyes, distributed under the GNU General Public License version 2.

To upgrade to 1.12 or higher from 1.11 or lower, replace all the files, then go to the Plugins Management page in the admin area and click the Update Subscriptions button near the bottom. If you do not do this, the formdata will not be available on your thanks page.

1. Unzip the file and upload the contents to your plugin directory
2. Install the plugin…
3. Define a form on the plugin admin page, see the example form to get started. Add the form to your skin or item using one of the methods described below.

NOTE: The most up-to-date documentation is maintained in the help file delivered with version 1.10 and higher. Additional features are available that are not described here, such as custom output templates for the email body and subject, javascript validation of required fields, javascript date picker control for date fields, additional skinvars for generating html input fields and buttons.

In order to use this plugin, you need to create an html form that includes the fields you desire and the submit button. You do not need the initial form tag. You will then add a few MailForm tags to add the MailForm features to your form. You can store the form in one of three ways as described later.

A sample form is shown below:

 <%MailForm(status,mycontact)%><br />
 <%MailForm(startform,mycontact)%>
 <%MailForm(sticket,mycontact)%>
 <p align="left">
 <b>Name (Required)</b><br />
 <input name="FullName" size="30" value="" />
 </p>
 <p align="left">
 <b>Email Address (Required)</b><br />
 <input name="EmailAddress" size="30" value="" />
 </p>
 <p>
 <b>Question (Required)</b><br />
 <textarea name="Question" cols="50" rows="10"></textarea>
 </p>
 <p>
 <b>Attachment</b><br />
 <input type="file" name="SupportFile">
 </p>
 <p>
 <%MailForm(captcha,mycontact)%></p>
 <p>
 <font size="2">
 <input class="formbutton" name="B1" type="submit" value="     Submit     ">
 <input class="formbutton" name="B2" type="reset" value="     Reset     ">
 </font></p>
 </form>

• <%MailForm(status,formname)%> - Displays the status message defined in the form definition (or a default message) when a form is successfully submitted.
• <%MailForm(startform,formname)%> - Inserts the html code (the <form> tag) to start a form that will be processed by NP_MailForm. formname should be the name of an existing form defined in the plugins admin page.
• <%MailForm(sticket,formname)%> - Inserts a key into the form that is uniwue to the visitor's IP address. This is a spam-fighting feature. The key is checked by the form processor and if that IP address hasn't loaded the form within the past 30 minutes, the submission will be denied.
• <%MailForm(captcha,formname)%> - Inserts the code required for a captcha test (characters embedded in an image) for guest visitors. Requires NP_Captcha.
• <%MailForm(form,formname)%> - Inserts the contents of the Form Body field from the form definition. The Form Body field should contain all the html and MailForm tags to create the entire form. This allows you to store the form in the db and call it anywhere in your skins or items by using a single tag.
• <%MailForm(template,formname,loginAware)%> - Inserts the form by parsing a file called the same as formname.template in the nucleus/plugins/mailform/forms/ directory. If the loginAware parameter is 'yes', this tag will look for a file called formname.loggedin.template if the user is logged in or formname.notloggedin.template if the user is not logged in. This is much like the way the Nucleus CMS core handles comment, login, search, and membermail forms. The advantage of this is that you can show different forms (or no form) to logged in visitors and to guests. You can also make use of some special tags in the template that inputs certain variables that you may need in the form. The form of these tags is <%formdata(parameter)%> and an example is given for the mycontact form in the distribution files. The available parameters are listed below (some are only useful for logged in users):
  • memberid - if on member detail page, this is the id of the user whose page is being viewed
  • realname - if on member detail page, this is the real name of the user whose page is being viewed
  • displayname - if on member detail page, this is the display name of the user whose page is being viewed
  • email - if on member detail page, this is the email of the user whose page is being viewed
  • url - if on member detail page, this is the url of the user whose page is being viewed
  • language - if on member detail page, this is the language of the user whose page is being viewed
  • mnumber - id of the logged in member
  • mrealname - real name of the logged in member
  • mdisplayname - display name of the logged in member
  • memail - email address of the logged in member
  • murl - URL of the logged in member
  • mlanguage - preferred language of the logged in user
  • fieldname - all values of fields from a posted form can be recalled by name.

• Add MailForm to quickmenu? Whether to include a link to the MailForm admin page in the left navigation bar of the admin area. Yes or No.
• Delete database tables on uninstall? Whether to delete the database table when you uninstall the plugin. Yes or No. Should only be set to Yes if you are going to permanantly remove the plugin.

• see examples for tips.

• Version 1.13, release 05 Oct 2009
  • make emails go out in html and text format for better looking emails
• Version 1.12, release 11 June 2009
  • Fix some moreXHTML strict compliance issues, thanks, Leng
  • Use sessions to allow passing of form data to thanks page for improved configuration options on that page, see the help.html file.
• Version 1.11, release 08 June 2009
  • Fix some XHTML strict compliance issues, thanks, Leng
• Version 1.10, release 18 April 2009
  • Use of templates for form output (email body)
  • Add field and button skinvars to generate simple form fields and buttons
  • Add javascript options for required field validation and date picker control
• Version 1.00, private release
• Version 0.92, release 10 July 2008
  • xhtml compliance fix
  • workaround for deprecated mime_content_type function
• Version 0.91, release 24 January 2008
  • bug fixes
• Version 0.9, released 15 January 2008
  • Initial Public Release