here."/> Bob's Guides | SPForm Snippet here."/>

SPForm Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

For basic SPForm troubleshooting, see the SPForm FAQ page.

SPForm is a really simple e-mail contact form that is as spam-proof as I could make it. It creates a contact form like the one here. This tutorial will walk you through the steps necessary to install and configure SPForm on your MODx site.

SPForm has a number of useful features including:

  • No e-mail addresses on the screen or in the page source
  • Multiple, configurable, spam-proofing options
  • Full documentation on all options
  • Easily editable drop-down list of recipients
  • Relatively easy to install and configure
  • Easily ban individual spammers, domain names, or IP addresses
  • Send mail with phpMailer using mail() or authenticated SMTP
  • Multi-language support

SPForm's options are set in the configuration file: spfconfig.cfg.php. Here's a partial list of the options:

  • Require keyboard and/or mouse activity
  • Time users and set minimum and maximum times allowed to submit the form
  • Present CAPTCHA-style image verification (requires the Captcha plugin in MODx Revolution)
  • Present a simple random math problem as an image and ask the user to solve it
  • Use an invisible (but not hidden) field that autobots will get caught filling
  • Require name, subject, e-mail with JS validation
  • Set maximum length of subject and recipient
  • Add subject prefix to message subject field
  • cc all messages to a specified address (in addition to recipient)
  • Set maximum number of http links in message
  • Restrict the use of the form to certain domains
  • Report remote host, user, address, identity, and referrer in msg headers
  • Disallow blank referrer
  • Reject messages with fake referrer set to self
  • Require messages to be sent from one's own server

 

Installing SPForm for MODx Revolution 2.0.0 and Beyond

This couldn't be much easier. Just go to System | Package Management on the main menu in the MODx Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Find the SPForm snippet and put a check next to it (it should be under "Communication"). Check any other packages you might want to install and click on "Finish." That should bring you back to your Package Management grid. Right click on SPForm and select "Install Package." You'll be asked for a return email address and can specify whether you want the sample contact form installed (highly recommended). When the install completes, you'll have a working, relatively spam-proof contact form on your site.

You can skip all the way down to the section on Configuring SPForm in MODx Revolution.

 

Installing SPForm for MODx Evolution and Earlier

The first step is to go here to download the current version of SPForm.zip (1.0.5) to your computer.

Next, extract the contents of the SPForm zip file to your assets/snippets directory. The files should end up in a directory called /assets/snippets/spform.

Make sure all the files are there. You should see this structure:

  • lang (folder)
    • en.inc.php
    • phpmailer.lang-en.php
  • noises (folder)
    • noise1.jpg
    • noise2.jpg
    • noise3.jpg
    • noise4.jpg
  • ttf (folder)
    • arial.ttf
    • ftb_____.ttf
    • pala.ttf
    • tahoma.ttf
    • verdana.ttf
  • index.html
  • spform.inc.php
  • spformproc.inc.php
  • spfresponse.inc.php
  • spfconfig.cfg.php
  • spfdebug.php
  • contacts.cfg.php
  • banlist.cfg.php
  • spfveriword.php
  • spfvericlass.inc.php
  • mathstringclass.inc.php
  • mouseMovement.js
  • usedKeyboard.js

 

Creating the Three SPForm Resources

SPForm requires three MODx documents to do its work: one to show the contact form, a second one to process the contact form, and a third to display the "thank you" page. Remember that snippet names and file names are case-sensitive so be very careful to use the exact case in all the examples below. If your contact form doesn't display or if you don't end up with a display of the "Thank You" page after submitting it, there's a good chance that you misspelled one of the names.

Since SPForm finds the three documents by ID number, you can change their names, although it's recommended that you get SPForm working before doing so.

Creating the Contact Page Document

