Deko Boko – A reCAPTCHA Contact Form Plugin for WordPress

Support development of Deko Boko

Deko Boko is a simple but highly extensible contact form for WordPress. You can see it in action on my contact page (but please only actually send me an email if you have something meaningful to say – thanks).

There are a number of good contact forms for WordPress, so why create another one? There are two things that make Deko Boko different from the others:

It uses reCAPTCHA for blocking spam. reCAPTCHA is a great project that uses data from its captcha form submissions to help digitize books.
The Deko Boko contact form can be extended any way you want, but without the need for complicated admin menus. If you’re comfortable editing HTML, then you can add any number and any type of input fields to the contact form. You can control which fields are optional or required. When the form is submitted, any fields that you added will have their data included in the body of the email.

Additional features:

The form layout is controlled by a CSS styled list, which provides a great deal of flexibility. With CSS edits you can change the position of the field labels to top-aligned, left-justified, or right-justified. Deko Boko uses the techniques outlined in Cameron Adam’s excellent article on form layout (so if you need to add things like new fieldsets and legends, follow the advice in his article). A sample form is included for you to use as a template for your own custom version.
Plays nicely with WP-reCAPTCHA, the WordPress plugin for using reCAPTCHA to protect against comment spam. If you already have a API key set up with WP-reCAPTCHA, Deko Boko will automatically use it.
Includes selectors for using different themes and languages with the reCAPTCHA widget, as well as support for custom CSS for the reCAPTCHA widget.
Support for multiple, custom contact forms.
“CC Me” option for users to receive a copy of the message they submit to you. You can specify header text and footer text to “wrap” this message. Deko Boko can automatically include the name of your blog and a timestamp in the header or footer text.
Security in addition to reCAPTCHA is included. Deko Boko protects against email header injections and XSS attacks.

New in version 1.2:

You can have Deko Boko load its stylesheet only on pages where you use the Deko Boko contact form, so it won’t be loaded unnecessarily on other pages.
Localization support: a dekoboko.pot file is included to enable translations to other languages.
If you want to make a custom contact form, a template is included to get you started.
If you want to customize the dekoboko.css stylesheet, you can place it in your active theme folder, and Deko Boko will find it there (that way you won’t lose your stylesheet customizations when upgrading Deko Boko).
Uninstall option.
Uses a nonce field for additional security.

Installation

Download the zip file, unzip it, and copy the “dekoboko” folder to your plugins directory. Then activate it from your plugin panel. After successful activation, Deko Boko will appear under your “Settings” tab. Note that Deko Boko requires WordPress 2.5 or higher.

Important note to upgraders: you will need to deactivate and then reactivate Deko Boko after you upload the new files. Also, the contact form now uses a nonce field for additional security. If you have made your own contact form template, you will need to add a nonce hidden input field, like this:

<?php wp_nonce_field(’dekoboko_nonce’, ‘dekoboko_nonce’); ?>

Usage Guide

Deko Boko Settings

Before you can use Deko Boko, you need to fill out its Settings form. First, you will need a reCAPTCHA API key. If you are already using the WP-reCAPTCHA comments plugin, then you don’t need another key (you’ll see the form is pre-filled with your existing key). If you’re not using WP-reCAPTCHA, then follow the link on the Settings form to get a key. Then the only other requirement is that you provide the email address where you’d like the form submissions to go. All the other settings include comments explaining what they do.

Putting the Contact Form on a Page

Just put the shortcode tag:

[dekoboko]

on a page, and that’s where the Deko Boko contact form will appear.

That’s all there is to it!

Customizing and Extending the Contact Form

The default configuration of the form may be suitable for your needs. It includes inputs for a name, return email address, message subject, message body, and a “cc me” checkbox. All fields except the subject and “cc me” are required.

If you want to make changes or additions, you’ll need to be comfortable editing HTML (for adding or changing form fields) and CSS (if you want to change the layout of the form). Use sample-form.php as a guide if you want to make your own contact form (located in the Deko Boko “display” folder). Please look through that file before reading further, so you can see how it’s put together. If you want to make substantial changes, take a look at the techniques outlined in Cameron Adam’s excellent article on form layout, which I used as guide for Deko Boko.

You can add any number and any type of input fields you want. Deko Boko requires you to use either the dekoboko_optional or dekoboko_required form input arrays. Deko Boko takes advantage of PHP’s ability to process HTML form inputs as arrays, allowing you to add any new fields you like. For example, you could add an input like this in your form:

<li>
    <label for="dekoboko_favorite_color">What is your favorite color?</label>
    <input type="text" name="dekoboko_optional[favorite_color]" id="dekoboko_favorite_color" value="<?php echo $dekoboko_optional['favorite_color']; ?>" size="30" />
</li>

