form Help Page and Documentation

Find answers to your questions about form installation, configuration, languages, and more.
Here you'll find answers to your questions about your form's configuration, validation, installation, languages, and form testing. If you need more help, please contact Mike Cherim for assistance. (Note: Some support is fee-based.) You may remove this file after installation.


Form Version: v3 - Build Number: B3.20090130.01 - Model Number: SASU - Blocked: 352 - More Help »


Page Information

Donate

On this page you will find helpful answers, about script installation, configuration, and language management. Also get answers to your frequently asked questions. If you find yourself in need of more help, you can check out the demo site help page. You can also contact Mike Cherim if all else fails. You may also post a comment on Mike's Beast-Blog web log.


Script Installation

This section will help guide you through the simple installation process. Please note that some configuration is required.

  1. Unzip and check out the readme file. It is these instructions, repeated. Open the form and files folders to locate the CONFIG.php file.
  2. Open that file using a text editor like Notepad, Textpad, or a markup editor that won't mess up the scripting. Don't use Word, and Dreamweaver can be dangerous. Some FTP programs can work well, and you may be able to edit the file from within your server admin.
  3. Enter the first two variables, $send_email and $reply_email, as a minimum. The next two, $addressee and $web_site are a good idea as well. There are many other variables, like language, if needed, display options, and more, but they can wait until the script validation is done.
  4. Once that is done, put the entire form folder on your server on the root, within a directory, or within a sub-directory. Do not rename anything! (Unless you first check out the FAQs to learn how.)
  5. A 1 byte error-log.txt file is located in the files sub-directory located in form. Find it and make it writable. CHMOD 666 if needed. This is an essential step and you will not be able to proceed until done.
  6. You're about done. Go to the validation page with your browser and look for the green validation bar with form ID. From there you can check on the script's variables, locate available languages, etc. You may also move the validation file to validate and test in the same directory your contact page will be in.
  7. Assuming you're a go, load up the form testing page and give it a whirl. You may also move this page, as you can with the validation page, to perform a test of the form in the same directory your contact page will be in. This is an option. If the validation page is good, the form should be too!
  8. If it works, and it should, you can work on using the CONFIG.php to customize and further configure. You will also want to edit the style sheet if changes are desired (it can be found in the themes sub-directory).
  9. Add the link to the style sheet and the focus JavaScript file - for form field focus effects for Internet Explorer - to the head of your contact form page (see Figure 1), then add the PHP "include" to the body content area of that same page (see Figure 2). Go live and worry not.
    <!--Figure 1 (written as xhtml)-->
     <link rel="stylesheet" type="text/css" href="form/files/themes/default.css" media="screen" />
     <!--[if IE]><script type="text/javascript" src="form/files/focus.js"></script><![endif]-->
    

    Figure 1 Note: You may choose to add the form styles to your own style sheet or do something else such as use existing styles. It's your call. Use the default style sheet to see what classes you have available to you. The style sheet name in the example is default.css, but change as needed.

    <!--Figure 2-->
     <?php include_once("form/form.php"); ?>
    

    Figure 2 Note: In all cases above, adjust the path to the files to meet your needs such as if your contact page is in a folder: ../form/form.php.

Getting Errors

If you make a mistake during the installation process, you may see an error bar with an error written in it. Environmental, configuration, and installation errors will be shown in English. Form errors are written in your selected language. If you see it on the form page the form will not be operable. If seen on the validation page, the page will be cut off (validly) after the error. If you see an error on this page you have some serious installation issues. The bar looks like this. (Strong text was used by default because strong text, by way of the strong tag, is important.)

Example Error: This is an example of a contact form error message. Jump to Error

If you run into problems, check out the FAQs below.


Script Configuration

This section will help guide you through the simple configuration process. Don't worry, it's pretty easy, especially considering the form's flexibility. Using this contact form there are two files you can edit. The CONFIG.php file and the language file. Here the CONFIG.php will be covered, groups of variables/arrays listed and briefly explained. As noted in the installation instructions, edit this file with a safe markup editor or a text editor like Notepad. Be sure to read the instruction header in the file itself for further details. To get a quick peek at these values as they are configured here, check out the validation page.

