jQuery Smart Cart 3: Documentation

The smart interactive jQuery Shopping Cart plugin with PayPal payment support

Requirements

  1. Bootstrap 3+
  2. jQuery (supports jQuery 1.9+, jQuery 2+, jQuery 3+)

Installation

NPM

npm install jquery-smartcart

Bower

bower install jquery-smartcart

Composer

composer require techlab/jquery-smartcart

Download

Get the latest source files from Github Download

How to use

Include Bootstrap CSS (ignore this if you have already included on the page)

You can use CDN or your own Bootstrap installation
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet" />

Include SmartCart CSS

<link href="../dist/css/smart_cart.min.css" rel="stylesheet" type="text/css" /> 

Include HTML

The HTML has two parts, product list and cart list. The product list can be any design you prefer, Smart Cart will not managed it, but there is some setting need to do so that Smart Cart can identify the "Add To Cart" buttons and the values of the product. While the cart list is fully managed by Smart Cart ofcourse it is customizable too.

First we can look at the basic of the product list
Things to note:
  • Add to cart button is identified by searching for the elments with class name "sc-add-to-cart", and a click event is attached with it.
  • Then the product container of a product is identified by the class name "sc-product-item"
  • The product container must have the basic values for the product like product_name, product_price etc
  • The product values like product_price is identified by searching for an element with attribute name or data-name
  • All the element values with attribute name or data-name will be added to product object
<div class="row">
<!-- BEGIN PRODUCTS -->
<div class="col-md-4 col-sm-6">

<!-- PRODUCT CONTAINER, identified by the class "sc-product-item" -->
<div class="sc-product-item">
<!-- PRODUCT IMAGE, identified by data-name="product_image" -->
<img data-name="product_image" src="http://placehold.it/250x150/2aabd2/ffffff?text=Product+1" alt="...">

<!-- PRODUCT NAME, identified by data-name="product_name" or can be an element with name="product_name" -->
<h4 data-name="product_name">Product 1</h4>
<!-- PRODUCT DESCRIPTION, identified by data-name="product_desc" or can be an element with name="product_desc" -->
<p data-name="product_desc">Product details</p>

<!-- PRODUCT PRICE, identified by name="product_price" or can be an element with data-name="product_price" -->
<input name="product_price" value="2990.50" type="hidden" />
<!-- PRODUCT ID, identified by name="product_id" or can be an element with data-name="product_id" -->
<input name="product_id" value="12" type="hidden" />

<!-- ADD TO CART BUTTON, identified by class="sc-add-to-cart" -->
<button class="sc-add-to-cart btn btn-success">Add to cart</button>
</div>

</div>
<div class="col-md-4 col-sm-6">

<!-- PRODUCT CONTAINER 2 -->
<div class="sc-product-item">
<img data-name="product_image" src="http://placehold.it/250x150/2aabd2/ffffff?text=Product+2" alt="...">

<h4 data-name="product_name">Product 2</h4>
<p data-name="product_desc">Product details</p>

<input name="product_price" value="320.75" type="hidden" />
<input name="product_id" value="14" type="hidden" />
<button class="sc-add-to-cart btn btn-success">Add to cart</button>
</div> </div> <!-- END PRODUCTS --> </div>

And the second part is the cart HTML which is simple. A div element wrapped with a form element which we can used to submit the cart values
<form action="results.php" method="POST"> 
<!-- SmartCart element -->
<div id="smartcart"></div>
</form>

Include jQuery (ignore this if you have already included on the page)

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

Include SmartCart JavaScript

<script type="text/javascript" src="../dist/js/jquery.smartCart.min.js"></script>

Invoke the SmartCart plugin

<script type="text/javascript">
$(document).ready(function(){
  $('#smartcart').smartCart();
});
</script>

Paypal Implementation

Please see the above implementaion and here specifying only the part that need change, the cart html section and the cart invoke section.

HTML for the cart

<!-- Paypal Submit URL : https://www.paypal.com/cgi-bin/webscr -->
<!-- Paypal Sandbox Submit URL: https://www.sandbox.paypal.com/cgi-bin/webscr -->

<!-- Paypal Cart submit form -->
<form action="https://www.paypal.com/cgi-bin/webscr" method="POST">
<!-- SmartCart element -->
<div id="smartcart"></div>

