Difference between revisions of "Pages:Custom Forms"
From Whirlwind eCommerce Wiki
(→EXAMPLES: added fieldValidations example) |
|||
| (6 intermediate revisions by 2 users not shown) | |||
| Line 10: | Line 10: | ||
;redirect: The URL where the visitor should be directed to following submission of the form. For each custom form it is recommended you create an accompanying page that will display a thank you or confirmation message. This page should be where the visitor is directed to using the 'redirect' field following form submission. | ;redirect: The URL where the visitor should be directed to following submission of the form. For each custom form it is recommended you create an accompanying page that will display a thank you or confirmation message. This page should be where the visitor is directed to using the 'redirect' field following form submission. | ||
;otherFields: A comma delimited list of custom field names. Leave empty if no custom fields are being used. | ;otherFields: A comma delimited list of custom field names. Leave empty if no custom fields are being used. | ||
| + | |||
| + | ===OPTIONAL HIDDEN FIELDS=== | ||
| + | ;fieldValidations: Use to require certain fields. Comma delimited list of required fields, commands and messages. Example: "firstName/min:1:Must enter first name,zipCode/min:5:You must enter a 5 digit zip code,emailAddress/email:Must enter a valid email address" sets firstName to require min length 1 character, zipCode to require min length of 5 characters and emailAddress to be a valid email address. | ||
| + | ::Each field validation should follow the format: /command:attributes:error message. Available validations are: | ||
| + | ::*min: specified a minimum number of characters. Example "firstName/min:1:You must enter a first name". | ||
| + | ::*email: validates entry is formatted like an email address: Example "emailAddress/email:You must enter a valid email address". | ||
===CORE FIELDS=== | ===CORE FIELDS=== | ||
| Line 17: | Line 23: | ||
;emailAddress: A text field with a maxlength of 255 | ;emailAddress: A text field with a maxlength of 255 | ||
;subscribe: A checkbox with a value of 1 (if checked, this will pass and trigger the newsletter registration process for the entered emailAddress) | ;subscribe: A checkbox with a value of 1 (if checked, this will pass and trigger the newsletter registration process for the entered emailAddress) | ||
| + | |||
===CUSTOM FIELDS=== | ===CUSTOM FIELDS=== | ||
| Line 126: | Line 133: | ||
| − | Catalog Request Example: | + | Catalog Request Example (With field validations): |
<source lang="HTML4strict"> | <source lang="HTML4strict"> | ||
| Line 135: | Line 142: | ||
<input type="hidden" name="fa" value="USER.formSubmit"> | <input type="hidden" name="fa" value="USER.formSubmit"> | ||
<input type="hidden" name="redirect" value="index.php?pageId=456&message=You will receive a copy of our catalog shortly"> | <input type="hidden" name="redirect" value="index.php?pageId=456&message=You will receive a copy of our catalog shortly"> | ||
| + | <input type="hidden" name="fieldValidations" value="emailAddress/email:A valid email address is required,street1/min:1:Street address is required,city/min:1:City is required,state/min:1:Please select a state,zipCode/min:5:Please enter a valid zip code"> | ||
| − | <input type="hidden" name="otherFields" value="" /> | + | <!-- a shipping form will contain custom fields here --> |
| + | <input type="hidden" name="otherFields" value="street1,street2,city,state,zipCode" /> | ||
| − | <h1> | + | <h1>Order a Catalog</h1> |
<br>First Name: <input type="text" name="firstName" size=25 maxlength=50> | <br>First Name: <input type="text" name="firstName" size=25 maxlength=50> | ||
<br>Last Name: <input type="text" name="lastName" size=25 maxlength=50> | <br>Last Name: <input type="text" name="lastName" size=25 maxlength=50> | ||
<br>Email Address: <input type="text" name="emailAddress" size=50 maxlength=255> | <br>Email Address: <input type="text" name="emailAddress" size=50 maxlength=255> | ||
| + | <br>I would like to receive occassional emails about specials and what-not: <input type="checkbox" name="subscribe" value="1"> | ||
| + | <br> | ||
| − | <!-- | + | <!-- the following custom fields are used to make a shipping form --> |
| − | + | <br>Address: <input type="text" name="street1" size=50> | |
| − | + | <br>Address Line 2: <input type="text" name="street2" size=50> | |
| − | <input type=" | + | <br>City: <input type="text" name="city" size=50> |
| + | <br>State: <select name="state"> | ||
| + | <option>AK</option> | ||
| + | <option>AL</option> | ||
| + | <option>... more states here ...</option> | ||
| + | </select> | ||
| + | <br>Zip: <input type="text" name="zipCode" size=10> | ||
| − | <br /><input type="submit" value=" | + | |
| + | <br /><input type="submit" value="ORDER!" /> | ||
</form> | </form> | ||
</source> | </source> | ||
Latest revision as of 14:58, 25 May 2010
Custom forms allow page content managers to create forms on the fly in the WYSIWYG editor. A knowledge of HTML form coding is required to do this. When a custom form is submitted by a website visitor, it is emailed to specified recipients (using the emailTo field below) AND it is placed into the database accessible via Form Submissions in system administration.
Each form has required hidden fields, core fields and custom fields:
REQUIRED HIDDEN FIELDS
Required hidden fields send data to the system that tells it how to process the form. The required hidden fields are as follows:
- fa
- This field should ALWAYS have a value of "USER.formSubmit" - which tells the system this is a custom form that needs to be processed.
- formType
- This field's value is used to classify and organize the form submissions made through this form. For instance, enter "newsletter" as the value if this form is being used to register for the newsletter; or enter "catalog request" as the value if this is a catalog request form. This value can later be used when looking up the form in Form Submissions so you can filter only certain forms.
- emailTo
- A comma delimited list of email addresses that will receive this form's contents upon submission. Use to send yourself and others notifications of these forms as they are submitted. Leave empty if there are no recipients.
- redirect
- The URL where the visitor should be directed to following submission of the form. For each custom form it is recommended you create an accompanying page that will display a thank you or confirmation message. This page should be where the visitor is directed to using the 'redirect' field following form submission.
- otherFields
- A comma delimited list of custom field names. Leave empty if no custom fields are being used.
OPTIONAL HIDDEN FIELDS
- fieldValidations
- Use to require certain fields. Comma delimited list of required fields, commands and messages. Example: "firstName/min:1:Must enter first name,zipCode/min:5:You must enter a 5 digit zip code,emailAddress/email:Must enter a valid email address" sets firstName to require min length 1 character, zipCode to require min length of 5 characters and emailAddress to be a valid email address.
- Each field validation should follow the format: /command:attributes:error message. Available validations are:
- min: specified a minimum number of characters. Example "firstName/min:1:You must enter a first name".
- email: validates entry is formatted like an email address: Example "emailAddress/email:You must enter a valid email address".
- Each field validation should follow the format: /command:attributes:error message. Available validations are:
CORE FIELDS
Core fields are visitor-populated fields that can be used to organize and classify form submissions. The emailAddress field in particular is required if you wish to include the subscribe option (which allows visitors to subscribe to the newsletter when this form is submitted).
- firstName
- A text field with a maxlength of 50
- lastName
- A text field with a maxlength of 50
- emailAddress
- A text field with a maxlength of 255
- subscribe
- A checkbox with a value of 1 (if checked, this will pass and trigger the newsletter registration process for the entered emailAddress)
CUSTOM FIELDS
Custom fields allow the content manager creating the form to add any number of additional form fields that will be stored upon submission. Note that form submissions cannot be searched or filtered by the contents of these fields, but they are present when looking up submitted forms and are listed in exports of form submissions (which are then sortable by the custom fields in Excel). Custom fields can have any name EXCEPT the reserved CORE and REQUIRED HIDDEN field names (fa,formType,emailTo,redirect,firstName,lastName,emailAddress,subscribe,otherFields). All custom field names MUST be entered into the hidden field "otherFields" (see REQUIRED HIDDEN FIELDS above)
EXAMPLES
Generic Example, with detailed explainations:
<!-- start our form --> <form action="index.php" method="POST"> <!------------------------> <!--- HIDDEN FIELDS ----> <!------------------------> <!-- the formType field attached a 'category' to this form when submitted. If you have multiple custom forms on your website, this helps to easily search, filter and group form submissions ideas for this are: newsletter, catalog request, contact us, feedback... --> <input type="hidden" name="formType" value="this form"> <!-- the emailTo field allows you to enter recipients of this forms contents When the form is submitted, the contents will be sent to the email addresses in this field --> <input type="hidden" name="emailTo" value="email@website.com,anotheremail@website.com"> <!-- the fa field tells the websiteto process this form on submission --> <input type="hidden" name="fa" value="USER.formSubmit"> <!-- the redirect field tells the website where to put the visitor after the form has been procesed --> <input type="hidden" name="redirect" value="index.php?pageId=123&message=Thank you for filling our our form"> <!-- the following otherFields field is REQUIRED if you have ANY custom fields enter a comman delim list of the field names --> <input type="hidden" name="otherFields" value="source,color,likeItalian" /> <!---------------------> <!-- CORE FIELDS ------> <!---------------------> <!-- first name, last name and email fields are CORE form fields but are optional - you do not have to include these fields, but if you do, make sure you use the correct names --> <br>First Name: <input type="text" name="firstName" size=25 maxlength=50> <br>Last Name: <input type="text" name="lastName" size=25 maxlength=50> <br>Email Address: <input type="text" name="emailAddress" size=50 maxlength=255> <!-- the subscribe field is another CORE field that is optional. If it is used and checked, than the newsletter subscription process will be triggered for the passed emailAddress upon form submission --> <br>Check here to subscribe to our newsletter: <input type="checkbox" name="subscribe" value="1"> <!---------------------> <!-- CUSTOM FIELDS ------> <!---------------------> <!-- any number of custom fields can be created each can have any name as long is not one of the above hidden or core field names make sure to populate the otherFields field with the names of your custom fields or they will not work --> <br />How did you find out about us? <input type="text" name="source" size=50 maxlength=100 /> <br />What is your favorite color? <select name="color"> <option>Red</option> <option>Blue</option> <option>Green</option> </select> <br />Do you like italian food? YES<input type="radio" name="likeItalian" value="1" /> NO<input type="radio" name="likeItalian" value="0" /> <!-- be sure all your custom field names are entered into the "otherFields" field see above REQUIRED HIDDEN FIELDS for details --> <!--- DONE WITH CUSTOM FIELDS ----> <!-- just your plain run of the mill submit button - nothing special --> <br /><input type="submit" value="SUBMIT" /> <!-- close out the form --> </form>
Newsletter Sign Up Form Example:
<form action="index.php" method="POST"> <input type="hidden" name="formType" value="newsletter"> <input type="hidden" name="emailTo" value="newsletters@mywebsite.com"> <input type="hidden" name="fa" value="USER.formSubmit"> <input type="hidden" name="redirect" value="index.php?pageId=123&message=Thank you for registering for our newsletter"> <!-- no custom fields in this example, but you are free to add if you need them! --> <input type="hidden" name="otherFields" value="" /> <h1>Register for our newsletter!</h1> <br>First Name: <input type="text" name="firstName" size=25 maxlength=50> <br>Last Name: <input type="text" name="lastName" size=25 maxlength=50> <br>Email Address: <input type="text" name="emailAddress" size=50 maxlength=255> <!-- notice the subscribe field is hidden here, since it is assumed they want to subscribe otherwise they would not be submitting this form --> <input type="hidden" name="subscribe" value="1"> <br /><input type="submit" value="SUBSCRIBE!" /> </form>
Catalog Request Example (With field validations):
<form action="index.php" method="POST"> <input type="hidden" name="formType" value="catalog request"> <input type="hidden" name="emailTo" value="catalogrequests@mywebsite.com"> <input type="hidden" name="fa" value="USER.formSubmit"> <input type="hidden" name="redirect" value="index.php?pageId=456&message=You will receive a copy of our catalog shortly"> <input type="hidden" name="fieldValidations" value="emailAddress/email:A valid email address is required,street1/min:1:Street address is required,city/min:1:City is required,state/min:1:Please select a state,zipCode/min:5:Please enter a valid zip code"> <!-- a shipping form will contain custom fields here --> <input type="hidden" name="otherFields" value="street1,street2,city,state,zipCode" /> <h1>Order a Catalog</h1> <br>First Name: <input type="text" name="firstName" size=25 maxlength=50> <br>Last Name: <input type="text" name="lastName" size=25 maxlength=50> <br>Email Address: <input type="text" name="emailAddress" size=50 maxlength=255> <br>I would like to receive occassional emails about specials and what-not: <input type="checkbox" name="subscribe" value="1"> <br> <!-- the following custom fields are used to make a shipping form --> <br>Address: <input type="text" name="street1" size=50> <br>Address Line 2: <input type="text" name="street2" size=50> <br>City: <input type="text" name="city" size=50> <br>State: <select name="state"> <option>AK</option> <option>AL</option> <option>... more states here ...</option> </select> <br>Zip: <input type="text" name="zipCode" size=10> <br /><input type="submit" value="ORDER!" /> </form>