Required set-up to operate form
  • $send_email = Enter the email address you want the form to send to. You can add more than one, just separate them with a comma.
  • $reply_email = Enter the email address you want the user to see and reply to if they reply to their copy of the email. Choosing a noreply account name or something similar is recommended for maximum email privacy.
Basic form set-up options
  • $addressee = What you want the email to use to address you by. This is only displayed in the primary email.
  • $web_site = Enter the name of your company, organization, or web site. In my case, I would enter "Green-Beast.com" in mine. This will show on the subject line, in brackets, and has other uses.
Subject line menu options array
  • $subjects = This array offers various subject lines or contact reasons to your users. These quoted variables terminate with a comma and following the pattern add as many or as few as you need (minimum is one). A few are offered by default. Write in your language.
Optional menu options array
  • $options = This array offers various options for an optional menu. It's enabled by default (you can disable it), and used to offer visitors a means of stating how they were referred. These quoted variables terminate with a comma and following the pattern add as many or as few as you need (minimum is one if enabled). A few are offered by default. Write yours in your language of choice.
Anti-spam question and answer
  • $spam_question = Use this to verify the person submitting the form is, well, a real person. Ask a question that has only one possible and logical answer. This is not a time to get tricky and doing so does not make this trap more effective. If you have international users, you may want to offer an arithmetic-based question like 1+1= or something along those lines. Change this pair from time to time.
  • $spam_answer = This is the answer to the question above. This is not case sensitive. If the user cannot figure out the answer or get the answer wrong, they will be presented with the solution so they can try again. This is a better solution than that used on version 2 of this form.
