Bob's Guides

SPForm Snippet Tutorial

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-premium extras with a clear conscience.

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
• Easily editable drop-down list of recipients
• Relatively easy to install and configure
• Send mail with phpMailer using mail() or authenticated SMTP
• Multi-language support

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

See the properties tab of the SPForm snippet for a full list.

Installing SPForm for MODX Revolution 2.0.0 and Beyond

This couldn't be much easier. Just go to System (gear icon) | 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. Type SPForm in the search box and hit enter. Click on the "Download button" and wait for the download to finish. Then, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to the SPForm package. You'll be asked for a return email address you want the contact form to send to. When the install completes, you'll have a working, relatively spam-proof contact form on your site.

Testing SPForm

The pagetitle of the contact form resource is "Contact" If you preview that page, you should see your contact form, fill it in and click on the "Submit" button. It should send an email to the address you entered during the installation. If you don't get the email, it's likely that something is wrong with the email system on your site. In Package Manager, download and install the QuickEmail snippet to test the system. Create a test page with this code:

  [[!QuickEmail? &debug=1]]

By default, SPForm and QuickEmail use 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 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 mail account of yours that allows sending SMTP mail.

It's recommended that you use SMTP to send your emails. In MODX Revolution, there's no need to mess with SPForm's SMTP settings. Instead, set the MODX SMTP System Settings. Go to System (gear icon) | System Settings and type SMTP in the search filter box at the upper right and press "Enter". Once the values are set properly, any MODX snippet or plugin that calls the mail() function will operate using SMTP.

These are the ones to set (consult your hosts help pages or email support for the Host specification and SMTP port number). These settings work with Gmail:

• mail_smtp_hosts — The host SMTP specification (e.g. smtp.bobsguides.com, smtp.gmail.com)
• mail_smtp_port — Your hosts SMTP port number, 465
• mail_smtp_auth — set to Yes
• mail_smtp_prefix — ssl
• mail_smtp_user — The username for your email account, your Gmail address
• mail_smtp_pass — The password for your email account (see note below)
• mail_use_smtp — Set to Yes

For the other SMTP System Settings, the defaults should work fine.

Important Note: For Gmail, if you use two-factor authentication (and you should), Gmail now requires you to create an App password.

1. Click on "Select app" and select "mail"
2. Click on "Select device" and select "Other (custom name)"
3. Make up a name for your device
4. Click on the "Generate" button
5. Copy the generated password at the upper right
6. Paste that password into the mail_smtp_pass System Setting

If you change your Gmail password, any App passwords are revoked, and you have to recreate them.

Configuring SPForm

SPForm is quite spam-proof as installed, so if you like the content and styling of the form and "Thank You" page, you don't have to do any configuration at all.

If you do want to configure SPForm, one way is to add properties to the snippet tag on the Contact page, and the one on the "Thank You" page like this:

  [[!SPForm?
      &recipientArray=`support:support@yoursite.com,admin:adminusername@yoursite.com`
      &useTimer=`0`
      &warnAll=`1`
      &spfDebug=`1`
]]

For spam proofing, the &warnAll property should only be turned on for debugging, since it gives too much information to hackers.

The snippets on the two pages have different properties, so make sure you use the ones for the snippet tag you're altering.

You can see the properties and their descriptions by editing the SPForm snippet or the SPFResponse snippet. Click on the "Properties" tab. (To see the descriptions, click on the "Default Properties Locked" button to unlock them and click on the small plus sign next to each property).

You can also see the default values in the properties grid. It's strongly recommended that you *not* change the property values here. If you do, your changes will be undone whenever you update or reinstall SPForm. Instead, add the ones you want to override to the snippet tag as in the example above, or create a custom property set as described below. Use back-ticks to surround the values. For "Yes/No" values use 1 for yes and 0 for no.

You can modify the form and the text on the two pages by duplicating the Tpl chunks used and use properties in the tag to tell SPForm to use your Tpl chunks instead of the default ones (more on this below). You can also tell SPForm to use your own CSS file for the styling by changing the &cssPath property in the snippet tag for either resource, or both of them. (See the "Styling the SPForm Pages" section below.)

Custom Property Set

Another method you can use to override the default values is to create a custom property set, but it's more complicated than just adding properties to the snippet tag.

Here's how to do that:

• In the Elements tree | Snippets | SPForm | 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 in a property set, 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. You can set those as you did for the SPForm snippet with either properties in the tag, or a custom property set.

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 (Click on the "Default Properties Locked" button first).

Important Note: If you have the "log" properties turned on at a site that receives a lot of email, 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 SPForm Pages

Almost anything you want to do in the way of styling the form and the response page can be done by using your own Tpl chunks, and by using a different CSS file.

You can rename the two resources, but it's recommended that you not change the aliases. For other changes, it's best to use your own Tpl chunks. Duplicate the chunks and put the names of the duplicates in the &spformTpl property (for the form on the Contact page) and/or the &spformProcTpl property (for the content of the "Thank You" page).

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.

Remember that 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 from a copy of the original and pass the path to it in the &spfCssPath property as a parameter in the snippet call or in your property set. The default CSS file is at assets/components/spform/css/spform.css.

Be sure to do this for both snippet calls if you've made changes that will affect the response page.

Another option is to paste the SPForm CSS file into your site's main CSS file, make your changes there, and use &spfCssPath=`""` in the snippet calls. SPForm will then ignore its own CSS file. Make sure the template you use includes a reference to your CSS file.

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."

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 block them either in your htaccess file or in the spfBanlist chunk. The spfBanlist chunk is easier to use. There are instructions in comments in the spfBbanlist chunk explaining how to do it. You can ban users by IP number, email address, or domain name (or partial versions of each). 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."

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

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.

Troubleshooting

For basic SPForm troubleshooting, see the SPForm FAQ page.

Uninstalling SPForm

You can uninstall SPForm in package manager, but you may need to remove the two resources manually. They are not modified during upgrades to preserve any properties you've added to the snippet tags.

Copyright © 2011-2025
Bob Ray