<!-- Paypal required info, Please update based on your details -->
<input name="business" value="YOUR-PAYPAL-EMAIL-HERE" type="hidden">
<input name="currency_code" value="USD" type="hidden">
<input name="return" value="http://www.yourdomain.com/yoursuccessurl" type="hidden">
<input name="cancel_return" value="http://www.yourdomain.com/yourcancelurl" type="hidden">

<input name="cmd" value="_cart" type="hidden">
<input name="upload" value="1" type="hidden">
</form>

Invoke the SmartCart with Paypal option

<script type="text/javascript">
    $('#smartcart').smartCart({
                                submitSettings: {
                                    submitType: 'paypal' // form, paypal, ajax
                                },
                                toolbarSettings: {
                                    checkoutButtonStyle: 'paypal' // default, paypal, image
                                }
                            });
		});
</script>
Continue reading to know more about parameters, events and customization.

Parameter Description:

Parameter Name Description Values Default Value
cart initial products on cart Object Array []
resultName Submit name of the cart parameter String cart_list
theme theme for the cart, related css need to include for other than default theme String default
combineProducts Combine similar products on cart true/false true
highlightEffect Highlight effect on adding/updating product in cart true/false true
cartItemTemplate Template to show items in the cart String <img class="img-responsive pull-left" src="{product_image}" /><h4 class="list-group-item-heading">{product_name}</h4><p class="list-group-item-text">{product_desc}</p>
cartItemQtyTemplate Template to show item quantity in the cart String {display_price} × {display_quantity} = {display_amount}
productContainerSelector Selector used to identify the product container in the product list. String .sc-product-item
productElementSelector Selector used to identify the elements whoes values to be included with the cart object String *
addCartSelector Selector used to identify the "Add To Cart" Button String .sc-add-to-cart
debug Enable/Disable debug mode Boolean false
paramSettings Map the paramters in the product list with the cart object

{
    productPrice: 'product_price',
    productQuantity: 'product_quantity',
    productName: 'product_name',
    productId: 'product_id',
}
lang An object with language variables

{
    cartTitle: "Shopping Cart",
    checkout: 'Checkout',
    clear: 'Clear',
    subtotal: 'Subtotal:',
    cartRemove:'×',
    cartEmpty: 'Cart is Empty!<br />Choose your products'
}
submitSettings An object with submit setting

{
    submitType: 'form', // form, paypal, ajax
    ajaxURL: '', // Ajax submit URL
    ajaxSettings: {} // Ajax extra settings for submit call
}
currencySettings An object with currency setting

{
    locales: 'en-US', // A string with a BCP 47 language tag, or an array of such strings
    currencyOptions:  {
        style: 'currency', 
        currency: 'USD', 
        currencyDisplay: 'symbol'
    } // extra settings for the currency formatter. Refer: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString
}
toolbarSettings An object with toolbar setting

{
    showToolbar: true,
    showCheckoutButton: true,
    showClearButton: true,
    showCartSummary:true,
    checkoutButtonStyle: 'default', // default, paypal, image
    checkoutButtonImage: '', // image for the checkout button
    toolbarExtraButtons: [] // Extra buttons to show on toolbar, array of jQuery input/buttons elements
}

Event Description:

Event Name Description Parameters
itemAdded Triggers when an item is added on the cart Object: object of the product.
itemUpdated Triggers when an item is updated on the cart Object: object of the product.
itemRemoved Triggers when an item is removed from the cart Object: object of the product.
cartCleared Triggers when the cart is cleared
quantityUpdated Triggers when an item quantity is updated on the cart Object: object of the product.
Integer: new quantity value.
cartEmpty Triggers when the cart is empty
cartSubmitted Triggers when the cart is submitte Object: object array of full cart.

Example: Event Initialize

<script type="text/javascript">
  $(document).ready(function() {
      
      // Initialize the leaveStep event
      $("#smartcart").on("cartEmpty", function(e) {
         alert("Cart is empty");
      });

      // Initialize Smart Cart 
      $('#smartcart').smartCart();
  }); 
</script>

Programmer in PHP and C# with added interest in jQuery, Bootstrap, HTML and CSS. Believes that the code should be as beautiful as the design.

Comments