User blacklist IP array
  • $blacklist = Got people problems? Adding their IP address (found in the primary email's footer) to this array might solve the issue. Use this with caution though as you don't want to block the innocent. Also note that this is not effective if the user has a variable IP address or visits you from another location. It can help, though, and is one more tool at your disposal. These quoted variables terminate with a comma and following the pattern add as many or as few as you need. Do keep at least one default entry if not blocking anyone, the array must not be empty.
Display options
  • $show_privacy = This will display a small privacy link (which can be reworded in your language file) on the footer of your form. If you have a policy, this is recommended since you will be collecting some non-identifying user data and accepting user-supplied information by using this form.
  • $privacy_url = If you enter yes to $show_privacy, this is where the link will point. Use a relative URL like this: /pages/privacy.php; or an absolute URL like this: http://www.yourdomain.com/pages/privacy.php.
  • $show_stats = This will display the blocked stats (which can be reworded in your language file) on the footer of your form.
  • $show_author = This will display a small link to Mike Cherim (which can be reworded in part in your language file) on the footer of your form. This is not required, entering no will remove it altogether, but it is damn well appreciated if you decide to keep it.
  • $add_breaks = Some people like inserting breaks into a form to neaten it up. This is a justifiable use of the element. But they are not for everyone. Purists like to using CSS only to drop inputs on a new line using display:block applied to the label element (but it looks like hell with styles off). Thus, you now have a choice without editing the form.
  • $show_main_legend = This will display for form's main legend (form heading) as the name implies. This does not remove the legend, just hides it off screen for accessibility. If you don't display the legend, the fieldset border will automatically go away (and can be removed separately as well). Edit the text in your selected language file.
  • $show_sub_legends = This will remove all the sub legends, removing the border and sliding them off screen just like the main legend above. Doing this, however, will automatically add an alternate required field method using an asterisk or your symbol of choice (editable in your language file) and text indicating the symbol's meaning to retain the form's accessibility and usability. Edit the text in your selected language file.
  • $show_main_border = If you keep the main legend you can still get rid of the fieldset border here. This can be done in the style sheet with ease, but version 2 users asked about this a lot so this was needed.
  • $show_req_borders = Add/remove sub fieldset borders on required fieldsets only. If no optional fields are used, the required fieldset will co-join into a single fieldset to retain markup quality.
  • $show_opt_borders = Same as above, but this affects the optional fields fieldset border only. If no optional fields are offered, this fieldset won't exist. The script is smart about things like that.
  • $show_addy2_label = If you're offering the Address inputs on your form, there is an Address 2 field whose label is hidden by default. Use this to display it. This single variable initiates many automatic changes in the script.
  • $offer_cc_opt = Offering this option affords form users the opportunity to get a specialized copy of the email sent to the address they provided. Their email copy does not contain the all collected data: IP, ISP, UserAgent, referrer, and whois link; only the time stamp. You will be notified if they requested a copy so you'll be in the know. Edit the time stamp text and more in your selected language file.
  • $added_req = This little variable makes many changes adding an asterisk (or symbol you specify in the language file) next to the labels of all required fields. They will be displayed bold, and in your chosen error label color. Doing this will also append your form's main label with the symbol and text denoting its meaning. Being within a label this will remain accessible to screen reader users in "forms mode." Edit the text in your selected language file.
  • $err_border_color = Enter a hex code or color name (#bb0000, red, etc.). Certain errors will apply this color to affected input borders. This could have been done in the style sheet, but this is a feature enhancing usability so it was better incorporating it.
  • $err_label_color = Enter a hex code or color name (#bb0000, red, etc.). Certain errors will apply this color to affected input labels. This could have been done in the style sheet, but this is a feature enhancing usability so it was better incorporating it.
Form input options
  • $get_org = This places an optional input on your form asking for company/organization. Based on the label text entered, you could use this input for something else without editing the script. Edit the text in your selected language file.
  • $get_phone = This places an optional input on your form asking for phone. Based on the label text entered, you could use this input for something else without editing the script. Edit the text in your selected language file.
  • $get_website = This places an optional input on your form asking for a web site URL. Because of the http:// in the input, it can't really be used for anything else. Still, though, you may edit the text in your selected language file.
  • $get_address = This places several inputs on your form asking for an address. The inputs added include (shown in en): Address 1, Address (continued), City/town, State/province, Zip/postal code, and Country. Because of the sole purpose of this selection, these inputs can't really be used for anything else. You may, however, edit the text in your selected language file.
  • $get_optmenu = This places an optional select menu on your form. It's enabled by default (you can disable it), and used to offer visitors a means of stating how they were referred, as one example. You can use it for whatever. Edit the text in your selected language file, but the options are written in the "Optional menu options array" ($options =) mentioned above.
Mail and form settings
  • $language = This is an extremely important variable. It critically controls all of the text on your form, in the errors, associated text, some attributes, and the wording and the header in your emails. The form will not work without it. The proper language abbreviations are in fact the name of the language files so be sure to use a language that is actually available. The language files, ru, es, en-gb, be, de, ca, da, nl, sv, sk, el, he, zh-tw, ja, pl, lv, fr, cy, zh-cn, gl, no, ro, it, tr, pt, id, en, pt-br, fi, en-us, es-sp, my, are currently available. In use now is en.
  • $char_set = This sets the character set in your email to allow support for certain characters used in some written languages. By default it is utf-8. It is well supported and nearly universal, but you may change it if your needs dictate. Learn more about character sets.
  • $xhtml_or_html = Enter the markup language you need. You are limited to these two choices, XHTML or HTML. If you don't know what you use on your site, ask a web developer. It'll take two seconds to tell. It's XHTML by default because it has become so common on new sites.
  • $time_offset = This edits the time stamp which can be useful since you want your form to submit in your local time, but your server may be located in another time zone. This info can be seen on your validation page. Edit by adding +1, +3, -2, or -4, etc., as needed.
  • $internationalize = This changes the time stamp to be more internationally readable. It changes the date format to YYYY.MM.DD (instead of M, Dxx, Y) and the time to 24-hour time (a.k.a. European, military, and nautical time).
Advanced settings
  • $thankyou_page = This is no by default but if set to yes it allows the form admin to specify a separate thank you page that the form user will be sent to upon a successful submission.
  • $thankyou_url = If you have the $thankyou_page variable above set to yes, enter the URL of the thank you page here. Use a relative URL only (not http://yourdoman.com, just /thankyou.php, for example).
  • $add_antiflood = This is no by default but if set to yes it turns on an anti-flood feature reseting the form for users automatically (how fast this happens is editable, see next) to prevent them from refreshing the page thus resubmitting the email. This isn't a widespread problem, but it can happen. It will happen now and then if someone misses the Reset link, but if it happens a lot, or a person is proving difficult, this is available to you.
  • $flood_level = If you have the $add_antiflood variable above set to yes, this can be used to control its aggression. By default it is set to 2 seconds, which is a fairly aggressive setting slow enough for the user to see they submitted successfully but fast enough that refreshing by mouse is difficult. Setting it to 0 would be very aggressive and is best avoided unless absolutely necessary so user can see they sent the mail.
  • $neg_f_param = Yes by default sets proper return path (needed for AOL) but some hosts, i.e., Network Solutions, will not send mail this way so may be set to no.
  • $smtp_sneak = This changes the send From address to your send To address. This will allow the emails to be delivered on some restricted systems by sort of bypassing SMTP authentication. If using this, the Reply-to email address will still be that of your sender so you can use your email client as you would expect - it just won't look right. If your form sends but your server won't deliver the emails, try this first.
  • $ini_set = On occasion your web host will enable the PHP mail() function, but not allow SMTP on your server. This turns it on. If your form sends but your server won't deliver the emails, try this next. If you set this to yes, you may have to edit the next four variables. Contact your web host if you need help.
  • $smtp = This is essentially your mail server. It is localhost by default and this is usually fine. Contact your web host if you need help.
  • $smtp_port = The default port 25 is typical. Contact your web host if you need help.
  • $smtp_password = This may or may not be needed, contact your host for specifics.
  • $smtp_username = This may or may not be needed, contact your host for specifics.
  • $sendmail_from = This will usually be the same as the $send_email, but you do have an opportunity to change it here.
  • $sendmail_path = The name says it all. The default /usr/sbin/sendmail -t -i is typical but contact your web host if you need help.
  • $form_action = If you need to edit your form action (needed on some sites depending upon configuration), you'll use this instead of digging in the code. Leaving it empty will work in most cases as the script does use various methods of populating your form's action attribute. Please be aware that this variable is used in other places in the script, not just the action. It also controls form reset.
  • $form_lockdown = Want to close down your form for a while, or need to do maintenance? Need to do a restyling? Entering yes here will make it all possible, but do see the next variable.
  • $allow_ip = If your form is locked down to your visitors but you need to access it yourself for maintenance or a re-styling, if you have a static IP address enter it here and you'll be able to see and use the form while others will not. This currently only supports one allowed IP.
  • $name_len =, $email_len =, $org_len =, $phone_len =, $addy1_len =, $addy2_len =, $city_len =, $state_len =, $postcode_len =, $country_len =, $web_len =, and $spam_len = All control the number of characters allowed in your form's inputs by setting the maxlength input attribute. The script enforces this number for security but this is an error people will very rarely see.
Personal ID key
  • $pid_key = This is a random number/letter combo you can add to your config to ensure your form's ID number is 100% unique, helpful if offering more than one form on your site. Before being used, the script applies the md5() hash function to this number.

Language Management

One of this form's strong features is its support for other languages. Any left-to-right language can be supported. Support for right-to-left languages is unknown at this time. This script uses language files to handle all of the visitor-accessible text used in association with the form, including its errors, the email texts, and more. Any and all is easily editable.

The language files, ru, es, en-gb, be, de, ca, da, nl, sv, sk, el, he, zh-tw, ja, pl, lv, fr, cy, zh-cn, gl, no, ro, it, tr, pt, id, en, pt-br, fi, en-us, es-sp, my, are currently available. In use now is the en file. More will become available as they are made by contributors. In most cases you shouldn't need to edit your selected file, but you can if you want. To learn more, study the current en language file, compare it to the form itself, and also see the language information presented on the validation page.

Editing Language Files

If you want to edit the language file, do it with care and make note that some text snippets are used in conjunction with others or with variables. Great care was taken, however, to not force a particular language syntax so as to retain the form's international usability and appeal.


Frequently Asked Questions - FAQs

This section contains some answers to frequently asked questions that you may have as well. If you have a question not answered here, when form testing, also use it to ask Mike for help.

My form sends, or it says so, anyway, but I don't get the emails. Why?
If the success message comes up, the form has done its job. The PHP mail() function is enabled - the script checks for that. It's now up to everything up- and down-stream, beginning with your mail server... your host offers one, right? Do check your spam filter if you have one, and give it a while. Mike's server sends quickly, but not all do. No luck? Okay, go to the Advanced Settings variables in the CONFIG.php file. Look for the $neg_f_param first and set it to "no" then test. No good? Next look for the $smtp_sneak and set it to "yes" then test the form again. Still nothing, huh? Okay, reset the other variables then and move on to the next five variables. The first, $set_ini is like a switch, set it to "yes". The four remaining are controls, so to speak. The next in line, $smtp, where you'll enter your domain email, will probably be the only one you'll need to edit so save the changes go ahead and test the form again. If you need help with these steps, or if it still doesn't work, you will need to contact your web host.
I'm getting errors about certain files not being found. What's up?
You must install the entire form folder, without renaming anything. This should be done on the root- or index-level, a directory, or sub-directory. The folders must be readable (CHMOD 755 - this is a typical default), and the PHP include() and require() functions, and variants, must be supported.
I bring up the index.php in my browser and it says access is prohibited?
You're not instructed to bring up the index. That is how it works, and it is there for your directory privacy. To use the form you must include form.php into your web page. Please re-read the installation instructions or readme file.
I'm getting errors about the error-log.txt file. What's up?
The file must be in the files folder, writable (CHMOD 666), it must contain at least 1 byte of data (the number 0, zero, for starters), and must not contain more than 10 bytes (for security - its file size should never exceed 8 bytes). If all of that is a good to go... hmm.
Say what? How do I do this CHMOD 666 thing?
If you load up the validation page and get the green bar, then your server makes files writable by default, you won't get the error addressing that. If you do get the File Not Writable error, then by way of FTP or by way of your server admin panel, set the file's permissions (also known as CHMOD which short for CHange MODe), to 666. This is the same as saying the file is Readable and Writable, but not Executable, to the Owner, Group, and to Everyone (Public). Next to files in some environments you will see code like -rw--rw--rw- which actually means the file is CHMOD'd to 666 and is writable. To edit this in your server or FTP, try accessing the file's Properties. Ask your host if you still need help with it. Also, here's a source of some additional info.
I edited my config file, but my form now comes up blank. What happened?
You either added a quote mark to one of the variables, you removed one or both of the two quote marks, or you accidentally removed the semi-colon at the end of a string (or comma if it's an array you edited). You will now have to go back into that file and look carefully at each line. Alternatively you may also locate your server's error log, clear it, reload the page going blank, then check the log. It may reveal a line number. Need help with your server's error log, ask your web host.
The include doesn't work on my *.html page. Why?
To process PHP scripting, you must apply the include on a *.php page, or contact your web host and request server configuration to run PHP on any page or file. If you choose the former method and change your file extension to *.php, don't forget to update your navigation.
I uploaded the files and followed the instructions, but the files are messed up... why?
As noted in the instructions, always use a plain text editor like NotePad to edit the files. FrontPage and others can destroy the PHP files. Also, based on this comment from Gill Lucraft, uploading via FTP with support FrontPage Server Extensions (FPSE) can also wreak havoc on the files. This can turned off for a minute or upload can be done through the server. Even good FTP programs like Filezilla and CuteFTP can fall victim to FPSE.
If I can't rename the form folder, how can I install more than one copy on my site?
Well, you can rename it, but you must make a couple small changes. Using a plain text editor just like you used to edit the CONFIG.php file, open the following files and near the very top of each you'll find a special configuration allowing you to rename the folder: help.php, validation.php, test-form.php, form.php, and functions.php. The variable you will have to change by entering the new folder name is $set_directory. You will also need to do this on two more lines in the functions.php file, identified at the top of that file.
I am getting a warning when I activate anti-flood or custom thank you page feature, or neither works. How come?
The "headers already output" warning will show up on some sites depending on how they are scripted. This is currently an open issue in need of resolution. Any fix ideas? Step forward.
My language file is messed up. How can I fix it?
Open it with a text editor and fix them, save as UTF-8 or whatever works for you. Or use character entities if all else fails.
How do I "test" the other themes?
You'd have to edit the test-form.php file to call for something other than the default style sheet. For testing, though, the easier option is to just rename the style sheet you want to test to default.css.
I deleted the en language file and now the form will not display my language. How come?
Even blank, that file must exist. The script looks for that particluar file in order to verify the path to the langs sub-directory.
I want to show the form stats elsewhere on my site... how?
Easy one, just apply the following readfile() function to the location you want (see Figure 3). Just make sure the file path is right for your installation.
<!--Figure 3-->
 <?php readfile("form/files/error-log.txt"); ?>
Can I distribute this form on my site?
No. This form can only be distributed by its maker. You can, however, contribute to the form by way of creating themes or official language files. Your contributions will be properly acknowledged.
I want to make or have made edits to the script. Can I still get support?
No. The only files that should be edited are the CONFIG.php file and whatever language file you select. If you made or want to make edits to any of the other files you're on your own unless working as an authorized contributor.
When a visitor submits the form, what "other" data is collected?
Nothing really personally identifying. To better exemplify, below is an example of the webmaster's primary email footer (see Figure 4).
Can I see the webmaster's copy of the email, before I download it?
Sure thing. See Figure 4, below. Do note, however, that only the fields containing data will be displayed. For example, if you keep the "Website" input enabled, but the form user leaves it empty (or with the default http://), it will not be displayed in the email at all.
<!--Figure 4-->

 Hello Mike,

 An email has been sent from Joe Foo. Here's the message:

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
 Phasellus non dolor at purus lacinia lobortis. In hac habitasse
 platea dictumst. Quisque orci metus, dignissim vel, egestas 
 bibendum, elementum et, augue. Cras ac velit. Integer semper ipsum.


 This additional information was provided:

    Name: Joe Foo
    Email: joe@foo.com 
    Organization: The Foo Group, Ltd.
    Phone: 800-FOO-RULES
    Address: Foo Technology Park
    Address (continued): 1 Foo Circle
    City/town: Fooville
    State/province: Foo
    Zip/postal code: 01234
    Country: USA
    Website: http://www.foo.com
    Referred by: A print advertisement

 Data Collected:

    Time stamp: Dec. 28th, 2007 @ 10:45 pm
    IP: 00.00.00.00
    UA: Firefox on Windows
    ISP: c-00.00.00.00.hsd1.xx.comcast.net
    Ref: http://green-beast.com/form/test-form.php
    Whois: http://ws.arin.net/cgi-bin/whois.pl?queryinput=00.00.00.00

Can I pay to have my form installed/styled/modified?
Sometimes installation help is available, if there's some spare time. Contact Mike by using the form testing page.
Is this version going to be converted into a WordPress plugin like version 2?
Yes, that's the plan. Some v3 road-time has to first pass to ensure any bugs are ironed out, then a conversion can take place.

Copyright © 2007-2017 Mike Cherim. Some rights reserved. [ Top ]