Cart.js

Owned by Hostbill Support
Last updated: Mar 17, 2023 by HostBill
3 min read

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