ecommerce

x5engine.cart.ecommerce

Kind: global class
Summary: This class allows you to manage the entire JavaScript E-Commerce Cart of WebSite X5.
For example, you can add, remove or update the products in the cart, get the total amount of an order and save it to the database.

Although the class has a contructor and can be instantiated by you, you may want to get the WSX5 global ecommerce instance stored in `x5engine.cart.manager`.

If you need more info about the ecommerce data structure, you should take a look to the x5cart.js
created by WebSite X5 and stored in the site's "cart" folder.

new ecommerce(settings)

Instantiate a new E-Commerce manager passing half-a-ton of parameters.

Param Type Description
settings Object
settings.indexpage String The cart page url relative to the site base url
settings.vat Number The default VAT
settings.coupon Boolean true to enable the coupons
settings.vattype String The type of VAT to use (none
settings.currency String The currency symbol
settings.currency_id String The currency ID
settings.order_no_format String How to format the order number
settings.form_autocomplete Boolean Save form data in a cookie?
settings.form_validation String How to validate the user data forms
settings.showShipmentFields Boolean Must the cart show the shipment fields?
settings.continue_shopping_page String The default continue shopping page
settings.remove_from_cart_icon String Icon used to remove the goods from the cart
settings.add_to_cart_icon String Icon used to add the goods to the cart
settings.minimumAmount Number Minimum order amount (goods only)
settings.currencies Array Currencies available for automatic conversion (not enabled yet)
settings.cartCookie String The name of the cookie used to store the order data
settings.formCookie String The name of the cookie used to store the user's form data
settings.products Object // Array of products in stock (see the product class)
settings.shippings Object // Array of available shippings (see the shipping class)
settings.payments Object // Array of available payments (see the payment class)

Example 

var myEcommerce = new x5engine.cart.ecommerce({});

.formatCurrency(n, format, currency) ⇒ String

Format a number using the provided currency format.
The format parameter accepts the following chars:
- [C] to set the currency position
- @ to indicate a mandatory number in the decimal section
- # to indicate a optional number in the decimal or integer section
- The first comma or period is used to divide 10^3 groups
- The second comma or period is used to divide decimal part from the integer part

Kind: instance method of ecommerce
Returns: String - The formatted string

Param Type Description
n Number The number to format
format String The format to be applied
currency String String to use as currency

Example 

formatCurrency( 10.243, [C]#,###.@@, '€'); // Outputs €10.24

Example 

formatCurrency( 1210.243, [C]#,###.@@, '€'); // Outputs €1,210.24

Example 

formatCurrency( 1210.243, [C]#,###, '€'); // Outputs €1,210

.settings(newSetting) ⇒ Object

Provide the current cart settings

Kind: instance method of ecommerce

Param Type Description
newSetting Object JSON with the new settings

.form() ⇒ Object

Provide the form fields set in the cart settings

Kind: instance method of ecommerce

.add(productid, quantity, option, suboption, forceQuantity) ⇒ String

Add a product to the cart

Kind: instance method of ecommerce
Returns: String - The hash code useful to get/update/remove this product from the cart

Param Type Description
productid String The product id
quantity Number The product quantity
option String The option id
suboption Number The suboption id
forceQuantity Boolean If true, the set quantity is not added to the current one but it replaces the actual

.remove(hash) ⇒ Boolean

Remove an element from the cart

Kind: instance method of ecommerce
Returns: Boolean - True if the element was removed correctly

Param Type Description
hash String The hash id of the element in the cart

.update(hash, quantity, option, suboption) ⇒ String

Update the quantity for a gived product

Kind: instance method of ecommerce
Returns: String - The new hash of the product, useful to get/update/remove this product from the cart

Param Type Description
hash String The product hash
quantity Number The quantity
option String The option
suboption Number The suboption

.cart() ⇒ Object

List the elements in the cart

Kind: instance method of ecommerce

.count(boolean) ⇒ Number

Return the number of goods in the cart

Kind: instance method of ecommerce

Param Description
boolean deep True to keep quantity of each product in account

.category(categoryId) ⇒ Object

Return the products of a specified category.

Kind: instance method of ecommerce

Param Type Description
categoryId String The category id

.store(productId) ⇒ Object

Provide the information about the products in the store or a single product in the store

Kind: instance method of ecommerce
Returns: Object - The product data

Param Type Description
productId String The id of the searched product. Leave this empty to get the entire list of products.

.shippings() ⇒ Object

Provide a list of the available shippings

Kind: instance method of ecommerce

.shippingsCount() ⇒ Number

Provide the count of available shipping options

Kind: instance method of ecommerce

.payments() ⇒ Object

Provide a list of the available payments

Kind: instance method of ecommerce

.paymentsCount() ⇒ Number

Provide the count of available payment options

Kind: instance method of ecommerce

.payment(id, save) ⇒ Object

Get or set the payment method

Kind: instance method of ecommerce
Returns: Object - The current payment istance

Param Type Description
id String The payment id
save Boolean True to save the cart

.shipping(id, save) ⇒ Object

Set the shipping

Kind: instance method of ecommerce
Returns: Object - The current shipping istance

Param Type Description
id String The shipping id
save Boolean True to save the cart

.userInvoiceData(data, save) ⇒ Object

Set the user invoice data

Kind: instance method of ecommerce
Returns: Object - The invoice data

Param Type Description
data Object The invoice data
save Boolean True to save the cart

.userShippingData(data, save) ⇒ Object

Set the user shipping data

Kind: instance method of ecommerce
Returns: Object - The shipping data

Param Type Description
data Object The shipping data
save Boolean True to save the cart

.vat() ⇒ Number

Provide the total VAT applied on the cart

Kind: instance method of ecommerce

.fullPrice(includeVat) ⇒ Number

Provide the total price of the order without discounts.

Kind: instance method of ecommerce

Param Type Description
includeVat Boolean True to include the VAT

.price(includeVat) ⇒ Number

Provide the total price of the order.

Kind: instance method of ecommerce

Param Type Description
includeVat Boolean True to include the VAT

.paymentPrice(paymentid, includeVat, full) ⇒ Number

Get the payment price basing on the current cart contents

Kind: instance method of ecommerce

Param Type Description
paymentid String The payment ID string
includeVat Boolean Include VAT or not?
full Boolean Full price or discounted

.paymentVat(paymentid, full) ⇒ Number

Get the payment VAT basing on the current cart contents

Kind: instance method of ecommerce

Param Type Description
paymentid String
full Boolean Full price or discounted

.goodsFullPrice(includeVat) ⇒ Number

Provide the total amount of the goods in the cart without discounts

Kind: instance method of ecommerce

Param Type Description
includeVat Boolean True to include the VAT

.goodsPrice(includeVat) ⇒ Number

Provide the total amount of the goods in the cart

Kind: instance method of ecommerce

Param Type Description
includeVat Boolean True to include the VAT

.goodsWeight() ⇒ Number

Provide the total weight of the goods in the cart

Kind: instance method of ecommerce

.goodsVat() ⇒ Number

Provide the total VAT applied on the products

Kind: instance method of ecommerce

.coupon(coupon, save, callback) ⇒ Boolean

Apply a coupon code

Kind: instance method of ecommerce

Param Type Description
coupon String The coupon code
save Boolean Set to true to save the cart after setting the value
callback function Execute this when the coupon is correctly loaded. It's called passing _coupon as parameter

.canApplyCoupon() ⇒ Boolean

Return true if the user can apply a coupon on the current products in the cart or on the cart itself

Kind: instance method of ecommerce

.canSetOrder() ⇒ Object

Provide info about the actual cart status.

Kind: instance method of ecommerce
Returns: Object - { 'success': true|false, 'message': '' }

.isSetUserData() ⇒ Boolean

Return true in case the user data is correctly set

Kind: instance method of ecommerce

.paymentHTML(options) ⇒ String

Get the payment HTML code.

Each keyword is replaced using the following rules:

  • [PRICE] = The price formatted using the default format
  • [PRICE, MULTIPLIER, FORMAT] = The price formatted with a custom multiplier and format
  • [ORDER_NO] = The order number
  • [ORDER_ENC_DATA] = The order encrypted data, useful to restore the order itself
  • [UCASEKEYWORD] = The original keyword taken from the user's invoice data
  • [SHIPPING_UCASEKEYWORD] = The original keyword taken from the user's shipping data
  • [USE_SHIPPING_DATA] = Is replaced by "true" or "false" boolean value if the user has compiled or not the shipping form

The available keywords on the INVOICE and SHIPPING sections are:

[COMPANY], [NAME], [LASTNAME], [ADDRESS1], [ADDRESS2], [ZIPPOSTALCODE], [CITY], [STATEREGION], [COUNTRY], [COUNTRYCODE], [EMAIL], [PHONE], [MOBILE], [FAX], [VAT], [CUSTOMERID], [ADVERTS], [NOTE]

Moreover, any custom field is added using a custom ID so you can just use its ID or its uppercased name in the keyword to replace it in the HTML code.

Example 

[NAME] // Will be replaced with the customer's name
[000000000] // This field ID will be replaced with the customer's custom field value
[CUSTOM FIELD NAME] // This uppercased field name will be replaced with the customer's custom field value
HTML Escaping

Each keyword can be replaced with the HTML escaped version of its value by placing HESCAPE_ before it.

Kind: instance method of ecommerce

Param Type Description
options Object The options

Example 

[HESCAPE_PRICE] // Will be replaced with the HTML escaped price in the default format 

##### URL Escaping
Each keyword can be replaced with the URL escaped version of its value by placing UESCAPE_ before it.

Example 

[UESCAPE_PRICE] // Will be replaced with the URL escaped price in the default format

.setOrder(callback) ⇒ void

Set the order

Kind: instance method of ecommerce
Returns: void - The order number

Param Type
callback function

.orderNumber() ⇒ String

Provide the order number

Kind: instance method of ecommerce

.empty(save) ⇒ void

Empty the cart

Kind: instance method of ecommerce

Param Type Description
save Boolean True to save the cart

.getStringifiedEncodedData() ⇒ String

Encode the data of the cart, with order data and form data encoded to prevent privacy issues

Kind: instance method of ecommerce

.getStringifiedFormData() ⇒ String

Stringify the saved form data

Kind: instance method of ecommerce

.getStringifiedOrderData() ⇒ String

Get a JSON string of the data to be saved

Kind: instance method of ecommerce

.bind(event, callback) ⇒ void

Bind a callback on a cart event

Kind: instance method of ecommerce

Param Type
event String
callback function

.unbind(event, callback) ⇒ void

Unbind a callback from a cart event

Kind: instance method of ecommerce

Param Type
event String
callback function

.restore(stringifiedEncodedData) ⇒ Boolean

Restore the cart using the current data

Kind: instance method of ecommerce

Param Type Description
stringifiedEncodedData String The encoded order string

.getLastOrderNumber() ⇒ String

Get the last order number

Kind: instance method of ecommerce
Returns: String - The last order made on the customer's PC or null

.clearLastOrderNumber() ⇒

Clear the last order number

Kind: instance method of ecommerce
Returns: void