Launch the MODx Manager, (log on with https://yoursite.com/manager).

Select the Site tab near the top of the page and click on New Document.

Fill in the fields on the document editing screen as follows (your "Uses template" field will be different):

spform-image1

The Menu index number tells MODx where to show this document in the menu. If you'd like your contact form to be at the end of your menu, for example, you can put 99 in the Menu index box. If you're not sure, don't worry, you can come back to this page and change it later.

Look at the top of the Create/edit document window (scroll up if you have to). You should see three tabs like the ones below:

ezfaqtutorial-image2

Click on the Page Settings tab. This tab allows you to set some of the characteristics of the document we're creating.

The Published checkbox determines whether visitors to your site will see the document or not. You might want to leave it unchecked until you're done creating the SPForm pages. If you leave it unchecked, you'll have to come back here and check it to make the page visible to visitors. If you don't care if people see the unfinished page, you can check it now.

Notice also, the Published date and Unpublished date boxes. If you'd like to have a page appear and/or disappear from the site, you can put dates in these boxes by clicking on the little calendar icon next to each box. You can try these now if you like. You can remove the date by clicking on the other calendar icon (the one with the red circle and slash over it).

Make sure the Show in menu checkbox is checked.

Next, scroll down to the Document content window and paste in the following line:

[!SPForm!]

Note: For MODx 0.9.7, use the following instead: [[!SPForm]]

Now, scroll up to the top of the page and click on Save.

Creating the Form Processing Document

As you did above, create a new document by selecting Create New Document. Fill in the fields on the document editing screen as follows:

spform-image1

Make sure the "Show in menu check box is UNchecked. Make sure the "Published" checkbox on the Page settings tab is checked.

Next, scroll down to the Document content window and paste in the following line:

[!SPFormProc!]

Note: For MODx Revolution, use the following instead: [[!SPFormProc]]

Now, scroll up to the top of the page and click on Save. Make a note of the document ID after you save the document (it's in parentheses next to the document title in the Resource tree at the left side of the screen). We'll need it later.

Creating the "Thank You" Page Document

As you did above, create a new document by selecting Create New Document. Fill in the fields on the document editing screen as follows:

spform-image1

Make sure the "Show in menu check box is UNchecked. Make sure the "Published" checkbox on the Page settings tab is checked.

Next, scroll down to the Document content window and paste in the following line:

[!SPFResponse!]

Note: For MODx Revolution, use the following instead: [[!SPFResponse]]

Now, scroll up to the top of the page and click on Save. Make a note of the document ID after you save the document (it's in parentheses next to the document title in the Resource tree at the left side of the screen). We'll need it later.

 

Creating the Three Snippets

If we looked at our contact page now, there would be nothing there because we haven't created the snippets called on the three pages yet.

Creating the SPForm Snippet

In the MODx Manager click on Resources at the top of the screen and select Manage Resources. On the right side of the screen, click on Snippets.

Click on New Snippet. Fill in the fields as shown below:

spform-image1

Since you can't paste the code from the image, here is the line that goes in the php section:

require_once $modx->config['base_path']."assets/snippets/spform/spform.inc.php";

Now, let's give our snippet a category so it will be easier to find among all the other MODx snippets. Click on the Properties tab. Don't worry, your code is still there on the General tab. In the New Category: field, type: SPForm Snippets.

spform-image1

Now click on Save. You should see your new snippet under the new category in the list.

Creating the SPFormProc Snippet

Click on New Snippet again. Fill in the fields as shown below:

spform-image1

Since you can't paste the code from the image, here is the line that goes in the php section:

require_once $modx->config['base_path']."assets/snippets/spform/spformproc.inc.php";

Click on the Properties tab and select SPForm Snippets from the Existing Category drop-down list. Now click on Save. You should see this second snippet under that category in the list.

Creating the SPFResponse Snippet

Click on New Snippet again. Fill in the fields as shown below:

spform-image1

Since you can't paste the code from the image, here is the line that goes in the php section:

require_once $modx->config['base_path']."assets/snippets/spform/spfresponse.inc.php";

Click on the Properties tab and select SPForm Snippets from the drop-down list. Now click on Save. You should see this third snippet under that category in the list.

 

Configuring SPForm

If you look at your site now, you should see your contact form but it won't list your desired recipients or send any e-mail because we haven't configured it yet.

There are two files that need to be edited to make SPForm work. The first is the file contacts.cfg.php, the second is the file spfconfig.cfg.php.

Editing contact.cfg.php

This file is the easiest, so let's do it first. It sets the recipient(s) that will receive e-mail from the form. The file is in the assets/snippets/spform directory and, if you're doing this on your local machine, you can edit it with any text editor. If you're site is on a remote server, you can either edit the file locally and FTP it to the remote site or use the MODx file editor.

To use the MODx file editor, click on the Resources tab at the top of the screen, then click on Manage Files. You should see a directory list with the assets folder at the top. If not, you may need to go to Tools | Configuration | File Manager and correct the File Manager Path to match the actual physical path to the root of your site.

Click on assets, then on snippets, then spform. To edit the contacts file, click on the edit button (the white check mark in the green box) next to contacts.cfg.php. Note: Depending on your screen size, after clicking on the edit button, you may not see the code until you scroll down.

The lines in the file that start with a pound sign (#) are comments. You can delete them later if you'd like to gain a very slight speed increase. These three lines do the actual work:

Please choose a recipient: Please choose a recipient:
WebMaster: Webmaster: you@yourdomain.com
Sales: Sales: sales@yourdomain.com

Notice that each line has three colons (:). These separate the parts of the line. The first part (before the first colon) is for your use and will also appear in error messages. The second part is what will appear on the form. The third part is the e-mail address that the form contents will be sent to. Notice that the first line has no third part so the user can't send to that choice.

If you have only one recipient to send to, you'll have only one line here. Delete the first and third lines and edit the remaining line as appropriate.

If you have more than one recipient, the first line is optional. It prompts the user to select a recipient, but if you delete it, the first line will be the default recipient. Edit the lines to match your situation and click on Save.

If you look at your form now, you should see the recipients as you set them up but you should not see any e-mail addresses.

Editing spfconfig.cfg.php

This form sets all the various options and parameters for SPForm. Edit it the same way you edited the contacts file. The first thing to do is to set the allowed referers for your form. This helps keep spammers from using your form to send e-mail. Edit the following lines to match your environment. Be careful not to delete the single quotes or the commas:

'yoursite.com','www.yoursite.com',
	'localhost'

If you make a mistake here, you will get an error message from SPForm telling you that the form was sent from an invalid referer.

Next, change the following lines to match the document IDs of the two SPForm pages. If you forgot them, you can see the document ID numbers in parentheses next to the document names in the Resource tree at the left side of the MODx Manager.

$spformProcID = 7;  // Doc ID of spformproc page
$spfResponseID = 8; // Doc ID of spfresponse page

Finally, change the "errorsTo" address to your own e-mail address.

$errorsTo = "you@yourdomain.com";

Take a look at the options in the rest of the file. Many of the spam-proof options are turned off by default because it's best to get the form working first and then turn them on, one at a time, to make sure they don't cause any trouble. To turn on an option, you simply change false to true. but it's strongly advised that you save that for later when you've made sure that the form is sending mail.

 

Configuring SPForm in MODx Revolution

Configuring SPForm is much easier in MODx Revolution. Almost all configuration is done with the snippet properties (parameters) of the SPForm and SPFResponse snippets.

To see SPForm's options, just go to the elements section of the Manager and select the SPForm snippet. Then click on the "Properties" tab.

There are three ways to set SPForm's options in Revolution.

1. You can add parameters to the snippet call. You can use any properties you see in the snippet properties grid. Values sent as parameters will override any other settings.

Example:

    [[!SPForm? &useTimer=`0` &warnAll=`1` &spfDebug=`1`]]

This will turn off the timer and turn on all warnings and debug messages. You can override any property in the grid with a parameter in the snippet call, however, it's usually easier to create a custom property set and edit the properties (options) in the grid. See number 3 below.

2. You can edit the default properties grid. We STRONGLY recommend that you NOT do this. It is a bad practice because your values will all be overwritten when you upgrade the snippet.

3. The recommended method is to create a custom property set. Here's how:

  • In the tree, click on Elements | Snippets | SPForm snippets | SPForm.
  • Click on the properties tab.
  • On the right side, click on "Add Property Set."
  • Check the checkbox for "Create New Property Set."
  • Give the set a name (e.g. SPFormLocal) and a description.
  • Click on Save.
  • Edit any properties you want to change (the names of the changed items will appear in green after you save the set).
  • Click on "Save Property Set."
  • In the tree, click on Resources.
  • Right-click on "Contact" and select edit.
  • Change the snippet call to look like this:
    [[!SPForm@SPFormLocal]]

SPForm will then use your custom property set to override any values in the default set. You can still override any values by sending parameters in the snippet call.

Important: When changing SPForm options, be sure to select your custom property set before editing. Be careful not to edit the default property set by accident!

A few properties are attached to the SPFResponse snippet and you'll have to set those as you did for the SPForm snippet.

Hopefully, everything you need to know about the property settings is there in the snippet properties grids. Just click on the little plus sign next to a property to see an explanation of what it does.

Important Note: If you have the "log" properties on at a busy site, your error log (assets/components/spform/error.log) can get very big, very fast. You can delete it or save it empty it at any time.

 

Styling the Pages in Revolution

Almost anything you want to do in the way of styling the form and the response page can be done by editing the spformTpl and spfresponseTpl files and by changing the SPForm CSS file at assets/components/spform/css/spform.css. The error page can be styled by editing the spformprocTpl chunk and the spform.css file.

Note that the default is to have the prompts and inputs on separate lines of the form, but CSS for having then inline is already in the CSS file. Just change spf_block_prompt to spf_inline_prompt in the spformTpl chunk.

If you want to have your own CSS file (a good idea if you've made changes that you don't want overwritten when you update the snippet), just create your css file and pass the path to it as a parameter in the snippet call:

    [[!SPForm? &spfCssPath=`path_to_your_css_file`]]
    [[!SPFResponse? &spfCssPath=`path_to_your_css_file`]]

Be sure to do this for both snippet calls if you've made changes that will affect the response page. You can also add an spfCssPath property to any custom property set you've attached to the SPForm and SPFResponse snippets.

Another option is to paste the spform CSS file into your main CSS file and use &spfCssPath=`""` in the snippet calls. SPForm will then ignore its own CSS file.

 

Testing the Form

Your form should now work. If you fill out all the forms fields with appropriate values, you should be redirected to the "Thank You" page. Your form still might not send e-mail, however. By default, SPForm uses the mail() function which depends on an active mail server being up at your site. If your site is on your local machine and you have no mail server, the form will operate normally, but no e-mail will be sent. If it is on a remote server, it still may not work because some ISPs have mail() turned off for security reasons.

Wait a while for your test e-mail message to arrive. On some ISPs it can take quite a while for the mail to actually go out and it can be held up along the way. If you never get the mail, don't despair. There's another method of sending mail that should work on any server. SMTP mail is an option that can use most any mail account that you have.

In MODx Evolution, you configure it by editing the following lines of the spfconfig.cfg.php file:

 $spfUseSMTP= false; // default false -- if this is false, the next four parameters are ignored

 if ($spfUseSMTP) {
	 $spfSMTP_Port = 587; // default port for authenticated e-mail - many hosts now block port 25.
     $spfSMTP_Host = "smtp.your-isp.com";
     $spfSMTP_UserName = "your-username@your-isp.com";
     $spfSMTP_Password = "your-password";
 }

Change $spfUseSMTP= false to $spfUseSMTP= true. Then edit the host, username, and password lines to match those of your e-mail account (just as you would configure a mail client like Eudora, Pegasus, Windows Mail, etc.). Your form should now send mail.

In MODx Revolution, the best method is simply to set the SMTP system settings. Go to System | System Settings and type SMTP in the search filter box at the upper right, then click anywhere in the grid. Once the values are set properly, any MODx snippet or plugin that calls the mail() function will operate using SMTP.

 

Adding Spam-proofing Options

Once your form is working, you can try adding the various options. Requiring use of the mouse or keyboard is a good option since most spambots are automated. The timer is another option because automated spambots tend to fill out the form very quickly or very slowly.

The veriword option presents the user with a CAPTCHA-like image that must be entered. Using the mathstring option with this is even better because it will ask the user to solve a very simple math equation. Some spambots are getting good at deciphering CAPTCHA images and entering them and this will foil them completely.

Note that in order to use the veriword and mathstring options, your host must have the graphics engine turned on. If it's not on, there is no way to make the images appear. The user must also have cookies turned on. In addition, users with seriously impaired vision, especially those who use audible screen readers will be unable to use your form. Frankly, the other options combined will do a very good job of preventing spam even without the veriword and/or mathstring options.

The hidden field option is another good one. Most spambots will fill in all fields in a form and, since this one doesn't actually appear to users, no real user will fill it in. If you use this option, be sure to add the .CSS lines listed in the spfconfig.cfg.php file to your .CSS file or the field will appear to real users and many will fill it in.

Sometimes, spammers will actually visit your site and paste their spam into your form manually. This is fairly rare, but the only way to stop them is to put their IP numbers in the banlist.cfg.php file. It's located in the assets/snippets/spform directory and comments in the file will tell you what to do. The IP number is available in most mail clients when you look at the spam e-mail you receive if you click on something like "show details."

 

The Ban List

You can ban individual email addresses, domains and subdomains either by name or by IP number by editing the banlist file at assets/components/spform/banlist.inc.php.

in MODX Evolution, the files is at core/components/spform/banlist.inc.php.

There are instructions in the comments section of the file on how to do it. With all the spam-proofing options, banning is usually unnecessary but if someone is manually entering stuff in the form and annoying you, this is the way to stop them.

 

SPForm CSS

SPForm is designed to be really easy to use and install so the display is fairly simple and the styling options are somewhat limited. You can add the following to your MODx .CSS file to hide the hidden field and style the form they way it looks on this site. Feel free to modify the .CSS to make the form look the way you want it to, but don't change the .spform_input section. It makes sure the hidden field remains hidden.

.spform_input {
    position:absolute;
    text-decoration:underline;
    background-color:#CC0000;
    left:0px;
    top:-500px;
    width:1px;
    height:1px;
    overflow:hidden;
}
.spf_prompt {
    display:block;
    padding-right:10px;
    font-weight:bold;
}
.spf_normal_input {
    font-weight:normal;
    padding-left:0px;
}
.spf_verify_msg {
    font-weight:bold;
}
.spf_verify_prompt {
    font-weight:bold;
}
.spf_cookie_msg {
    font-weight:normal;
    color:#ff0000;
    padding-top:30px;
}

 

About SPForm

Adapted from: Many sources but particularly scform by James Seymour and CFFormProtect by Jake Munson

Special thanks to the following for their help and support:

  • Rene Tschannen
  • Susan Ottwell
  • Jason Coward
  • Ryan Thrash
  • Shaun McCormick

I created this snippet for people who want a really simple, easy to install, easy to use, easy to reconfigure, email contact form with the best spam protection I could manage. The MODx eForm snippet is available for use in email contact forms, but it is extremely flexible and powerful. As a result, it is somewhat daunting for some people to install and use.

If you need complex templates, multiple templates, file uploads, multi-language support, or communication between your contact form and the MODx DB, you want eForm. If you want extra fields, you can modify the SPForm snippet code, or use eForm. SPForm may have those features in the future, but it doesn't now.

SPForm is as spam proof as I could make it. It protects well against email injection attacks, flooding, and various other techniques. The email addresses of your recipients are well hidden and never appear in the source code of a page. It also has a number of options that will give even more protection against spammers such as pseudo form fields and CAPTCHA. You can also enter spammers with specific email addresses or IP numbers into the banlist file to prevent them from using your form. You can ban whole domains if you want. It also allows you to set the maximum length of the e-mail and subject fields and limit the number of URLs that can be sent in a single message. It has options to use hidden form fields, and to require keyboard or mouse action in filling the form. You can set maximum and minimum times that users can take to fill out your form. You can even ask users to solve simple math problems to prove that they are human. All the options are individually configurable, the idea being that everyone will use a different configuration and spammers will find it more work to adjust to yours than it's worth.

Please note that no contact form can prevent spammers from visiting your site and manually sending you spam through your contact form. SPForm will protect you from most autospammers and will let you limit the number of http links in each e-mail message.

SPForm has been completely refactored for MODx Revolution. It now has templates, classes, and its behavior can be controlled by setting the snippet properties (parameters).

Installation is now fully automated in MODx Revolution and SPForm should work for you with little or no configuration.

Some of the original code for SPForm comes from Scform.php, written by James Seymour. I left Jim's GPL notice in the snippet source code. I've made extensive modifications to Jim's code. Some are to make the form work as a MODx snippet. Others are based on ideas I've found in other spam-proof contact forms including Jake Munson's CFFormProtect. Some of the ideas are my own. If SPForm works for you, Jim and Jake deserve most of the credit. If it doesn't, I deserve most of the blame. Please don't contact Jim or Jake for help with the snippet. As far as I know, neither are MODx-aware and they almost certainly won't be able to help you.

Please let me know via the MODx forum if you have any problems with SPForm or suggestions for improving it or these instructions.

 

Beyond SPForm

SPForm is designed to be easy to install and configure, but it isn't very flexible. If you find that SPForm isn't meeting your needs, there is an alternative snippet for MODx Evolution called eForm that almost certainly will. eForm is more complex and time-consuming to configure than SPForm, but it is infinitely more powerful. It gives you complete control over how the form looks, allows custom fields and custom responses, and has many other options as well. With the eForm2DB snippet, it even allows you to use your form to interact with the MODx database.

For MODx Revolution, the FormIt package will create a much more customized contact form.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray