In Brief: A form element for setting properties for a "product", which combined with an e-comm confirmation page element, can be used to sell items using the proper transaction agent.

Dependencies: A standard form page.

Hints & Tricks: You can switch payment processors at any time, but be aware that each payment agent may require slightly different fields to process the transaction correctly.

In order to process an e-comm item, you also need to create an e-comm confirmation page element. In other words, each e-commerce field item needs a corresponding e-commerce confirmation page element!

Starting with Build 693 it is now easier to create Shopping Cart like applications within RackForms. This is in part possible because the Label field now supports tokens, as well as a sample job being created to show some tricks located at:

\RackForms\goodies\Sample Jobs\E-Commerce\basic-shopping-cart.xml

Using this job as a guide should give you a good handle on what's needed to create your own shopping cart solution.

Options/Properties

Basic Attributes

HTML 5 Type (text input fields only)

This field, which default to text, allows us to set specific input type values for this field. At the most basic level, setting a type will enable browser based validation, and possibly create extra input controls for the field.

Browser Validation:

While we have a full validation system available to us in RackForms, in recent years browser vendors have taken steps to implement some of the most common validation steps within the browser itself. The Email field is a good example of this, when set the browser will check the validity of the input against common email patterns. If this field is found invalid the browser automatically applies a OS/Browser specific style to the invalid field.

Extra Input Controls

Generally speaking, adding extra input controls such as calendars and color pickers meant downloading and implementing a third party JavaScript solution. With the new HTML 5 controls this work is now implemented directly in the browser. A good example of this is the Date type, when set in some browsers a calendar item appears next to the field.

Considerations

It's very important to note these controls and their implementations vary wildly across browsers and OS's, and even then, not consistently across the same browser over different OS's.

The good news is if an input type isn't supported the browser simply renders a standard text box.

Label

Type the text you want to appear above or to the side of the form element. This is also the value of the text displayed in the RackForms Result Browser and Email messages.

The label field supports local PHP variables if they are wrapped in PHP tags and echo'd out as: <?php echo $val; ?>

Please note that only local variables are supported, $_SESSION variables must be bound to local variables in the PHP Top Code or PHP Head Code section first.

As of Build 693 the functionality of this item has been expanded to support dynamic tokens for E-Commerce items. Please see the in-editor tooltip (located just above this field), for specifics.

As of Build 701, this field now also accepts the standard RackForms 2 token set for form field labels. Please see the in-app tooltip for exact values to use.

As of Build 705, this field now accepts the standard RackForms 2 token set for Section/Headline Text and Body Copy elements. That is, we used to only be able to use the @{value} token, as can now use F{}, S{} and so on.

The 'new' tokens will, by default, transform linebreaks into HTML br tags. This is very handy when we want to display a text area to a user where such line breaks have been added. This ensures the typed value matches, as closely as possible, the display.

Also in Build 705 is the 'raw' field token: FR{field_name}. This token was created because by default, when we use a F{} token for say, text1, we are actually creating the following code:

Tail TextTail Text allows us to add text just after a text field element. Generally speaking this is useful for adding definitions to the data being entered, such as lbs, psi, and so on.

The content in this item is enclosed in a span with a class of tailtext, and is thus best used for small images and blocks of simple text.

By default the text container is defined in formpage.css with a rule of:

.tailtext { font-size: 75%; }

This means the text will usually be smaller than the label field by a small amount. However, we can certainly add our own html and inline styles to this element for a more custom look.

Name/Value

This element is set by RackForms automatically, though it is recommended to change this value if you decide to display Javascript validation messages, as the 'identifying' text of the error is the value of this field.

This value is displayed by default if no 'Label' attribute is assigned to the element. For technical users, this element name is in fact the same as the Name/Value html form attribute of this element.

You will also notice that if you change the name of this field, the id attribute to the immediate right of this element also updates with the same value. This is because in most cases you should keep the same value for both elements--however, you can use a different value, simply type in the id field separately.

