Thank you for purchasing jQuery Price Calculator Pro. If you have any questions that are beyond the scope of this help file, please feel free to contact me through my website (http://benmartinstudios.com.au/) or directly by email.
jQuery Price Calculator Pro (PCP) is a clean, simple, progressive price calculator script. PCP allows you to add a running total to an order form, giving your customers a precise idea of how much an item's configuration will cost. It also allows you to show an itemized summary, so that the customer can get a quick overview of their order before they submit it.
Supported Inputs:
PCP is very customizable. You can:
jQuery Price Calculator Pro supports all major browsers, including: IE7, IE8, IE9+, Firefox, Chrome, Safari 4-5+, Opera 10+. jQuery Price Calculator Pro has not been tested in IE6 as it is currently unsupported.
Check out the example files (found in app/examples/) for some sample implementations of jQuery Price Calculator Pro.
The HTML is simple, all you need to do is create a form with various inputs. Each input that has a cost must have a data-cost attribute set (otherwise it will have no cost). Examples are shown below:
<p><select name="delivery"> <option selected="selected" value="pickup" data-cost="0">Pick Up</option> <option value="cbd" data-cost="1.00">CBD</option> <option value="outskirts" data-cost="2.50">Outskirts</option> </select></p> <p><label><input type="checkbox" name="extras[]" value="spicy-dip" data-cost="1.30"/> Spicy Chip Dip </label></p>
It is recommended to wrap each <input> tag with a label (in the following manner: <label><input ... >Label Text</label>).
If data-ignore="true", then the input will be ignored when component prices are shown, and also when the total price is calculated.
data-default: (optional) By default, the value that the input controls will always show up in the item summary, even if the user has not selected a value. When the input is at the value that this attribute is set to, it will be ignored by the item summary (if it is enabled). E.g. if an input has a starting value of 0, and you do not wish for it to show up in the item summary unless the user changes it from 0, then set data-default="0". This attribute is redundant for checkboxes and radio buttons, and is really only applicable to drop downs (see the following paragraph) and jQuery UI sliders.
If the element is a drop down (select), then set the data-default="true" on the default option. In the following example, if the first option is selected (as it is by default), this element will be ignored in the item summary.
<p><select name="delivery"> <option selected="selected" value="none" data-cost="0" data-default="true"> -- Please Choose -- </option> <option value="pickup" data-cost="0">Pick Up</option> <option value="cbd" data-cost="1.00">CBD</option> <option value="outskirts" data-cost="2.50">Outskirts</option> </select></p>
To add a quantity field, you must insert an input into the HTML code with a data-quantity attribute. Set the attribute to a comma separated list of the name attributes of each element that the quantity applies to. For example:
<p><label><input type="radio" data-cost="1" value="RB #1" name="f_1" /> RB #1</label> <span class="staticPrice"><span class="hypen"> - </span>$1 AUD</span></p> <p><label><input type="radio" data-cost="2" value="RB #2" name="f_1" checked="checked"/> RB #2</label> <span class="staticPrice"><span class="hypen"> - </span>$2 AUD</span></p> <p><label><input type="radio" data-cost="3" value="RB #3" name="f_1" /> RB #3</label> <span class="staticPrice"><span class="hypen"> - </span>$3 AUD</span></p> <p><label><input type="checkbox" data-cost="7" value="CB #3" name="f_2[]" /> CB #3</label> <span class="staticPrice"><span class="hypen"> - </span>$7 AUD</span></p> <p><label><input type="checkbox" data-cost="6" value="CB #2" name="f_2[]" checked="checked"/> CB #2</label> <span class="staticPrice"><span class="hypen"> - </span>$6 AUD</span></p> <p><label><input type="checkbox" data-cost="5" value="CB #1" name="f_2[]" checked="checked"/> CB #1</label> <span class="staticPrice"><span class="hypen"> - </span>$5 AUD</span></p> <p>CB+RB Quantity: <input type="text" name="q_1" value="" data-quantity="f_2[],f_1"/></p>
In the previous example, the quantity field will apply to the radio button group with the name attribute of f_1, and the checkbox group with the name attribute of f_2[].
Implementing a jQuery Numeric Spinner into jQuery Price Calculator Pro is simple. You don't even have to initialize the spinner - PCP does it all for you! All you need is a HTML5 number input, with a data-spinner attribute set to true, and jQuery PCP will take care of the rest. In newer browsers, the native spinner is used instead of the jQuery plugin. Take a look at the following example:
|
|
In the HTML for the input, you need the following attributes.
No other markup is required! It really is as simple as that!
Implementing a jQuery Numeric Spinner into jQuery Price Calculator Pro is simple. You don't even have to initialize the spinner - PCP does it all for you! All you need is a HTML5 number input, with a data-spinner attribute set to true, and jQuery PCP will take care of the rest. In newer browsers, the native spinner is used instead of the jQuery plugin. Take a look at the following example:
|
|
In the HTML for the input, you need the following attributes.
No other markup is required! It really is as simple as that!
The only difference between whether an input is a slider or a spinner is that a spinner has data-spinner="true", and a slider has data-slider="true"
To initialize jQuery Price Calculator Pro, jQuery must be loaded. It is recommended to load jQuery from a CDN. To find out more, check out the CDN section on the jQuery website.
|
|
Required Files
jQuery Price Calculator Pro requires the following files to function:
CSS:
JS:
jQuery UI Slider *new in v1.1!
jQuery UI Sliders require the following additionalfiles:
CSS:
JS:
jQuery Numeric Spinners require the following additional files:
CSS:
JS:
You must create an instance of jQuery Price Calculator Pro the <form> tag with which you wish to use it, as follows:
|
|
To see how to customize jQuery Price Calculator Pro, view the following section.
The bPrice function accepts a single (and optional) parameter, an object containing all of the customization settings. To customize jQuery Price Calculator Pro, do so as follows:
<script type="text/javascript">
$('#price-calculator-pro').bPrice({
floatSub: false,
subAlign: 'right',
...
});
</script>
None of the following options are required, they are all optional.
I endeavoured to make the property names as self-explanatory as possible. I welcome any suggestions on how to improve this and/or clarify any possible confusion.
| Property | Type | Default | Description |
| floatSub | boolean | true | Whether or not to float box displaying the running total when the page is scrolled (true will force the running total to always be in view). |
|
subSelector *new in v1.4 |
string | empty string | A jQuery selector of the element in which the summary/total fields are inserted into. Leave this blank for the default functionality. |
| subAlign | boolean | 'right' |
The alignment of the running total box. Accepts either:
|
| showPrices | boolean | true | Whether to show the individual component prices (true) or not (false). |
| showPricesOption | boolean | true | If enabled, this option gives the user the option of showing or hiding the individual component prices. |
| showZeroAs | string | empty string | If a component price is zero (0), this option allows you to change the price text. I.E. instead of showing $0 next to an item, you could change it to something like 'included' or '*free*'. If you wish for the component price to be a formatted zero, set this to '0'. Alternatively, if you want zero prices to be hidden leave this as an empty string (default). |
| signBefore | string | '$' | Text to display immediately preceding any price. E.G. if the price is 5, and you want $5 USD to be displayed, set signBefore to '$'. |
| signAfter | string | ' AUD' | Text to display immediately following any price. E.G. if the price is 5, and you want $5 USD to be displayed, set signAfter to ' USD'. |
| pricesFadeTime | integer | 600 | The amount of time taken when fading the prices in/out. Only applies if showPricesOption is true. |
| itemized | boolean | false | If true, an itemized summary of each selected item will be shown under the running total. |
|
items *changed in v1.4 |
array | [] |
This array contains a list of labels for each item in the itemized summary. The key of each entry must be set to the name attribute of the control (if aname attribute is not set, the id is used). For example, in the following array, the label of "Main" for the form element with a name of main.
var items = new Array(); Check out any of the examples in app/examples to see how this option is used. Changed in v1.4: If you wish to omit an item from the itemized summary, simply leave it's corresponding entry out of the items array. For example, to omit the item labeled Drink (the element with the name attribute of drink), omit the following line from the above example: items['drink'] = 'Drink'; |
| decimalSep | string | '.' | What to use as a decimal place separator (e.g. you could use a comma instead of a full stop/period). |
|
thousandsSep *new in v1.4 |
string | ',' | What to use as a thousand place separator (e.g. you could use a full stop/period instead of a comma). |
| emptySummaryText | string | <p>Please configure your order...</p> | The text to show if the summary is empty. This option is only applicable if itemized is set to true. |
|
pricesOverPeriod |
array | [] |
This option can be used if you wish to show prices over certain periods; for example, you could use this to show the total cost split over 12 months. This value is an array of objects for each "cost split". Each entry must be an object with the following format: { divider: The amount the total price should be divided by (number) title: The title of the split (string) suffix: Suffix to be appended to the price (string) } Checkout line 130-138 of the example in app/examples/prices-over-time/ for example usage of this feature |
Take a look at the file css/jquery-price-calculator-pro.css for examples of how to style the jQuery Price Calculator Pro - it is really straight forward. There are some extra styles in css/jquery-order-form.css, which are not required, but may improve the look of your form. All of the example files utilize Twitter Bootstrap for the basis of their styling.
The following is a list of sources that I have used in the development of this plugin.
Thanks again for purchasing my plugin! If you require any technical support with it, feel free to contact me via email or through my website (http://benmartinstudios.com.au/) and I will do my best to help you out. You can also post your question in the comments on CodeCanyon.
I welcome any feedback on the ease of use of both jQuery Price Calculator Pro itself and also this documentation file. I also encourage feature suggestions for future releases.
I'd love to see your implementations of the jQuery Price Calculator Pro, and I hope you enjoy using it!
Ben.