UniShop - jQuery XML PayPal Shopping Cart Plugin

Documentation

1. About

UniShop is an ultimate PayPal Shopping Cart plugin with a lot of features and modern design. With UniShop you can build your paypal shop in less than 30 min and start selling right way! No complex markup and no database is required. Just create an XML file with your products, add shop container to your webpage, insert plugin init code and you are done!

Key Features

Powerful filtering system with multiple filters, search boxes, range sliders and sorting boxes
User-friendly responsive one page design
Masonry grid with products (1,2,3 columns)
Modalbox with product description, images and prices
Multiple product options (with the prices)
Shopping cart with your purchases
Support for tablets & smartphones
Ability to customize plugin and add new features
Clear code with comments

2. Installation

Before installing UniShop make sure that your website links jQuery Library (latest version you can download from https://jquery.com/download/ website)

So, first of all you need to copy plugin files from a ZIP package that you downloaded from codecanyon.net to the corresponding directories under your website

css/unishop.css -> css/
css/unifilter.css -> css/
js/jquery.unishop.min.js -> js/
js/jquery.unifilter.min.js -> js/
js/masonry.min.js -> js/
images/uf-reset.png -> images/
images/uf-clear.png -> images/
images/uf-asc.png -> images/
images/uf-desc.png -> images/
images/unishop-icons-24.png -> images/
images/unishop-icons-32.png -> images/

Next you should link JS/CSS files in <head> section of your index.html file

		
		<link rel="stylesheet" href="css/unifilter.css">
		<link rel="stylesheet" href="css/unishop.css">
		
		
		<script type="text/javascript" src="js/jquery-3.3.1.min.js"></script>
		<script type="text/javascript" src="js/masonry.min.js"></script>
		<script type="text/javascript" src="js/jquery.unifilter.min.js"></script>
		<script type="text/javascript" src="js/jquery.unishop.min.js"></script>

UniShop plugin does not require any markup. Just create container DIV for the shop and add it to the <body> of your index.html file

		<!-- UNISHOP CONTAINER -->
		<div id="shop"></div>
		<!-- UNISHOP CONTAINER -->

Now you can add init code to the <head> section of your index.html file, that will look like this

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					shopXML: 'shop.xml',
					currencySymbol: '$',
					currencyName: 'USD',
					paypal: {
						business: 'your_shop@domain.com',
						currency_code: 'USD',
						lc: 'US'
					},
					shopFilters: {
						filters: 'category'
					}
				});
			});
		  </script>

For more plugin options see section 4. Plugin Options of this documentation

3. Shop XML

The "shop.xml" file contains information about the products in your shop, like a name, price, rating, thumbs and so on and it has the following structure

		<?xml version="1.0" encoding="UTF-8"?>
		<shop>
			<item>
				<name>Product #1</name>
				<price>10</price>
				<sku>sku12345</sku>
				<description>Product description & information</description>
				<rating>5</rating>
				<category>cat1, cat2, cat3</category>
				<thumbs>thumbs/tmb01_1.jpg, thumbs/tmb01_2.jpg</thumbs>
				<photos>photos/pic01_1.jpg, photos/pic01_1.jpg, photos/pic01_1.jpg</photos>
				<quantity min="1" max="10">1</quantity>
				<shipping>1.5</shipping>
				<options>
					<option name="Some Option">
						<entry value="Option_1">Option #1</entry>
						<entry value="Option_2">Option #2</entry>
						<entry value="Option_3">Option #3</entry>
						<entry value="Option_4">Option #4</entry>
					</option>
					…
					<option name="Price Option">
						<entry value="Option_1" price="10">Option #1 - $10</entry>
						<entry value="Option_2" price="20">Option #2 - $20</entry>
						<entry value="Option_3" price="30">Option #3 - $30</entry>
					</option>
					… 
				</options>
			</item>
			
			...
		
			<item> … </item>
			<item> … </item>
			<item> … </item>
		</shop>

XML markup starts with standard comment and contains single top level element called <shop>. The <shop> element contains multimple <item> elements that correspond to the products in your shop.

