Lexasoft Formmailer

Version: v1.5.6

Content of this file

 

Content of this supply
./formmailer/readme.htm This readme - file
./formmailer/first_sample Directory, containing first sample to which the section "How to create a form" refers.
./formmailer/basic_sample Directory, containing sample for easy use. Just basic features are used here.
./formmailer/advanced_sample Directory, containing sample for advanced use. Advanced features are used here.
./formmailer/upload_sample Directory, containing sample for upload feature.
./php-bin/ls Directory, containing the Lexasoft php class framework.
./php-bin/ls/config/mail.inc General configuration file for sending email. Should be customized to fit to Your needs.
./php-bin/ls/htmlmimemail Directory, containing email framework by phpguru.org. Please check their website for details.

Back to start

System requirements

Please note: Since Formmailer 1.5.1 there is no need to set "register_globals" to "ON" when using PHP 4.2 or above.
Formmailer 1.5.6 will be the last version to support both PHP4 and PHP5. We are going to withdraw PHP4 support in future.

Back to start

Installation

If You are updating from a previous version, please read update section.


Please note: If You want to use upload function, please read the chapter about this module.

 

Back to start

Update to v1.5.6

Before You start updating, check the version of Your formmailer from the readme file in Your original supply.

For a list of changes see appendix g , please.

Before You start, make a copy of Your current installation just to make sure... ;-).

If You are updating from v.1.5.5:

If You are updating from v1.5.1_02, please do the following:

If You are updating from v1.5 or v1.5.1:

Back to start

Basics and features

There are a few things to be kept in mind, using Lexasoft formmailer:

Back to start

How to create a Form

The easiest way to create and use a form with Lexasoft formmailer is to customize our samples. But, however, to create a form completely on Your own, You do have to do the following:

  1. Insert the following lines into Your page right at that point, where the form should appear:

    <?php
    // Include formmailers library (make sure this points to the email.inc file from this delivery):
    require_once "../../php-bin/ls/email.inc";

    // Create Object and initialize from configurationfile.
    $theFormMailer = new FormMailer();
    $theFormMailer->initFromPropertyFile( "./formmailer.cfg");

    // Output to Browser.
    $theFormMailer->out();
    ?>

    Please note: The page You insert this code into, must be a page that will be parsed by php. Usually those files end with .php, .php4 or .php5. If You are not sure, please contact Your system administrator for assistance.

  2. Create a template for Your form. This should be a "normal" html page, containing all directives for a html form, as usual.

    There are only three things to be looked at:

    1. Make sure, the "action" attribute inside the form tag points at the page, You inserted the php code in (as shown in point 1). You can do this extremely easily by writing "%script%".
    2. Make sure, the "method" attribute inside the form tag has the value "POST".
    3. You should pay attention to the names of the input elements ("name" attribute in their tags). This is how You can access the values, the user has been filled in, afterwards.

    Here is a very simple example of a form:

    <form method="POST" action="%script%">

    Your name: <input type="text" name="name" ><br>
    Your comment: <textarea name="comment"></textarea><p>
    <input type=    "submit" value="send" name="ok" >
    <input type=    "reset" value="cancel" name="cancel" >

    </form>

    You can use Your favorite html editor to do that and therefore You can create the form with any design You like. You should save this template into the same directory as where Your form is to be found.

    Please note: Only the part between <body> and </body> of Your template will be used.

    Use the name of this file in Your configuration file in key "FormTemplate". (See point 3).

  3. Create a cfg file. You must name it exactly as used in the $theFormMailer->initFromPropertyFile instruction (see point 1).

    Fill in at least the following keys:

    FormTemplate: The name of the template file for the form (see point 2)
    MailRecipients: The recipients of the feedback mail, seperated by ",".
    MailSubject: The subject of the feedback mail.

    We recommend to fill in the following keys as well, though this is not always neccessary:

    MailFrom: Sender of the feedbackmail (Header "From:").
    MailReplyTo: This adress will be written to Header 'ReplyTo'. This adress will be used, if the button "Reply" is pressed in the mailclient.
    MailReturnPath: Adress, to which the mail will be sent back, if it is undeliverably.

     

    Please note: Write "%MailFrom%" for the last two keys. Thus it is made sure, that they are identically to the value in MailFrom:

    MailFrom = myaccount@mydomain.com
    MailReplyTo = %MailFrom%
    MailReturnPath = %MailFrom%