Naming Convention Note: The only valid punctuation for the Name/Value and id fields is the underscore _. Use of any other character will cause the form to fail.

This is an incredibly important item for the Email+ and SQL+ Modules. The value you type into this box is what you will use to retrieve the dynamic value of the field at runtime. This element is often referred to as {field_id} in the documentation of those modules

id

By default is assigned the same value as the Name/Value element, though you can change this to a more field specific value. Not necessary for most applications. For technical users, this is the id attribute of the field item.

Wrapper Class Name

Every field element in RackForms is wrapped in either a LI or DIV element for Sortable or Free Form page types, respectively. When you place a value in this box it becomes the class="" attribute for that wrapper. Because a wrapper encompass both the input element and wrapper, you can use this value to show and hide sections of your form.

Helper Text

This text displays on the bottom of the field item. By default, the text is 7pt and light grey #888888. You can change the elements color in the RackForms editor, but the font size must be changed in the jobs formpage.css file.

Default Value[Only used with text element such as text box and text area]
Any pre-assigned values for this element should be typed into this box. At run-time this value is automatically populated into the field item.

Please note this area can contain a mix of tokens and standard text. This means we can have:

F{name}-entry

...and any non-token characters, in this case: -entry, will be included as well. Pay special attention to spaces, as they will be rendered along with any tokens!

There are a few special considerations with using PHP variables in this field:

1. Always wrap the full variable in braces.

2. You cannot execute functions in this block, only variables.

3. $_SESSION variables must use single quotes as in {$_SESSION['variable']}, not double quotes as in {$_SESSION["variable"]}

4. All variables are passed through htmlentities($variable, ENT_COMPAT), which means any double quotes are turned into &quot;

Placeholder Text

This value appear within a text box field item.

Tail Text

This value appears just after the form field input element of a text field item.

Field Width

In pixels units, the height of the field item. Default of 140 for text boxes and 200 for text areas.

Please note that File Items do not use pixels but rather the html size="" attribute. This means we want to be careful when changing these values, as inputting a value that makes sense for text boxes, such as 200, will be massive for file items.

Field Height

The height of the field, in pixels.

Apply To All Items - Both Field Width and Field Height have this convenience shortcut that when clicked, will make all other items on that form page the same width or height as the current item. This is very handy when we want to quickly apply the same look to all elements on that page.

* Please be aware that at this time the Display Field Count validation property has no effect on text areas that use TinyMCE. You can still set a maximum character count, but this value will only be validated at the time of the forms submission via PHP, not JavaScript.

** You can only use 1 style of TinyMCE text editor per form page. The text area that comes first in the form will determine which TinyMCE text editor configuration is used.

Readonly

When set this field can contain a value and will submit data when the user clicks the submit button, but its value cannot be changed
by the user. Please note this value can still be changed by manually editing the field in a JavaScript/Web debugger,
so please be sure to not place sensitive information that cannot be changed in this field.

Field Enabled

When Yes the field accepts values and input from the user. When set to No the field ignores
user input, and its value is not submitted with the form data.

Extra Attribute(s), JS, Event Code, etc

Although similar to a submit button, a button has an html type of 'button', not type=submit, which means when this element is clicked on,
your form will not be submitted, but rather you must supply the event to occur.

A common use of this type of element would be to attach a history command such as onclick="history.back()", and then use it on a multi-form page to make navigating back one page easier than using text links.

Add code to your field item by typing it into this box. Code can be JavaScript event code such as:

What's important to note is that the code you create here effects the field element, not the container it sits in. To edit the field container, you need to reference the field name prefixed with 'fb_fld-', as in a text box with an ID of text1 would be referenced like:
fb_fld-text1

Extra Field Style Attributes

This field allows us to define extra style attributes for our form elements such as:

color:#cdcdcd;

It's important to consider that RackForms also applies style data, traditionally as:

In short, font properties and height/width are handled automatically via editor properties. Thus, this field is for specifying extra style attributes not handled by the RackForms UI.

This is especially useful for Bucket items, where any style data we apply will greatly enhance the look of a standard bucket, which by default has only size and position styles applied.

Conditional Processing

Conditional Processing OverviewThe conditional processing capabilities of RackForms can be broken into two main categories:

Guided - In this mode we use all fields except the Custom Conditional Field Statement text area. That is to say, we use the RackForms user interface to select one element or wrapper to apply dynamic logic to. This could be considered the "easy" mode, in that we write no code to perform our dynamic logic. We simply tell RackForms the properties of the interaction we want and RackForms does the rest.

Custom Conditional Code - In this mode we use the Event Trigger property say which event calls the code we define in the Custom Conditional Field Statement box. This could be considered the more powerful but advanced mode, in that we write our own dynamic logic.

Of course with power comes flexibility, as in this mode we can apply any type of complex logic we need to get the job done. In particular though this code-centric mode is required if and when we want to apply dynamic logic to more than one field item or wrapper class item (items that have the same Wrapper Class property defined).

To be clear: if we only need to apply dynamic logic to one item or wrapper class we use the guided mode. If we need to have more than one item show or hide, we use the custom code mode.

Important NoteStarting with Build 759 we can use the Guided mode controls to apply conditional logic to items on a different page than the one the affecting form field is on.

Please note however, that this capability does not apply to Custom Conditional Code logic, only guided ones. That is, any custom conditional code we write only applies to items on the same page.

Field Initially Visible?

Determines if the form element is visible when the page first loads. Please note that this logic always resets on page load, that is, if a user goes back one page where an element was previously shown it will be invisible again
.

This Form Field...

This field and the next allows us to create a condition on the visibility of the field. We enter the Name/Value of a form field in this box, and in the next, the value we check against. If the value matches, we show the field. Please note this only works as a method to show a field, not hide. That is, we still uncheck the Field initially Visible to hide the field, these options simply allow us to show the field based on a condition from another form field. Please note this logic works across pages.

Has This Value...

The value we check to determine a fields visibility. This must exactly match the value the form field will contain. This field is also dynamic, which means we can use standard RackForms tokens to check against a dynamic value at run-time.

Easy Toggle?

Checking this box means RackForms will automatically handle the logic needed to perform the opposite action you set in Then... and If This Field Is: properties. For example, if you set the action of an item to be 'Show', if the condition needed to make this show action happen is revoked, the opposite action will automatically happen for you. So, if the condition is the text '1' must be set in a text box in order to show a second text field, if this 1 is removed or changed, the second text box will be hidden again.

In general we want to keep this box checked, though if you wanted to force a field to always show after an action then leave it unchecked.

Event Trigger

This is the JavaScript event that will be scanned for and then acted upon if activated. Some events are better than others for the various tasks you have. For example, the onClick event is perfect for Checkboxes, whereas the onKeyUp event is perfect for text boxes where a user needs to enter a specific value. Experiment with these values and have fun!

Caution! You may run into a situation where you build a form that enables the event trigger on a specific field, then remove that field later on without updating the Event Trigger's 'binding' to that element.

If this happens your forms validation will break, along with other potential issues.

The solution is always make sure that when we enable an event trigger for an element, that field exists on the form.

Animation?

While not always needed, if you want you can add animation using Prototype JS to your events. The upside of this is your forms may have a more professional appearance, the downside is the extra bandwidth needed to send the Prototype JS library over the wire to run the animations. However, if you are already using animation or have included the Prototype JS library for other purposes, this bandwidth cost is obviously negated, so animate away!

If This Field Is:

This is the core property of the Conditional Processing logic. In most cases you will only want to show and hide fields if a specific condition is met, this option allows us to set that condition. As with the Event Trigger property, some options only make sense in the proper context. For example, the top Value Comparison grouping is best served in combination with text and select fields, whereas the Field State options of Checked and Unchecked only make sense for checkboxes.

