Cart.js
Description of templates/common/js/cart.js
library usage to integrate with HostBill Cart APIÂ
Setup
To setup cart connection you need to call HBCart.init(cartObjct, settings)
- cartObjct - either an empty object or previously saved HBCart.cart object
- settings - object with settings required to connect your page with HostBill cart
$(function () { HBCart.init({}, { categoryId: 1, url: 'http://your.hostbill.url/', language: 'English' }) })
Settings
- url - url to your HostBill installation
- categoryId - HostBill orderpage ID, optional if productId is used
- productId - HostBill product ID, optional if you use categoryId and want to allow product selection.
- language - initial language, parameter should be the same as language names in HostBill
- currency - initial currency, will work only for new customers
- params - other parameters that you want to send when initialling cart
- requestBodyClass - class set to body when ajaxx requests are sent
Cart object
- HBCart.cart - all data used in cart
- HBCart.cart.summary - pricing details
- HBCart.cart.summary.recurring - list of recurring prices
- HBCart.cart.summary.tax - list of applied taxes
- HBCart.cart.product - selected product details
- HBCart.cart.product.config - items required to create product configuration
- HBCart.cart.category - selected category details
- HBCart.cart.category.products - products in selected category
- HBCart.cart.categories - other categories that are available in HostBill
- HBCart.cart.currency - selected currency
- HBCart.cart.currencies - available currencies in HostBill. This will show up only for not logged in clients.
- HBCart.cart.client - client object, only basic details [id, firstname, lastname, email]
- HBCart.cart.client.items - list of client fields, with values for logged in clients
- HBCart.cart.payment - list of available payment gateways
- HBCart.cart.validated - true/false, indicates if order can be placed with current setup
- HBCart.cart.errors - list of last errors from HostBill server
- HBCart.cart.info - list of last messages from HostBill server
Events
Triggered on window.document object
- cart.ready - called when HBCart.cart object is loaded
- cart.updated - called after HBCart.cart is refreshed by ajax
- cart.errors - event with error messages from HostBill function(event, errors){}
- cart.info - event with info messages from HostBill function(event, infos){}
- cart.requestStarted - called when first ajax request is sent to HostBill
- cart.requestComplete - called when all ajax request are complected
$(document).on('cart.ready', function(){ //render cart })
API
All methods listed below will refresh HBCart.cart object.
Each of those also returns a object that can be used to bind callback functions, example:
- options - optional, can also be used to attach ajax callback eg. {success: function(){}}
- options.updateCart - can be used to prevent HBCart.cart update if set to false
HBCart.Api.setProduct(id).done(function(cart){ //re-render configuration })
Methods
- HBCart.Api.getCart(options = {})
- refresh cart data
- HBCart.Api.setDomain(hostname: string, options = {})
- updates product domain name to provided string
- HBCart.Api.setCycle(cycle: string, options = {})
- updates product cycle, cycles as single letter [m - monthly, a - annually, etc.]
- list of available cycles provided in HBCart.cart.product object
- HBCart.Api.setProduct(id: number, options = {})
- changes product to provided id
- HBCart.Api.pushForms(options)
- sends form configuration to server based on what is set in cart object
- HBCart.Api.setForm(id: number, value, options = {})
- send to update form value
- id points to form id
- value should be either a number for qty/sliders, item id for dropdowns or an object {$itemid:1} for checkbox forms
- HBCart.Api.resetForms(options = {})
- will set default values for all forms
- HBCart.Api.resetForm(id: number, options = {})
- will reset selected form id
- HBCart.Api.pushAddon(options = {})
- HBCart.Api.addAddon(id: number, cycle: string, options = {})
- HBCart.Api.removeAddon(id: number, options = {})
- HBCart.Api.clearAddons(options = {})
- HBCart.Api.pushSubproducts(options = {})
- HBCart.Api.addSubproduct(id: number, cycle: string, options = {})
- HBCart.Api.removeSubproduct(id: number, options = {})
- HBCart.Api.clearSubproducts(options = {})
- HBCart.Api.pushConfig(options = {})
- sends forms, addons, subproducts and product configuration to server
- HBCart.Api.clearConfig(options = {})
- reset product configuration, forms, addons and subproducts
- HBCart.Api.addCoupon(code: string, options = {})
- HBCart.Api.removeCoupon(options = {})
- HBCart.Api.setCurrency(cur = 0, options = {})
- HBCart.Api.setLanguage(lang = 'english', options = {})
- HBCart.Api.setTaxRegion(country: string, region: string, options = {})
- used to update tax values, before client has signed-up
- HBCart.Api.signup(form, options = {})
- used to create client account, forms sent here should include fields defined in HBCart.cart.client.items
- HBCart.Api.login(email: string, password: string, options = {})
- login client to HostBill
- HBCart.Api.logout(options = {})
- HBCart.Api.setupOrder(options = {})
- validates order configuration and saves it to session, required before submitOrder
- HBCart.Api.submitOrder(gateway, note = '', tos = false, options = {})
- used to submit order after it was validated,
- gateway - payment gateway id
- note - optional order note
- tos - if terms of service are enabled in hostbill it has to be set to true
- HBCart.Api.clearOrderId()
- will remove order information from cart object, required if you want to use submitOrder one more time