====== Custom Checkout Fields ======

**Important: Requires v0.2.4 or higher.** Set your version in your store settings.

===== Overview =====

Sometimes it is necessary or desirable to include additional input fields on checkout, such as:
  * Checkbox to require Terms of Service agreement.
  * Checkbox to opt-in to a mailing list.
  * Input field for a referrer code.
  * Checkbox to "send as a gift", with a text area for a gift card note.
  * Input field for date of birth.

It's (relatively) easy to add custom fields to your FoxyCart checkout page, providing you know some HTML. In a nutshell, any code you insert in between the tags ''^^custom_begin^^'' and ''^^custom_end^^'' will be inserted in your checkout page, in between a container ''div#fc_custom_fields_container''.

===== An Example =====

Here's a basic example of the above functionality. It doesn't matter where you put this code. It will be //moved into// the checkout form when FoxyCart loads your checkout page, so it can be after the ''</body>'' or ''</html>'' tags if you want.

<code html>
^^custom_begin^^

<h2>Additional Information</h2>

<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>
			<h4>Updates</h4>
			<input type="checkbox" name="Update_List" value="yes" checked="checked" />
			<label for="Update_List">Leave this box checked to receive occasional updates about our products. We will not share your email address, and you can unsubscribe at any time.</label>

		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->

^^custom_end^^
</code>

This code will then be inserted in your checkout page, **below the address fieldsets** and **above the shipping fieldset**. It will be wrapped in a container div, like this:
<code html>
<div id="fc_custom_fields_container" class="fc_fieldset_container">

<h2>Additional Information</h2>

<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>

			<h4>Updates</h4>
			<input type="checkbox" name="Update_List" value="yes" checked="checked" />
			<label for="Update_List">Leave this box checked to receive occasional updates about our products. We will not share your email address, and you can unsubscribe at any time.</label>

		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>

		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->

</div><!-- #fc_custom_fields_container -->
</code>

===== What to name your fields =====

You can name your fields anything you want, but **we recommend using the underscore (''_'') for spaces**, and capitalizing your input names as you'd like them displayed. For all receipts, we will convert underscores to spaces for you.

For example, if you have ''<input name="Update_List" />'', it will be displayed in your receipt (and email receipts) as ''Update List''.

===== What about Receipts and the Datafeeds? =====

The custom fields will be inserted at the bottom of your your receipt (after checkout), as well as in any emails that include the ''^^receipt^^'' placeholder.

Custom checkout fields are included in all XML datafeeds from version 0.3.
===== What if I'm using multiship and I need a custom field per shipto? =====

No problem! Just wrap your custom fields in ''^^multiship_custom_begin^^'' and ''^^multiship_custom_end^^'' and you're good to go.


===== A Note about Checkboxes =====

**Checkboxes do not post** if they are unchecked. This is standard HTML form behavior, but it's worth noting, especially if you're using checkboxes for your XML datafeeds.

===== Required Fields =====

With v0.3.1 and on you can required a custom field by adding ''fc_required'' to its class (of the ''input''). You can add an error message (which will display if it's left blank) by adding a ''label.fc_error'' with ''for="your_field_name"'', like this:
<code html><label class="fc_error" style="display: none;" for="terms_of_service">Please accept our Terms of Service.</label></code>
For example, if you wanted to force a Terms of Service acceptance, it'd look like this:
<code html>
^^custom_begin^^

<h2>Additional Information</h2>

<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>
			<h4>Terms of Service</h4>
			<input type="checkbox" name="terms_of_service" value="accept" checked="checked" class="fc_required" />
			<label for="terms_of_service">By checking this box you agree to our <a href="http://www.YOURDOMAIN.com/tos">Terms of Service</a>.</label>
			<label class="fc_error" style="display:none;" for="terms_of_service">You must accept our Terms of Service to complete this transaction.</label>
		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->

^^custom_end^^
</code>

===== "Sensitive" Custom Checkout Fields =====

If you'd like to collect information that you //do not want to be emailed//, such as Social Security Numbers or other sensitive data, you can prefix your field names with ''h:'', like this:
<code html>
Please enter your Social Security Number: <input type="text" name="h:social_security_number" />
</code>
"Sensitive" fields are displayed in the admin's transaction view, and are sent in the XML, but are not emailed.