Global Form Tag Parameters and Fields

The following tag parameters and form input fields are common to all CartThrob form tags. Form tags may have additional parameters and fields. Follow links below for more information about specific forms.

Table of Contents

Parameters

HTML parameters

id

CSS id of your form. This is an arbitrary value.

id="myform"
class

CSS class of your form. This is an arbitrary value.

class="my_form_class"
name

The name of your form. This is an arbitrary value.

name="my_form_name"
onsubmit

Optional javascript function to run once the form is submitted.

onsubmit="your_custom_javascript()"
logged_out_redirect

If the "User must be logged in" setting is set to "yes", this is the location the logged_out user is redirected to when they try to view this form

logged_out_redirect="cart/login"
variable_prefix

Allows you to add a prefix to all variables within the tag to avoid variable collisions with another tag. 

variable_prefix="my_var"

This is an example of how you could then call the entry_id variable within the tag. 

my_var_entry_id

Form submission parameters

secure_action

If set to "yes" the form will be submitted via https://

secure_action="yes"
return

This is the URL you'd like the site redirected to when the operation is complete. If left blank, the page will not redirect.

return="cart/view_cart"
secure_return

If set to "yes" the form will redirect to the https:// version of your return url after form submission.

secure_return="yes"

Validation parameters

required

A pipe delimited list of form fields you wish to require for the current form. Submitting the form without these fields will result in an error.

required="first_name|last_name|item_options[product_size]"
rules:*your_field*

A pipe delimited list of CodeIgniter Form Validation rules to follow for the specified field.

rules:first_name="required|min_length[2]" rules:item_options[product_size]="required"

NOTE ExpressionEngine's version of CodeIgniter's validation rules is a few rules short of the complete set. Until EE's update, we currently offer the following validation rules: 

alpha
alpha_dash
alpha_numeric
exact_length
integer
is_natural
is_natural_no_zero
is_numeric
matches
max_length
min_length
numeric
required
valid_base64
valid_email
valid_emails
valid_ip
show_errors

Set to "no" to suppress any errors from being shown upon form submission. Defaults to "yes".

show_errors="yes"

error_handling

With this setting, you can display your form submission errors in the context of your form, rather than the standard ExpressionEngine user message template. Use this in combination with the error message variables.

error_handling="inline"
language

There are several validation messages you may encounter with CartThrob's coupon code system. These errors announce whether a coupon is expired or invalid. If you have a language you'd like these to display in, you can add the 2 character ISO 639-1 language code (en), or the full language name (english). Language files control the contents of these validation messages.

language="{segment_3}"
action

This setting is optional and used in scenarios where you need control over the action, such as a multi-language site with the language in the url.

action="/en/cart/checkout"

Inline Errors

When using inline error handling, you can display your errors within the context of your form using these variables, conditionals, and tag pairs.

When using inline errors, you must set a value to your input fields so that submitted data persists when an error occurs:

<input type="text" name="first_name" value="{first_name"}>

{if field_errors_exist}

This is true if you have errors that are associated with a specific field.

{if field_errors_exist}
<ul class="errors">
    {field_errors}
    <li>{error}</li>
    {/field_errors}
</ul>
{/if}

{if global_errors_exist}

This is true if you have errors that are not associated with a specific field.

{if global_errors_exist}
<ul class="errors">
    {global_errors}
    <li>{error}</li>
    {/global_errors}
</ul>
{/if}

{if errors_exist}

This is true if you have any global or field errors.

{if errors_exist}
There were some errors submitting your form.
{/if}

{if error:your_field}

This is true if you have an error associated with this particular field.

<input type="text" name="first_name" value="{first_name}">
{if error:first_name}
<p class="error">{error:first_name}</p>
{/if}

{error:your_field_name}

An error message associated with a particular field.

<label for="first_name"><span class="error">{error:first_name}</span></label>
<input type="text" id="first_name" name="first_name" value="{first_name}">

If you are using an array field, such as item_options, your error param will look like this.

<label for="item_options[product_size]"><span class="error">{error:item_options[product_size]}</span></label>
<input type="text" id="item_options[product_size]" name="item_options[product_size]" value="{item_options:product_size}">

{field_errors}{/field_errors}

Lists errors associated with specific fields.

{field_errors}
<p class="error" id="error_{field}">{error}</p>
{/field_errors}

{errors}
{!-- contains these variables--}
{error}
{field}
{error:count}
{error:total_results}
{if first_error}{/if}
{if last_error}{/if}
{/errors}

{global_errors}{/global_errors}

Lists errors not associated with a specific field

{global_errors}
<p class="error">{error}</p>
{/global_errors}

{global_errors}
{!-- contains these variables--}
{error}
{error:count}
{error:total_results}
{if first_error}{/if}
{if last_error}{/if}
{/global_errors}

{errors}{/errors}

Lists ALL errors.

{errors}
<p class="error">{error}</p>
{/errors}

{errors}
{!-- contains these variables--}
{error}
{field}
{error:count}
{error:total_results}
{if global_error}{/if}
{if field_error}{/if}
{if first_error}{/if}
{if last_error}{/if}
{/errors}

Tag Pair Variables

The three error tag pairs all contain the following variables:

error

{error}

field

{field}

error:count

{error:count}

error:total_results

{error:total_results}

{if global_error}

{if global_error}

{if field_error}

{if field_error}

{if first_error}

{if first_error}

{if last_error}

{if last_error}

Form Fields

Input fields are used to gather customer data in CartThrob forms. There are two primary types of input fields: standard inputs and custom data. These inputs follow this basic pattern:

Standard Inputs

<input type="text" name="first_name" />

Custom Data

<input type="text" name="custom_data[whatever]" />

When data is captured using CartThrob forms, standard inputs are used to capture common information like names and addresses.

In some cases you may want to save some or all of the customer information on one or more pages. This tag makes it easy to collect customer information, and output it later. You can later use saved data to populate other forms and pages using global tag variables. You must add these form fields to your form yourself, example:

<input type="text" name="company" value="CartThrob" />

Common

  • first_name
  • last_name
  • address
  • address2
  • city
  • state
  • zip
  • country
  • country_code (GBR, USA)
  • company
  • phone
  • email_address
  • description (description of the entire order or the store itself; used by some gateways)
  • use_billing_info
  • shipping_first_name
  • shipping_last_name
  • shipping_address
  • shipping_address2
  • shipping_city
  • shipping_state
  • shipping_zip
  • shipping_country
  • shipping_country_code
  • shipping_company

Advanced

  • ip_address
  • CVV2 (the number on the back of a credit card)
  • card_type
  • expiration_month
  • expiration_year
  • po_number
  • card_code
  • issue_number (used by certain payment gateways)
  • transaction_type (used by certain payment gateways)
  • bank_account_number
  • check_type
  • account_type
  • routing_number
  • begin_month
  • begin_year
  • bday_month (certain payment gateways request the beginning date for credit cards)
  • bday_day
  • bday_year
  • currency_code (GBP, USD)
  • language
  • shipping_option
  • weight_unit
  • region (used for taxes)
  • success_return (when an operation with some payment gateways is complete this is where a user will be sent)
  • cancel_return (when an operation with some payment gateways fail this is where a user will be sent)

Where is the credit_card_number field?

Because all of this data is stored in sessions, we do not store the actual credit card number for security purposes. Though the chance of data theft is probably remote, and we do not want to encourage bad security practices by storing the credit card number.

Buy Now

Top