Every <item> contains a set of XML elements (parameters) that set a price, name, rating of the product. Default elements that you can add to <item> are listed below. Also you can add your own XML elements and customize the script to use them in some way

Element	Description
<name>	name of a product
<price>	price of a product. Also may contain a sale="NN" attribute with the old price to show percent discount badge
<sku>	alphanumeric product ID that should be unique for every product in shop, like sku2355
<description>	short description of a product which will be displayed in modalbox
<rating>	product rating as a number from 0 to 5 stars. Decimals numbers like 4.5 are allowed too
<category>	comma-separated lists of categories that particular product belongs to for filtering purposes. Also instead of <category> XML element you can add whatever element you need (e.g. <size>, <color>) and configure UniShop to use it for filtering (see section 6. Shop Filters)
<thumbs>	URL to the image (relative to the index.html) that will be used as a product thumb in grid. Also you can add a second URL separated by a comma. In this case the thumbs will fade-in-out on "mouse hover"
<photos>	a comma-separated list with URLs to the images that will be displayed in product description modalbox
<quantity>	inital item quantity, usually 1. Also you should specify "min", "max" attributes so customer cannot buy more items than you have
<shipping>	shipping cost of a particular product regardless of the quantity purchased. If you set 0 then shipping charges will be displayed as "FREE"
<options>	container for multiple <option> elements that allow customer to make a selection of product variant upon purchase. This can be used for example to create a select box with different sizes or colors of a particular product. Also UniShop allows to have single <option> element that sets a price of item depending on selected option.

By default "shop.xml" is located in the same directory as your index.html. If you want to change its location you should change "shopXML" plugin option accordingly.

4. Plugin Options

In a list below you can find all UniFilter options with an explanation what they do

	// default options
	var default_options = {
		shopXML: 'shop.xml',								// shop XML file. Default "./shop.xml"
		shopID: 'myshop',									// your shop #ID
		masonry: true,										// use Masonry plugin for grid layout
		shopColumns: 3,										// grid columns 1,2,3. Default 3
		currencySymbol: '$',								// shop currency symbol, e.g '$'
		currencyName: 'USD',								// shop currency name, e.g. 'USD'
		localStorage: 'unishop',							// name of local storage to save cart contents 
		shopFilters: {										// shop filters configuration or false
			filters: null,									// filters XML elements, e.g. 'color, size'
			search: null,									// search XML elements, e.g. 'name'
			sort: null,										// sort XML elements, e.g. 'price, rating'
			range: null,									// range XML elements, e.g. 'price'
			order: 'filters, range, search, sort',			// order to display filters, range, search and sort
			animationTime: 500,								// animation duration, ms
			animationType: 'opacity'						// filtering animation - 
															// 'none|opacity|scale|rotate|translate'
		},
		paypal: {
			'business': 'paypal@domain.com',				// your PayPal business account
            'currency_code': 'USD',							// your shop currency
            'lc': 'US',										// your shop locale
            'no_shipping': 0,								// request shipping address on checkout
            'return': 'http://www.domain.com/shop/',		// URL to return after successful checkout
            'cancel_return': 'http://www.domain.com/shop/'	// URL to return when checkout is canceled
		},
		onReady: null,										// DOM ready callback
		onCart: null,										// new cart item added callback
		onCheckout: null 									// paypal checkout callback
		
	};

Now let's look on every option more precisely

Option	Default	Description
shopXML	"shop.xml"	location of shop XML file
shopID	"unishop"	ID to assign to the unishop wrap element
masonry	true	if available use Masonry plugin to align items in grid
shopColumns	3	number of columns in grid (can be 1,2,3 cols)
currencySymbol	$	currency symbol for display purposes
currencyName	USD	currency name for display purposes
localStorage	"unishop"	if not false, use this name to save cart contents in browser cache when page has been reloaded or window closed
shopFilters	[Object]	Object with shop filters configuration or false. See section 6. Shop Filters for more information
paypal	[Object]	Object with PayPal configuration and variables. See section 5. PayPal Setup for more information
onReady	[Function]	this callback function is executed as soon as shop DOM is ready. "this" keyword inside of a functin refers to UniShop DOM element
onCart	[Function]	use this callback to add/modify product params before it's being added to the cart. Function accepts object with product params as argument and should return it afterwards
onCheckout	[Function]	use this callback to add additional variables to the checkout request to Paypal.com. Function accepts object with cart items as well as paypal variables as an argument and should return it afterwards

