Build beautiful custom forms and manage submissions the WordPress way. View live previews of your forms while you build them. Create powerful and exstensible forms for simple contact inquiries, sign ups, subscriptions, events, payments, etc.
The problem of form creation in WordPress has been tackled many different ways. Custom Contact forms handles forms the WordPress way. The plugin provides a seamless user experience for managing your forms through the comfort of the WordPress media manager modal. CCF does not have as many features as some of it's competitors but instead provides you with just what you need. Custom Contact Forms is a legacy plugin name. The plugin can handle all types of forms not just contact forms.
Install the plugin in WordPress, you can download a zip via Github and upload it using the WP plugin uploader.
You can create and manage forms within a post by clicking the Add Form
button next to the Add Media
button:
Select or create a new form and click Insert into post
:
You can also add a form to your theme or plugin using PHP:
if ( function_exists( 'ccf_output_form' ) ) {
ccf_output_form( FORM_ID );
}
In case you want to use the shortcode, it is: [ccf_form id="FORMID"]
. You can find the form ID in the existing forms table of the form manager or in the URL when directly editing a form.
Each form has a number of settings that you should understand.
Title
- The main title for the form. This will be shown to the end user above the form.
Description
- A form description that will be shown to the end user below the form title.
Button Text
- This text will be shown to the end user on the submit button.
On form completion
- When a form is completed you can show a message or perform a browser redirect
Completion Message
- If you choose to show a message, you can customize the message to be shown.Redirect URL
- If you choose to perform a redirect, you can customize the redirect URL.Pause
- Pausing a form will temporarily disable new form submissions on the front end.
Pause Message
- This message will be shown if the form is paused.For each of your forms you can add email notifications (as many as you want). Email notifications will be sent when a form is successfully filled out. Each notification contains the following configurable settings:
Notification Title
- This is just an internal name for keeping track of your notification.
Email Content (HTML)
- This is the body of the email that will be sent. The email must be written using HTML. The following variables are support:
[all_fields]
- Shows all your form fields[ip_address]
- Shows the IP address of the submitter[current_date_time]
- Shows the current date and time[FIELD_SLUG]
- Each of your form fields can be inserted using their field slug."To" Email Addresses
- You can send each notification to as many emails as you want. Addresses have two types: custom
and
field
. custom
allows you to specify a specific email (such as your own). field
will pull the email address dynamically from a form field.
Reply To Email Address Type
- This allows you to set what email address is set as the notification email Reply To. WordPress Default
will use the default WordPress email address. Custom Email
will allow you to manually type in an address. Form Field
will allow you to choose an email field within the form to dynamically pull a email address.
Reply To Name Type
- This allows you to set the Reply To name in the notification email. Custom Name
will allow you to manually type in a name. Form Field
will allow you to choose a name field within
the form to dynamically pull a name.
"From" Email Address Type
- This allows you to set what email address the notification is sent from. WordPress Default
will use the default WordPress email address. Custom Email
will allow you to manually type in a from
address. Form Field
will allow you to choose an email field within the form to dynamically pull a from email
address.
"From" Name Type
- This allows you to set what name the notification email is sent from. Custom Name
will allow you to manually type in a from name. Form Field
will allow you to choose a name field within
the form to dynamically pull a from email name.
Email Subject Type
- This allows you to set what subject line is used on the notification email. Default
will use the CCF default subject. Custom Subject
will allow you to manually type in an email subject.
Form Field
will allow you to choose a field within the form to dynamically pull a subject line.
Include File Uploads
- If this is set to yes, file uploads will be sent in notification emails. This only applies if your
form has File Upload fields.
Note: In order for form notification changes to take affect, you will need to save the form.
For each of your forms, you can have a post (or custom post type) created every time someone submits the form. This is an extremely powerful feature.
Enable Post Creation
- Selecting Yes
will enable post creation. Note that posts won't start creating until you map some fields.Post Type
- You can choose the type of post type that will be created with each submission. This defaults to post
.Post Status
- You can choose the status (publish, draft, etc.) of the post that will be created with each submission. This defaults to draft
.Field Mappings
- You will need to map your form fields to the appropriate post fields. The available post fields are as possible:
Post Title
- Selecting this post field will map your form field to the title of the post.Post Content
- Selecting this post field will map your form field to the content of the post.Post Excerpt
- Selecting this post field will map your form field to the excerpt of the post.Post Date
- Selecting this post field will map your form field to the publish date of the post.Post Tags
- Selecting this post field will map your form field to the tags of the post.Custom Field
- Selecting this post field will map your form field to a custom field of the post. If you use Custom Field
, you will need to choose a custom field key.The building block of forms are fields. Each field has it's own set of settings that you can change on a per-field basis.
Internal Slug
- Every field in a form must have a unique slug. Slugs are auto-generated to make your life
easier. This makes it easier to develop with CCF.Label
- A label shows up above a field and is visible to the form user.Description
- A description shows up below a field and is visible to the form user.Initial Value
- A fields value upon loading the form.Required
- Required fields must be filled out for a form to be submitted.Class Name
- You can manually add classes to a fields wrapper element.Placeholder Text
- Very similar to Initial Value
but makes use of HTML5 placeholder.You can create forms using a number of field types. Certain field types of special field settings that are described below:
Single Line Text
- A single line text box. This is the most standard field.Paragraph Text
- A multi-line text box.Dropdown
- A simple dropdown of choices.Checkboxes
- A list of checkable choices.Radio Buttons
- A list of choices where only one can be chosen.Hidden
- A hidden field.File Upload
- Allow users to upload a file.
Note: Choiceable fields all handle choices the same way. Choices can be set with a value
and a label
. Values
are internal, and labels are visible to the end form user. If a choice does not have a value
, the choice will not
"count". Meaning the field will not be considered filled out if it's required.
Email
- A simple field that will ensure user input is a valid email address.
Name
- A field with two input boxes, one for first and one for last name.
Date/Time
- A field to ask for dates and time. You can configure the field to only ask for date or time if you choose.
Website
- A simple field that will ensure user input is a valid URL.
Address
- A field for US and international addresses.
Phone
- A simple field that will ensure user input is a valid phone number.
reCAPTCHA
- A Captcha field using Google's free reCAPTCHA technology. You will need to
sign up for reCAPTCHA before this field will work.
HTML
- An easy way to insert arbitrary HTML into the middle of a form.
<script>
.Section Header
- Inserts a pre-styled heading to break up your form visually.
CCF provides a very pretty table view for navigating your form submissions.
Click the Forms
item in the administration menu. Click on the specific form for which you want to view submissions.
Scroll to the Submissions
meta box. Click one the eye icon to view more information for a specific submission.
In the Submissions
meta box, you can add and remove columns. Click the cog icon at the top of the meta box to open
the screen options panel. In this panel you can check which columns you would like to see in the table.
In addition to being able to import/export forms with all fields and submissions, you can export submissions for individual forms as .CSV files. Click the icon within the form edit view like so:
Custom Contact Forms allows you to import and export forms and form submissions using the default WordPress importer/exporter functionality. You can export all your forms (with submissions) within the standard WordPress export view:
You can also export a single form (with submissions) within the Edit Form
screen:
Both export methods will produce a standard WordPress WXR file. You can import your WXR files using the standard WordPress importer:
Custom Contact Forms has a general settings page. Right now the only thing it contains is asset loading restriction which allows you to choose specific pages that form CSS and JS should be loaded on. This allows you to prevent a ton of unnecessary website bloat.
My form(s) will not save. What's wrong?
You most likely have a theme or plugin conflict. Try deactivating other plugins and activating a default theme. If forms still won't save, please create an issue.
Form mail is not getting emailed to me. What's wrong?
CCF relies on default WordPress email functionality. If CCF email is not sending, most likely no WordPress email is sending. You can test this by trying to send yourself a lost password email. If you don't receive the lost password email, then there is an issue with your host or a plugin/theme conflict.
My form won't submit on the front end of my website. What's wrong?
Most likely there is a JavaScript error on your page that is conflicting with the form. This is the result of a theme
or plugin conflict. Try deactivating other plugins and activating a default theme. Another possibility is that your
theme does not call wp_head()
or wp_footer()
.
Follow the configuration instructions above to setup the plugin. I recommend developing the plugin locally in an environment such as Varying Vagrant Vagrants.
If you want to touch JavaScript or CSS, you will need to fire up Grunt. Assuming you have npm installed, you can setup and run Grunt like so:
First install Grunt:
npm install -g grunt-cli
Next install the node packages required by the plugin:
npm install
Finally, start Grunt watch. Whenever you edit JS or SCSS, the appropriate files will be compiled:
grunt watch
Within the terminal change directories to the plugin folder. Initialize your unit testing environment by running the following command:
For VVV users:
bash bin/install-wp-tests.sh wordpress_test root root localhost latest
For VIP Quickstart users:
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
where:
wordpress_test
is the name of the test database (all data will be deleted!)root
is the MySQL user nameroot
is the MySQL user password (if you're running VVV). Blank if you're running VIP Quickstart.localhost
is the MySQL server hostlatest
is the WordPress version; could also be 3.7, 3.6.2 etc.Run the plugin tests:
phpunit
This plugin contains a valid Dockunit file for running unit tests across a variety of environments locally (PHP 5.2 and 5.6). You can use Dockunit (after installing it via npm) by running:
dockunit
Coming soon.
If you identify any errors or have an idea for improving the plugin, please open an issue.
Custom Contact Forms is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.