Minicart.js – Improve PayPal Shopping Cart Integration

Download   Demo

Minicart is a great way to improve your PayPal shopping cart integration. One simple change and your users will be able to manage their shopping cart directly from your website. Additional APIs provide you the power to customize the behavior to your needs.

Basic Setup

1. Create a PayPal Add to Cart Button


2. Include the following snippet into your HTML before the closing </body> tag:
   
   
   

   <script src="//cdnjs.cloudflare.com/ajax/libs/minicart/3.0.5/minicart.min.js"></script>
   <script>
    paypal.minicart.render();
   </script>
   

   
   
   
   


3. On your return page include:
   
   
   

   <script>
    paypal.minicart.reset();
   </script>
   

   
   
   
   

It’s that simple! Now the minicart will appear when a user views or adds a product to their cart.

Advanced API

The minicart has a JavaScript API for advanced users to customize the behavior.

General

paypal.minicart.render(config) Renders the minicart to the page. Config is optional and can have the following properties:

• parent - HTMLElement the minicart should render to.


• target - HTML target property for the checkout form.


• action - PayPal URL (if you are accessing sandbox or another version of the PayPal website).


• template - HTML template for rendering. See customization for details.


• styles - CSS styles for rendering. See customization for details.


• strings - An object of text strings: button, buttonAlt, subtotal and discount.

paypal.minicart.reset() Resets the minicart back to its default state.

View

paypal.minicart.view.show() Triggers the minicart to show by adding a “minicart-showing” CSS class to the document.

paypal.minicart.view.hide() Triggers the minicart to hide by removing the “minicart-showing” CSS class on the document.

paypal.minicart.view.toggle() Toggles the visibility of the minicart.

paypal.minicart.view.bind(form) Binds an HTMLFormElement’s submit event to the minicart. Useful for forms which may have been added to the page after the initial load.

Cart

paypal.minicart.cart.add(data) Adds an item to the cart. Fires the add event. Example data object:

 "business": "user@example.com", "item_name": "Product", "amount": 5.00, "currency_code": "USD" 

paypal.minicart.cart.remove(idx) Removes an item from the cart by index. Fires the remove event.

paypal.minicart.cart.items(idx) Returns an array of items from the cart. If an index is passed then only that item is returned.

paypal.minicart.cart.settings(key) Returns an object of global cart settings. If a key is passed then only that value is returned.

paypal.minicart.cart.discount(config) Calculates the cart discount amount. config can be used for formatting.

paypal.minicart.cart.subtotal(config) Calculates the cart total minus discounts. config can be used for formatting.

paypal.minicart.cart.total(config) Calculates the cart total. config can be used for formatting.

paypal.minicart.cart.destroy() Destroys the cart data and resets it back to the default state. Fires thedestroy event.

paypal.minicart.cart.on(event, fn, scope) Subscribe to cart events. Events include:

• add - Fired when an item is added. function (idx, product, isExisting)


• remove - Fired when an item is removed. function (idx, product)


• checkout - Fired on checkout. function (evt)


• destroy - Fired when the cart is destroyed. function ()

paypal.minicart.cart.off(event, fn) Unsubscribe from cart events.

Products

product.get(key) Returns a properties object for the product. If a key is passed then only that value is returned.

product.set(key, value) Sets a property for the product. Fires a change event.

product.options() Returns the options.

product.discount(config) Calculates the product discount. config can be used for formatting.

product.amount(config) Calculates the product amount discounts. config can be used for formatting.

product.total(config) Calculates the product total. config can be used for formatting.

product.isEqual(product2) Determines if the current product is the same as another.

product.destroy() Destroys the product. Fires the destroy event.

product.on(event, fn, scope) Subscribe to cart events. Events include:

• change - Fired when a value is changed. function (key)


• destroy - Fired when the product is destroyed. function ()

product.off(event, fn) Unsubscribe from product events.

API Examples

Examples of how you can use the API:

• Preventing checkout until terms are accepted


• Requiring a minimum quantity to checkout


• Only allowing a fixed quantity per item


• Ensuring an option is selected

Customization

The minicart HTML template and CSS can be fully customized using two different approaches: configuration and custom themes. In both approaches, all functionality from the API is available using Embedded JavaScript Template syntax.

Configuration

The HTML template and CSS can be overridden using the config object.

var myTemplate = "<div><%= config.strings.subtotal %> <%= cart.total( format: true, showCode: true ) %></div>";

paypal.minicart.render(
 template: myTemplate
);

Custom Themes

Custom themes can be created and bundled into your own custom version of the minicart.js file.

Before creating a custom theme you’ll need to have node.js installed. Once install is complete, open a terminal window and run npm install -g grunt-cli to install Grunt.

To create a theme follow these steps:

1. Fork and clone this repo so you can make your own changes. If you’re not sure what this means you can find out more on Github’s Help.


2. In your new fork, create a directory under src/themes with your theme name. For example, let’s createsrc/themes/myAwesomeTheme.


3. Next add your HTML template into src/themes/myAwesomeTheme/index.html. The templates use Embedded JavaScript Template syntax for logic.


4. Finally add your CSS styles into src/themes/myAwesomeTheme/styles.css.


5. With all that behind you it’s now time to generate your custom minicart JavaScript file. In a terminal window run grunt build --theme=myAwesomeTheme. This will output a bundled JavaScript file complete with the minicart and your new theme at dist/minicart.myAwesomeTheme.js.


6. Include this file into your HTML page instead of the normal JavaScript file and you’ll see your new theme!

If you’re new to the building a theme it’s a good idea to copy the one at src/themes/default and start there.

Localization

Localization is supported using the strings object.

paypal.minicart.render(
 strings: 
 button: "Caisse",
 buttonAlt: "Total:",
 discount: "Reduction:"
 
);

The currency symbol will be automatically updated based on the currency_code setting of your button.

Minicart.js – Improve PayPal Shopping Cart Integration