Custom Contact Forms [![Build Status](https://travis-ci.org/tlovett1/custom-contact-forms.svg?branch=master)](https://travis-ci.org/tlovett1/custom-contact-forms) [![Dockunit Status](https://dockunit.io/svg/tlovett1/custom-contact-forms?master)](https://dockunit.io/projects/tlovett1/custom-contact-forms#master) =============== Build beautiful custom forms the WordPress way. __Note: Version 6.0 breaks backwards compatibility. You will need to perform a database update after upgrading from anything pre 6.0. You may also need to reconfigure some of your forms.__ ## Purpose 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. ## Requirements * WordPress 3.9+ * PHP 5.2.4+ ## Installation Install the plugin in WordPress, you can download a [zip via Github](https://github.com/tlovett1/custom-contact-forms/archive/master.zip) and upload it using the WP plugin uploader. ## Usage You can create and manage forms within a post by clicking the `Add Form` button next to the `Add Media` button: ![Add a form in a post](https://tlovett1.files.wordpress.com/2015/01/add-form-post.png) Select or create a new form and click `Insert into post`: ![Insert a form into a post](https://tlovett1.files.wordpress.com/2015/01/insert-form.png) You can also add a form to your theme or plugin using PHP: ```php if ( function_exists( 'ccf_output_form' ) ) { ccf_output_form( FORM_ID ); } ``` ### Form Settings 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. #### Form Notifications For each of your form 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: * `"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. * `"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. __Note:__ In order for form notification changes to take affect, you will need to save the form. ### Fields 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. #### Standard Field Settings * `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. #### Field Types You can create forms using a number of field types. Certain field types of special field settings that are described below: ##### Normal Fields * `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. * __Allowed Files Types__ - Restrict the file extensions that can be uploaded. If left blank, this will default to whatever is allowed by WordPress. * __Max File Size__ - Restrict the max file size allowed to be uploaded. If left blank, will default to whatever is allowed by WordPress and your server. __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. ##### Special Fields * `Email` - A simple field that will ensure user input is a valid email address. * __Require Confirmation__ - Enabling this will insert another input box where the user must type the same email again. * `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. * __Enable Date Select__ - Will prompt the user for a date selection. * __Enable Time Select__ - Will prompt the user for a time selection. * `Website` - A simple field that will ensure user input is a valid URL. * `Address` - A field for US and international addresses. * __Type__ - Allows you to prompt the user for a United States or international address. * `Phone` - A simple field that will ensure user input is a valid phone number. * __Format__ - Allows you to prompt the user for a United States or international phone number. * `reCAPTCHA` - A Captcha field using Google's free reCAPTCHA technology. You will need to [sign up](https://www.google.com/recaptcha) for reCAPTCHA before this field will work. * __Site Key__ - Your Google reCAPTCHA site key. * __Secret Key__ - Your Google reCATPCHA secret key. ##### Structure Fields * `HTML` - An easy way to insert arbitrary HTML into the middle of a form. * __HTML Content__: Supports all HTML tags except `