If you want a form field that is optional for the user to fill out, then use the dekoboko_optional array. If you want to make it a required input, then use dekoboko_required.

Deko Boko uses dekoboko.css to control the layout of the form (also in Deko Boko’s “display” folder). It uses an ordered list to control the form layout. The CSS places the labels to the left of the input fields, and then right-justifies the labels. You can adjust the CSS to change the layout (see Cameron Adam’s article, mentioned above). If you customzie the stylesheet, place your custom version in your active theme folder. Deko Boko will find it there, and you won’t have to worry about your customizations being overwritten the next time you upgrade Deko Boko.

Note the id and name values of the input field are not the same. It’s standard practice to make them the same, but in this case, the brackets in the name are needed for PHP to process the inputs as desired, but brackets are not allowed in an id. You can use any text you like for the id of an input, just make sure you use the same value with the for attribute in the label.

Also note the purpose of the php code in the input fields’ value attribute is to re-display what people type if the form fails validation. For example, if they get the reCAPTCHA wrong, the form will re-display with an error message to let them know, and the form inputs will be filled with everything they typed previously, so they don’t have to type it again. The form inputs are “cleaned” before they’re re-displayed, to protect against XSS attacks. You’ll want to include value attributes like this if you add your own fields to the form.

Changing the Look and Language of the reCAPTCHA Widget

On the Deko Boko Settings page, you can choose a theme for the reCAPTCHA widget as well as a language. If you want to use your own colors, follow the instructions on the Deko Boko Settings page and in the dekoboko.css file.

Saving and Displaying Your Custom Contact Form

By default, the contact-form.php file that comes with Deko Boko is used to display the contact form. If you need more than one contact form, our you wish to customize the form, do the following:

Make a copy of sample-form.php, and save it with a different name into the Deko Boko plugin’s “display” folder. You can name it anything you like. For this example, let’s call it “contact-form-2.php”
Using the guidelines above, edit the file however you like.
To display your custom form, us the Deko Boko shortcode like this:
```
[dekoboko template="contact-form-2.php"]
```

What Does Deko Boko Mean?

Deko Boko Friends It is a Japanese onomatopoeia word that means bumpy, uneven or, rough (picture yourself bouncing up and down driving on a really bumpy road). It’s also the name of a wonderful Japanese kids’ program, Dekoboko Friends, which recently has been translated to English and is shown on Nick Jr. The name for the plugin is inspired by the show – all your goofy friends can use the Deko Boko plugin to get in touch with you.

Under the Hood

There are a couple things worth noting on how Deko Boko works:

Unlike many other contact forms, Deko Boko uses WordPress’ wp_mail function to send mail, rather than calling the PHP mail function directly. This means if you have any email related plugins that modify how WordPress sends mail, Deko Boko will send mail the same way as the rest of your WordPress installation.
Deko Boko uses the new WordPress shortcode API. This means you need WordPress 2.5 or higher to use Deko Boko.

Change Log

0.9 – Beta version. First public release.
1.0
- Added Settings selector for choosing a reCAPTCHA theme, and CSS color options for use with the “clean” theme (thanks Matthew E. for the suggestion).
- Added protection from cross site scripting attacks when displaying an invalid email address back to the user (thanks Chris S.).
- Added support for multiple templates
- Added “CC Me” option (thanks Cheryl M.)
- Bug Fix: now behaves correctly if you have a form with no optional fields (thanks Jeff for reporting this)
1.0.1 – bug fix: the Settings form now correctly lists the selected reCAPTCHA widget theme.
1.1
- Complete rewrite of the XHTML and CSS for the contact form. Both are now easier to work with, the XHTML is semantically correct, and no CSS filters are needed for different browsers. The rewrite was prompted by IE7’s incompatibility with the widely used “clearfix” code in the previous versions of Deko Boko.
- The latest version of WP-reCAPTCHA changed the name of the WordPress option variable where it stores its API key, so Deko Boko now looks for it under the new name and the old name.
- Added a language selector to the Deko Boko settings menu, for choosing a language other than English for the reCAPTCHA widget.
1.2
- Added option to load the Deko Boko stylesheet only on pages using the contact form, so it won’t be loaded unnecessarily on other pages.
- Add localization support: a dekoboko.pot file is included to enable translations to other languages.
- In addition to the standard contact form, a sample form is now also included, as a guide for users to make their own custom contact forms (to avoid confusion for non-programmers, the sample form does not include localization code).
- Supports a custom copy of dekoboko.css in the active theme folder (so customizations are not lost when Deko Boko is upgraded).
- Added an uninstall option.
1.2.1 – bug fix: now correctly saves the reCAPTCHA API keys if they hadn’t been set previously (was failing to save if WP-reCAPTCHA hadn’t been installed previously); bug fix: now correctly cleans up old-style Deko Boko options from the database.