After finishing those steps, You do have a basic form, which sends You a simple list of posted fields per email. It might look like this:

Form was sent:

- name:  Madonna
- comment:  Nice site You\'ve got here !
- ok:  send

Our first example shows, how this simple variant would look like.

In the following sections we will see how we can go on with this and we will have a closer look to the configuration file and the validation rules, provided with Lexasoft formmailer.

Back to start

How to go on

This first example, of course, is not very pretty at all. So how can we improve this result? There are several ways to do this:

Back to start

How to handle uploads

Since v1.5.5 Lexasoft formmailer directly supports upload of files to Your server. As this is a bit something special, we will handle it in this seperate chapter.

First of all: A fully working sample of the upload feature is included in this supply. We recommend to customize it to Your needs. Nevertheless it might be, You want to add upload capability to one of Your existing forms. So here is, how to do this.

Please note: If You are unsure, which mime type to use, You can find out as follows:

  • Make sure, the list of mime types in formmailer.cfg contains at least one entry. You can use the entries from the sample, if You don't know any.
  • Try to upload one of the files, You want the users to allow to send You.
  • If the mime type is not allowed yet, it is now shown in error message, provided, You did not remove the %UploadUserMimeType% from the message in lang.XXX.cfg. You can now add the mime type to Your list simply via copy and paste.
  • Sample contains a list of mime types for images (jpg, gif, png format) working with most of the browsers (IE, Netscape, Opera, Mozilla, Firefox).
Please note: The file input field must not be optional. A file to upload in this upload form must always be given.
Please note: For a list of substitutes, used by upload feature, check Appendix F.

Back to start

How to deal with spam

Spam, unfortunately, is a serious problem, we must take care of. There two aspects about this:

  1. Make sure, our mails will not be recognized as spam.
  2. Make sure, our feedback cannot be misused to send spam.

Regarding 1)

Regarding 2)

Spammers do not only use "normal" mail to provide spam mails, but also forms as used in Lexasoft.de formmailers. They do this by posting unwanted content directly to the mailing script.

Spammers use special scripts, that can post to many thousands forms across the net in just a second. That's why You can't get them with any client side Javascript evaluation in Your form.

Use the Lexasoft.de server side evaluation insted to recognize spammers and prevent them from sending spam. Although there are (up to now) less special "anti spam features", the rate of recognizing spam in practice is nearly 100%. Some of the websites we operate, are confronted with several thousands spam attacks a day.

Most of them are unsuccessful, just one or two of them in a month may be successful and send a mail.

Here are some hints, how to do this.

One last hint: Always keep an eye on all mails, sent by Your formmailer. The feedback itself, of course, usually is sent to You, only. Lexasoft.de formmailer does not allow to send this mail to any other than the recepient, configured in formmailer.cfg.

But the response mail (if You provide one), usually is sent to the email adress, the user provides. Thus a spammer could send a mail to any email address abusing Your form. This is a danger, You must face.

First of all: consider, whether You really need a response mail. In some cases this is "counterproductive", as the user might feel disturbed from an automatic message.

If You need to provide a response mail, please keep an eye on the following:

Back to start

Appendix A - Configuration files

This section shows You how to use configuration files. There are generally two configuration files used with Lexasoft formmailer: The formmailer.cfg (or similiar) which contains all configuration information and the language file, which can contain all messages. The language file is optional.

The configuration file syntax in fact is very simple. Here are the rules:

These are the common rules for configuration files. Please also note some special rules for the Lexasoft Formmailer:

Back to start

Appendix B - Validations

Lexasoft formmailer provides some validation to check, whether users input was valid. These are the following:

A validation for a arbitrary field in configuration file generally is configured as follows:

<ValidationName>.<FieldName> = <ValidationParameter1>, [<ValidationParameter2>,...] <ErrorMessage>

For example a validation of minimum length could look like this:

ValMinLength.name = 1, Please enter a value in Field name.


Please note: If the parameter(s) itself contain a comma (","), it might be usefull to quote all parts of the value with " or '. Therefore the sample above can also be written like this:

ValMinLength.name = '1', 'Please enter a value in Field name.' or
ValMinLength.name = "1", "Please enter a value in Field name."

In error message You can access all posted fields by quoting them in %. In addition there are some special values accessiblly with some validations. Please check this below.

ValMinLength and ValMaxLength

Validation name: ValMinLength resp. ValMaxLength
Number of parameters 1
Parameter 1 Minimum resp. maximum length of input in that field.
Additional values %currentlength%  current length of input.
%minlength% Minimum length of input (ValMinLength)
%maxlength% Maximum length of input (ValMaxLength)
Example of usage ValMaxLength.text = "255", "Value in field <b>Comment</b> must be at most %maxlength% characters long. Current length: %currentlength%."

ValIncludePattern and ValExcludePattern

Validation name: ValIncludePattern resp. ValExcludePattern
Number of parameters 1
Parameter 1 Pattern that should be ex- resp. included. This pattern is a perl compatible regular expression, with one important exception: An escape sequence must start with \\, not just \ as usual. For example: Write \\s instead of \s for a whitespace.
Additional values none.
Example of usage ValExcludePattern.name = "/[^a-zA-Z0-9äöüßÄÖÜâÂêÊîÎéÉ\\.\\,\\ \\-\\+*]/", "Value <b>%name%</b> in field <b>Your name</b> contains characters which are not allowed here."

ValEmailAdress

Validation name: ValEmailAdress
Number of parameters none.
Additional values none.
Example of usage ValEmailAdress.email = Value <b>'%email%'</b> in field <b>Your email</b> is not a valid email adress."

ValIsInPost

Validation name: ValIsInPost
Number of parameters 1 - n
parameters Complete list of fields, the form contains, expect from checkboxes, as they are not sent by the browser, if they are not checked.
Additional values none.
Example of usage ValIsInPost.fields = "subject", "message", "email", "name", "phone", "fax", "An error occured, please try again later."

Back to start

Appendix C - Alias feature

Lexasoft formmailer provides a special feature which enables You to set up different variants of a special value. For example You could define that posted value "support" can be translated to a valid email adress (support@lexasoft.de) and (the same time!) to a phrase like "support team" which could be displayed to the user.

This feature is called alias. It was developed to hide email adresses from the client in case the user has to decide, which department he would like to contact. In that case the email adress, the form is to send to, is unknown at time of development. Therefore it has to be posted. But if that, the email adress must be present in users browser, what often is not wanted due to spiders, which could use it for spaming.

Lexasoft formmailer gives You a simple tool for that. Here You will see, how it should be used:

Every alias can be defined in Your configuration file. The lines look as follows:

Alias.<FieldName>.<Variant>.<Value> = <VariantValue>

The parts have this meaning:

Alias Defines this line being alias definition. (Every alias line has to start like this)
FieldName Name of the field, this entry is valid for.
Variant Name of the variant.
Value Posted value
VariantValue Value in this variant

Here is an example:

  1. Create a DropDown field in Your form i.e. like this:

    <select size="1" name="recipient">
    <option selected value=    "no">-- please choose --</option>
    <option value=    "service">service</option>
    <option value=    "sales">sales</option>
    <option value=    "finance">finance</option>
    <option value=    "support">support</option>
    <option value=    "webmaster">webmaster</option>
    <option value=    "other">other</option>
    </select>
     
  2. Write down the follwing lines in Your configuration file:

    Alias.recipient.email.support = support@lexasoft.de
    Alias.recipient.view.support = support - team
    #... all other fields similiar to this

    In this example the value "support" in posted field "recipient" will be translated to the email - variant "support@lexasoft.de" and to the view (display) variant "support - team".
     
  3. Access those values in Your template files by quoting <FieldName>.<Variant> by %.
    For example write:
    ...
    <td    >%recipient.view%</td>
    ...
    in Your Response template to show the View Variant of the posted value. In our sample this will produce a table cell with the content

    support - team

    if "support" had been posted by the user.

  4. Acces them in Your cfg file the same way, by writing:

    MailRecipients = %recipient.email%

    In our sample with this the form will be sent to support@lexasoft.de, if "support" had been posted by the user.

Please note: See the advanced sample for a complete application with that feature.

Back to start

Appendix D - Default value feature

This feature of lexasoft formmailer is particularly designed for the use of checkboxes. In html they behave in a way, that name and value of the checkbox only are transmitted, if the checkbox is checked.

If the checkbox is unchecked, nothing is transmitted at all, not even the name without a value. This might cause some problems in reacting on an unchecked checkbox.

With the default value feature You can specify a value, which is used by the formmailer if a value is not transmitted by the form, just as it is with checkboxes.

Please note: This value will be used, if it is not transmitted, only. If it is, even with an empty value (""), the transmitted value will be used. That's why You can't use this with textfields as they are always transmitted no matter filled in or not.

Every default value can be defined in Your configuration file. The lines look as follows:

Default.<FieldName> = <DefaultValue>

The parts have this meaning:

Default Defines this line being default definition. (Every default line has to start like this)
FieldName Name of the field, this entry is valid for.
DefaultValue Value to be used default.

Here is an example:

  1. Create a checkbox in Your form, i.e. like this:
    ...
    <input type=    "checkbox" name="newsletter" value="yes">
    ...
  2. Write down the follwing line in Your configuration file:

    Default.newsletter = no
  3. Access those values anywhere in Your configuration files and in Your templates simply by writing %newsletter%.

In this example value "yes" will be used, if the newsletter checkbox is checked and "no" if it is unchecked.

Please note: See the advanced sample for a complete application with that feature.

Back to start

Appendix E - Reserved substitutes

Substitutes are values, You do not know while designing Your form, as they will be defined at runtime, only. For example, all posted fields, configuration values in formmailer.cfg or information given in language files, can be accessed via substitutes. Simply write %SubstituteValue% in any template or configuration file.

But there are a number of reserved substitutes, that are provided by the system. You can find them in the following table:

substitute

meaning
script

How to reach our own script. Used to define the action of the post request in form.
Example of usage:

<form method="POST" action="%script%">

backlink

How to go back to form after posting. Used in ResponseTemplate.
Example of usage:

<a href="%backlink%"><font size="2">Back to the form</font></a>

date Today's date in pattern You provide in Your language file. Default pattern: "m/d/Y"
time Time now in pattern, You provide in Your language file, Default pattern: "H:i:s"
ip Ip address of the user.

 

Appendix F - Upload Feature Details

In addition to general substitutes, upload feature makes use of several substitutes with a special meaning. As usual, all of them can be used in templates simply by writing them included in %%. In this appendix there is an overview:

substitute

meaning
1. Information generated by the script to be displayed in templates and messages.
%UploadMaxFileSize% Contains the maximum size of files to upload as configured in formmailer.cfg.
%UploadUserFilename% The original name of the file, as sent by the user.
%UploadUserMimeType% The mime type of the file, currently uploaded.
2.Error messages generated by the upload module. Must be translated in lang.XXX.cfg (where XXX is the language to use).
%MsgUploadFileExists% Error message, that file to upload does exist already. Should not appear, as the formmailer always tries to find unique name for every file.
%MsgUploadMissingFile% No file to upload is given.
%MsgUploadFileTooBig% File to upload is larger than maximum file size.
%MsgUploadWrongMimeType% Mime type of the file is not allowed to be uploaded.
%MsgUploadCopyError% Uploaded file could not be copied to the specified directory. Reason may be that this directory does not exist or insufficient rights are granted.

The upload sample is fully qualified with all substitutes above used and defined. Please check this for more details.

Back to start

Appendix G - Changes

Changes taken place
v1.5.6
  • Support for PHP5 added. Should be working with PHP 5.2.1 and above.
  • IP Adress of sender accessible in templates.
  • ValIsInPost feature added.
  • Cc and bcc header for response mail added.
v1.5.5
  • Upload feature added.
v1.5.1_02
  • Environment bug patched: In some server installations reading of environment variables failed. Sending formular was not possible (empty input page appeared again).
v1.5.1
  • No need to set register_globals to on in php.ini for PHP 4.2 and above, anymore.
  • Default value feature added.
  • A version signature as html comment is included in formmailer output.
  • X-Mailer header is included in every email sent.
  • A small number of mistakes had been removed from descriptions in readme.htm and formmailer.cfg.

 

Back to start