It is also important to note that RackForms will attempt to cast comparison values set as INT and FLOAT values to their respective native types.

This Value...

When we set the If This Field is property, with the exception of the two Field State checks of Checked and unchecked, we typically want to compare against some value. It is in this text box that we set that comparison value. RackForms will automatically attempt to detect FLOAT and INT values when testing against GREATER THAN and LESS THAN checks.

Then:

If the condition set in If This Field Is and This Value... passes, this is the action we will perform. Please note that is Easy Toggle? is enabled, we will automatically perform the opposite when the check fails.

This Field Or...

When we set an event, comparison, and action, the last step is to tell RackForms which fields to act upon. It is in this field and is close relative, This Wrapper Class, that we set this field or fields.

As you build your form RackForms will automatically track the Name/Value properties of the elements on that form page and then present them to you in list format in this field. Thus, all eligible form fields will be displayed in this select item, the one you select will become the field acted upon.

Finally, any elements that are set to hidden on page load are tagged with a [H], which makes it easy in many cases to see which items you may need to work with.

Note that items from other pages will be shown as well, they are grouped with an entry of the page name they below too.

This Wrapper Class

Similar to the This Field Or... property, with the exception that instead of single field we can act upon all elements with the same Wrapper Class attribute. This makes it very easy to show and hide large portions of content with one action, perfect for address fields and the like.

Conditional Field Statement

Although RackForms tires to automate as much of the show/hide process as possible, their will be times when you need to have more complex logic.
When this is the case, we can use the simple RackForms API to create custom logic.

The bulk of this logic will be derived from a JavaScript object called fbc. This object is defined in:

/rackforms-root/app/movefiles/conditional.js

This file is exported into the root of all RackForms jobs.

The basic usage of this object will depend on what action you want to perform. Their are 4 methods you need to know about:

Simple enough--But it is important to understand that at the page code level RackForms creates two distinct but related items.

The first is the event trigger which is placed inline with your form element. Please be aware the event used is not created automatically, you need to select one from the Event Trigger select item.

Thus, if we select the onKeyUp event RackForms will place this code inline with your element:

onkeyup="fb_dyn_text1(event, this.value, this)"

Notice we have three arguments. This is important because the inline method call is directly tied to the second main element RackForms creates for you, which is a script tag with that methods definition.

As you may now see, this method body is the code you create in the Custom Conditional Field Statement text area. The reason why it is wrapped in the method is to that you do not need to worry about creating or gathering the event, in_value, and elt parameters.

Thus, the last bit of knowledge to convey is that these parameters, event, in_value, and elt, can be used in any way you need in your Custom Conditional Code. Most of the time you will only need the in_value parameter for your logic, but please notice you must pass event to the fbc functions no matter what.

Custom Code Hints and Tricks

Place hide field calls at the top of the code section.

One common trick to employ to keep your code block clean is to place all hide calls at the top of your code block. This eliminates the need for most if/else blocks, and means we only need to set conditions to show elements. The reason this works is hiding and showing elements is so fast, that even if an item is shown and will not be hidden by the code, the hide call and subsequent show happens to fast to be perceived.

Be careful with integer values.

Integer and number values in JavaScript can often cause problems, as they may be interpreted as strings, and vice versa. Thus, when working with number values always pass them through isNaN (is not a number), and parseInt/float. For example, the following code will check to make sure k is a number, and is also an int.

That is, we call fbc.animationDone(elt), then in that function, define the actions to take place.

The elt parameter is the object that called the animation, that is, is the object which reacted to the event.

Please note this event is fired for every animation that plays. Thus, if we've used this in the content of a Wrapper Class with say, 5 elements, this function is called 5 times.

Important RackForms Note: In RackForms 2 the in_value parameter was defined as just value. This caused code conflicts however, and was thus renamed to the present value. If importing any RackForms 2 jobs into RackForms, any custom code will need to be updated to use the new value.