5. PayPal Setup

To start accepting payments you shold signup to the business type of PayPal account - instructions here. If you already have one, just skip this step.

Then you should set a currency and your business paypal account using the "paypal" plugin option, like so

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					shopXML: 'shop.xml',
					currencySymbol: '$',
					currencyName: 'USD',
					paypal: {
						business: 'your_shop@domain.com',
						currency_code: 'USD',
						lc: 'US'
					},
					shopFilters: {
						filters: 'category'
					}
				});
			});
		  </script>

Now you can accept payments to 'your_shop@domain.com' and the currency in which paypal will process payments from your online buyers is set to USD ('currency_code' paypal variable). Please note that 'currency_code' should match the "display" currency of UniShop plugin ("currencySymbol" & "currencyName" plugin options).

With the "paypal" option you can add any other cart-wide PayPal variables to UniShop. Complete list with paypal variables can be found here

6. Shop Filters

UniShop uses UniFilter jQuery Plugin for filtering, searching and sorting the products in your paypal shop. The steps necessary to configure filters, search and sorting are quite simple.

First you should add a parameter (XML element) to the items in "shop.xml" and then configure "shopFilters" plugin option with that XML tag name. Depending on whether it should be a filter, range slider, search or sort box the values of the XML element may be different. For search and filters the value should be a comma-separated list of words; range can accept only single numeric value; while the sort requires either numeric or alphabetic value

Let's better check some examples!

You might already noticed the <category> XML element that is used to perform a filtering by a category. Now let's add another filter to filter by a color. So, open "shop.xml" file and add "<color></color>" XML element to every <item> in your shop

		<?xml version="1.0" encoding="UTF-8"?>
		<shop>
			<item>	
				...
				<color>black, white</color>
				...
			</item>
			<item>
				...
				<color>green, white</color>
				...
			</item>
			<item>
				...
				<color>blue, yellow</color>
				...
			</item>
			...
		</shop>

To display filter with colors in UniShop sidebar you should add XML tag name (the "color" in our case) to the list of filters in "shopFilters" plugin option, like so

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					...
					shopFilters: {
						filters: 'category, color'
					}
				});
			});
		  </script>

Reload the page and you will get two filters - one by a category and second by a color. Note that you may add as many filters as you need.

Now, what if you want to search by a color? In this case init code will be like this

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					...
					shopFilters: {
						filters: 'category',
						search: 'color'
					}
				});
			});
		  </script>

You can also search by any other XML element, for example "<name>"

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					...
					shopFilters: {
						filters: 'category',
						search: 'name'
					}
				});
			});
		  </script>

Let's now take a look on range slider. With the range slider you can filter items in grid that match some numeric range. For example, what if you want to display items with a price within some range. UniFilter init code in this case will look like this

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					...
					shopFilters: {
						filters: 'category',
						search: 'name',
						range: 'price'
					}
				});
			});
		  </script>

When you will check "shop.xml" file you will see that every <item> has <price> XML tag with single numeric value, so we can easily use it to make a range slider. The same way you can add any other XML tag with single numeric value to create another range slider, for instance to filter products by rating or by size

Along with filters, search fields and range sliders you may add a sort drop down list. Let's say you want to sort items by rating. XML element that can be used for sorting shold have single numeric or alphabetic value, and to create a sort box you shoud add that XML element tag name to the "sort" list of "shopFilters" plugin option

		 <script type="text/javascript">
			$(document).ready(function(){
				$('#shop').unishop({
					...
					shopFilters: {
						filters: 'category',
						search: 'name',
						range: 'price',
						sort: 'rating'
					}
				});
			});
		  </script>

Thanks for reading!