Field Style Properties

Element z-index

New to Build 697, this feature allows us to set the z-index of most items. This property is reflected in the editor as well, making positioning items much more streamlines than in previous versions.

By default most items, with the exception of calendar fields, have a base index of 1. This means so long as your form fields to not overlap you will not need to set this property. However, some fields, such as images or those with popup's (like the calendar field), benefit from setting a different layering order.

Text Color

Click into the box to load the color selector. Drag your cursor over the saturation in the main box to select the color intensity, or drag the hue slider to change color.

Font Size(px)

Type a number in this box to change the font size of the element.

Label Font Weight

New to Build 685, this option lets us set the font weight of the forms field label or main text block.

Element Position

Use this control to position an element to the right of the page, as opposed to the default left.

Label Position

Has no effect for this field. Might be implemented in later versions.

E-Commerce Item Options

Transaction Type

Transaction type is the type of interaction we provide to the payment gateway.
The most basic distinction would be between say, a one time payment and a donation.

In RackForms wee Can Choose From:

• One Time Payment
• Subscription
• Donation
• Shopping Cart Item

As a general rule, only PayPal and Stripe support the second, third and fourth options, though this may change in the future.

Setting this field tells RackForms how to crate the payment gateway form, so make sure it is set correctly for the product you're setting up!

Thus, if you have a simple item you want to sell, you would select One Time Payment. If you want to allow your users to select more than one item and have RackForms group them together on the PayPal payment page, select Shopping Cart Item.

Please note that when you select your Transaction Type you also need to be mindful of the Confirmation Pages' E-Commerce item options as well. This is because not all combinations will work. For example, as of right now only PayPal supports the Shopping Cart Item Transaction type.

A note on Shopping cart items
Shopping cart items are a special case in RackForms that allow us to let the users select any number of items or products from the form page, then have PayPal or Stripe batch them together into one lump payment item on the payment page. The limitation to this method is the items in PayPal are not itemized, but the benefit is that created a rather simple form of shopping cart.

However, in Stripe items are full itemized and listed on a payment page. Thus, it is highly recommended to use Stripe for almost all of your payment processing needs.

The key point though is that in order for this shopping cart method to work we need to set the Transaction type to Shopping Cart Item in this field, and select Shopping Cart Items from the Process This Field... select item in the E-Commerce delivery module options.

A good way to learn about shopping cart items (for Builds 680 and higher) is to check out the sample job:

\RackForms\goodies\Sample Jobs\E-Comm\paypal-shopping-cart.xml

Currency Type

Sets the currency type of the transaction. If you need a currency type added, please use the contact page to request one!

An important aspect of this field is we want to be sure to select the correct currency, not just the currency symbol. For example, The Australian Dollar and US dollars will not be processed the same by your e-commerce provider!

Transaction Tax Rate

This element sets a transaction wide tax rate. It's important to note this field does not distinguish between items (such as shopping cart items). Thus, we cannot have items that are taxed and those that are not on the same form page.

Please note not all Payment Gateways have implemented this feature. Currently PayPal and Stripe are the only supported payment providers.

Using a Dynamic Tax Rate: This field supports the use of a dynamic tax rate if we supply a SESSION variable as its value. For example, we could add a Code Block element to our form page with the following code:

<?php

$_SESSION['rate'] = 0.8;

?>

Then, our Tax Rate value would simply be that SESSION element as in:

$_SESSION['rate']

Please note the following limitations:

• Only one tax rate can be applied for each form.
• The set tax rate applies to the entire transaction.

Transaction Language

Type in the name of the transaction language used. This is only applicable for PayPal, where you can find a full list of supported languages and countries here. Be sure to use the proper county code, which is, for PayPal, 2 letters.

Require Address?

If checked, the payment gateway will ask the user for their address on the checkout screen. Not needed for some transaction types, such as donations.

Form Field Type

New to Build 680 and expanded in Build 693,
this field allows us to set what he form field element will be. We can select from Radio, Checkbox, and Select items.

Please note that when we select checkbox items we are by default using the shopping cart method, as checkbox items mean that more than one item can be selected per purchase. As only shopping cart items support this method, the two items are complimentary.

Quantity Dropdown

When enabled, displays a drop-down menu next to the e-commerce item. Users can then select between 1 and 30 items.

Important Imitations and notes: Quantity is not supported for all transaction types. Specifically, Stripe is the only payment provider that supports this option for subscription items. If no quantity is supplied, we always default to 1.

Item Options

Short Description - this is the description that the payment gateway will display next to your product.

Price - The price of the transaction. Can be left blank for donations. Do not use punctuation other than a comma and/or decimal.

As of Build 651 this field is dynamic, we can use:

S{session_var_name} to include $_SESSION elements

F{field_item_name} to include Form Field Values.

Thus, we could let the user type in a donation amount on 1 page of your form, and that will be the value used for this element.

We could also create a more complex order form where we keep track of several elements and then create a 'total price' which is used again, as the value for the e-comm item, much like a traditional shopping cart.

Retrieving Price In Your Forms
While we currently do not have a way to retrieve the total price of a transaction, as of Build 700 we can now query the selected price for a specific item using a form field token in the format of:

@{fieldName_price}

That is, the token used for form field items, which in many cases is @{} or F{}, the name of the e-commerce field item, followed by an underscore and the word price.

Extra - Required for some gateways, for example 2Checkout requires this field to include the product_id of your item. Generally not used with PayPal and Google Checkout.

However, as of Build 699, we can now use this field to mark a PayPal shopping cart item as a discount item. We do so by applying a single (-) minus mark to the field.

For Stripe and PayPal, we can use an upper-case S to signify the item as a subscription product.

Subscription Options

Billing Frequency

This field is used in conjunction with Billing Unit to determine how often the customers card is charged. Stripe and PayPal, the two supported platforms for creating subscriptions in RackForms, handle this logic similarly:

Stripe - Stripe defines this logic as: The number of intervals (specified in the interval property) between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.

PayPal - The number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year.

For example, we'd use these values to create a subscription plan that bills once a month:

To Bill Once a Month:

Billing Frequency

Billing Unit

Stripe

1

Month

PayPal

1

Month

To Bill Once a Week:

Billing Frequency

Billing Unit

Stripe

1

Week

PayPal

1

Week

To Bill Twice a Month:

Billing Frequency

Billing Unit

Stripe

2

Week

PayPal

2

Week

To Bill Once Every Three Months:

Billing Frequency

Billing Unit

Stripe

3

Month

PayPal

3

Month

As you can see the logic is pretty strait forward, though it's important to be aware of the values used so as to not create an invalid billing profile.

Billing Unit

PayPal and Stripe handle this value slightly differently, though the intent is the same: this is the unit of measure for the billing cycle.

Stripe call this the subscription interval, and accepts week, month, or year.

PayPal calls this the subscription BILLINGPERIOD, and accepts Day, Week, Month, and Year.

As we can see from the tables above, the basic idea is this value represents the units the Billing Frequency is multiplied by to get our final billing interval.

Trial Days

The number of days a trial period lasts.

Trial Unit

This value is hard-coded to Days.

Plan Identifier

This value is required for Stripe, and is used to identify the plan name to Stripe. This value usually takes on a service level, such as Standard, Pro, or Enterprise.

Customer Identifier

Required for Stripe and PayPal, this value represents the label above the customer identifier field automatically generated in the billing form. The default value of 'Your Email Address' is almost always the right choice, as this will provide a semi-unique identifier for the user.

So many features, So little time

Our story

Back in 2007 we had a simple idea: make building web forms fun and easy, and most importantly available to as many users as possible. Years later we're still going strong and though the software has grown by leaps and bounds, still find building forms as easy as we had hoped.