Welcome to CMSnipcart’s documentation!¶
CMSnipcart is a Joomla! component for building an ecommerce website powered by Snipcart and Joomla! CMS.
This documentation gives your instruction for how to install and setup CMSnipcart on your Joomla! website.
Contents:
Overview¶
CMSnipcart is a Joomla! component for building an ecommerce website powered by Snipcart and Joomla! CMS.
Snipcart is a “lean, powerful HTML/JavaScript shopping cart” which can be used on any website. You just need to include some lines of code and start selling, Snipcart takes care of your payments, order history, your customers... so you can have a shopping site running quickly. There is no setup fee or monthly fee, Snipcart takes a small 2% fee of your sale or only $10 fee if your monthly sales are under $500. You can find more info about Snipcart at https://www.snipcart.com/.
Because Snipcart is an HTML/JavaScript shopping cart, you can find it difficult to setup your site if you are not a web developer or if you are not familiar with HTML, CSS and JavaScript. CMSnipcart helps you do all of the technical tasks to have a Joomla! website with Snipcart integrated.
CMSnipcart includes:
- CMSnipcart component: the main component for managing your store.
- CMSnipcart system plugin: inserting Snipcart code into Joomla! pages.
- Profile module: showing login, logout buttons and Snipcart order history.
- Shopping cart module: showing items in Snipcart shopping cart.
- Products module: showing list of products horizontally or vertically.
Technical Requirements¶
CMSnipcart is compatible with Joomla! 3.x.x. The latest version of Joomla! is recommended. CMSnipcart is NOT compatible with Joomla! 1.x.x and 2.5.x.
Please check Joomla!’s Technical Requirements for more information of Joomla!’s requirements.
Features¶
Front-end¶
- Show list of all products or products in a specific category.
- Select product attributes (like size, color...) and quantity before adding to shopping cart.
- Control product’s stock.
- Like/share buttons for Facebook, Twitter, Pinterest and Google+.
- Zoom product’s image.
- Change product’s image based on selected attributes.
- Shopping cart module.
- Products module to show a list of products horizontally or vertically.
- Module for Snipcart profile.
Back-end¶
- Manage products, categories, product attributes, discounts, order custom fields, orders and customers.
- Customize Snipcart’s texts (localization).
Installation¶
Installation¶
In your Joomla! back-end, you navigate to Extensions -> Manage
In “Upload Package File” tab, you click “Browse” button and select the installation package of CMSnipcart on your computer, click “Upload & Install” button to upload the package to your server and install it.
If the package is installed successfully, you receive the message “Installion of the package package was successful.”
You can see CMSnipcart in Components menu item.
Update¶
In order to updating CMSnipcart to a greater version, you just need to install the new package, there is no extra steps required.
Configuration¶
In your Joomla!’s back-end, you go to Components -> CM Snipcart to access CMSnipcart component.
The default page is the dashboard.
You click the “Options” button on the toolbar to configure CMSnipcart. You can find 6 configuration tabs: Mode & Credentials, General, Shopping Cart & Checkout, Currency, Notification and Permissions.
Mode & Credentials¶
In “Mode & Credentials” tab we have the folling options:
Mode: Your Snipcart shop’s mode.
Live Public API Key: The public API key for your shop when it is in Live mode.
Test Public API Key: The public API key for your shop when it is in Test mode.
Live Secret API Key: The secrect API key for your shop when it is in Live mode.
Test Secret API Key: The secrect API key for your shop when it is in Test mode.
Webhook secret key: A secret key which is appended to webhook URL to protect it from public access. This webhook is used to receive notifications for your orders from Snipcart. Webhook must be enabled in order to control your product stocks (inventory). Your webhook URL looks like this:
http://www.yoursite.com/index.php?option=com_cmsnipcart&task=webhook&key=WEBHOOK_SECRECT_KEY
Get API Keys¶
To get your API keys, log into Snipcart, open the right menu.
Click “API KEYS” menu item.
On the top of the page, you can switch between Live and Test mode. In each mode you have different public API key and secret API Key.
Copy your public API key to public API key field in your CMSnipcart’s configuration. At the bottom of the page, create your secrect API key and copy it to secret API key field in CMSnipcart’s configuration. Be careful to paste the keys into the correct mode field (if you are in Test mode, paste to the fields of Test mode).
Configure Domain¶
In your Snipcart dashboard, open the right menu, click “DOMAINS & URLS” menu item.
Select the protocol your website uses in “PROTOCOL” option (HTTP or HTTPS), enter your domain in “DOMAIN” field. This is the domain of your shopping site.
Configure Webhooks¶
In your Snipcart dashboard, open the right menu, click “WEBHOOKS” menu item.
Enter your webhook URL into “WEBHOOKS URL” field. Your webhook URL looks like this:
http://www.yoursite.com/index.php?option=com_cmsnipcart&task=webhook&key=WEBHOOK_SECRECT_KEY
Replace “http://www.yoursite.com” with the URL of your website and “WEBHOOK_SECRECT_KEY” with the webhook secret key which you configure in CMSnipcart’s configuration.
IMPORTANT: Webhook must be enabled in order to control your product stocks.
General¶
In “General” tab we have the folling options:
- Load Joomla!’s jQuery: Load the jQuery version which is shipped with Joomla!. CMSnipcart requires jQuery to work. Set this option to No if jQuery is already loaded by another extension.
- Bootstrap: The Bootstrap version available in front-end. Bootstrap is often loaded by your template.
- Default Max Quantity Allowed To Buy: You can set the max quantity which customer can buy for a product in every checkout, if that value is 0, this default value is used instead.
- Front-end’s Pagination Limit: The number of items is displayed in front-end product list. Default is 20 items.
- Back-end’s Pagination Limit: The number of items is displayed in back-end list. Default is 20 items.
- Load FontAwesome: CMSnipcart uses FontAwesome, load FontAwesome from CMSnipcart if FontAwesome is not loaded by other extensions.
- Load override CSS file: Load override CSS file to override Snipcart default styles. You need to create components/com_cmsnipcart/assets/css/snipcart.css file and add your override CSS styles.
- Social Network buttons: Show social network buttons.
- Change Product Thumbnail With Selected Child Product’s Thumbnail: Update product’s thumbnail image in deal detail page with the image of the selected child product.
- Zoom Thumbnail On Hover: Zoom product’s thumbnail on mouse hover.
- Snipcart’s Language: Use another language for Snipcart instead of English.
Shopping Cart & Checkout¶
In “Shopping Cart & Checkout” tab we have the folling options:
- Add To Cart Mode: The way we add product to shopping cart.
- Show Shopping Cart Popup When Adding An Item: Automatically show shopping cart popup when adding an item to the cart.
- Show Continue Shopping Button: Show Continue Shopping button in shopping cart.
- Allowed Credit Cards: Credit cards you want available during checkout.
- Allowed Shipping Methods: Enter shipping method’s IDs, seperated by a comma. For example: fedex-2-day,fedex-express-saver. You can create shipping methods in Snipcart dashboard. If no shipping methods is set, all shipping methods are allowed.
- Autocheck “Use this address for shipping”: Check “Use this address for shipping” checkbox automatically.
Currency¶
In “Currency” tab we have the folling options:
- Currency symbol: Currency symbol which is used for original price, discounted price and discounted value.
- Currency symbol’s position: Where currency symbol is displayed, before or after amount.
- Currency decimals: The number of decimals in currency.
- Decimal point: The character which is used as decimal point.
- Thousands separator: The character which is used as thousands separator.
Notification¶
“Notification” tab contains the options for AJAX notifications in back-end, these notifications notify you if a task is done successfully or if there is any errors.
- Notification position Where notification is displayed on the page.
- Notification’s timeout (seconds) The number of seconds a notification is visible after disappears.
Persmissions¶
“Permissions” tab allows you to configue what users in specific user groups can do.
If you are the only one can access Joomla! back-end or if all the users who can access Joomla! back-end have the same rights, you can leave these options with default settings. However if you allow other users to access Joomla! back-end and want to limit their rights in CMSnipcart component, you can adjust these settings to suit your needs.
CMSnipcart system plugin¶
After enter your public API key in CMSnipcart component’s configuration, you need to check if Snipcart can connect to your site.
In your back-end, you go to Extensions -> Plugins, search for “System - CMSnipcart” plugin and enable this plugin.
In your Snipcart dashboard, click “VALIDATE THE JAVASCRIPT FILE” button next to “Have you included Snipcart javascript file on your website? Click on the button next to this message to validate it.” message in your notification section.
Enter your site’s URL in the next step.
If the validation is successful, you see the message “We have confirmed that Snipcart javascript file is included correctly on your website with your API Key.”
The notification “Have you included Snipcart javascript file on your website? Click on the button next to this message to validate it.” now disappears.
Menu Items¶
CMSnipcart has 3 menu items which are required to run CMSnipcart properly:
- Products: Used to show a list of products. You can show all products or only the products in a specific category.
- Product: Used to provide friendly URL for product detail page and help you control the Joomla! module which are displayed in product detail page.
- Thank You: After completing an order, customer is taken to this page. This page shows information of completed order.
Products Menu Item¶
In your Joomla! back-end, you access the menu where you want to create menu item for product list, click “New” button on the toolbar to create a new menu item.
In “Menu Item Type” option, click “Select” button and select “Products” from CMSnipcart.
If you want to show all products, you select “- All Categories -” in “Category” option, otherwise you select a specific category to show only the products in that category.
Switch to “Options” tab, you can use “Columns” option to configure the column quantity in product list.
Product Menu Item¶
Create a new menu item for Product, ensure you select your hidden menu in “Menu Location” option.
Thank You Menu Item¶
Similar to Product menu item, you create a new menu item for Thank You, put it in your hidden menu.
Categories¶
Create New Category¶
Go to CMSnipcart in your Joomla! back-end by navigating to Components -> CM Snipcart. Click “Categories” in the left menu.
To create a new category, you click “New” button.
We have the following fields in the form:
- Name: Category’s name.
- Alias: Category’s alias for friendly URL. This alias is not used yet, you can leave this field empty or keep the auto-generated value.
- Status: This info is currently not used. You can keep the default “Published” value.
- Meta Description: Meta description for search engine optimization.
- Meta Keywords: Meta keywords for search engine optimization. Keywords are separated by comma.
Change Status¶
In category list, you can click on category name to edit a specific category and change its status. You can change status directly in category list by clicking the green or red circle in “Status” column. You can do the same to products and order custom fields.
Delete Categories¶
To delete categories, you select them in category list and click “Delete” buton. A confirmation popup appears, you click “Yes” to confirm and delete the selected categories. Similar popups appear when you delete products and order custom fields.
Sort Categories¶
By sorting categories, you decide the ordering of the categories. This feature is currently not used yet in front-end, it will be used in future when more features are added to CMSnipcart.
To sort categories, you click “Ordering” column header in category list, then you click drag and drop the icons in “Ordering” column to sort the categories.
You can also sort products, order custom fields and product attributes.
Product Attributes¶
If your product has many characteristics which require customers to choose before purchase, product attribute helps you create these characteristics.
In your Joomla! back-end, navigate to Components -> CM Snipcart. Click “Product Attributes” in the left menu.
Click “New” button to create a new product attribute.
You give your product attribute a name, click “New Option” to add options for this attributes. You can select these options when you create/edit products, customers select these options before purchase.
To delete an option, you click the red X button on the right side of option’s name.
To delete product attributes, you select them and click “Delete” button.
To sort product attributes you drag and drop the icons in “Ordering” column.
Products¶
Create New Product¶
Navigate to Components -> CM Snipcart -> Products in your Joomla! back-end to access product list.
Click “New” button to create a new product.
We have the following fields in “Product” tab:
- Name: Product’s name.
- Alias: Product’s alias for friendly URL.
- Unique ID: An unique ID to indentify this product (for example SKU). You need to use this unique ID to apply discounts to this product in Snipcart dashboard.
- Category: The category which the product is in.
- Image: Product’s image which is shown in product list and product detail page.
- Cart Image: Product’s image which is shown in Snipcart’s shopping cart popup. If there is no image provided, the main image will be used.
- Description: Product’s description which is shown in product detail page.
- Cart Description: A short description of product, it is shown in Snipcart’s shopping cart popup.
- Stock: Product’s inventory.
- Max Quantity Allowed To Buy For Every Checkout: The max quantity customers are allowed to buy for every checkout. This value is used to generate quantity dropdown list (if you show it). If the value is 0, the default value in the component’s configuration is used.
- Status: This info is currently not used. You can keep the default “Published” value.
- Meta Description: Meta description for search engine optimization.
- Meta Keywords: Meta keywords for search engine optimization. Keywords are separated by comma.
In “Attributes” tab, you can select the attributes of your product. If there is no attributes needed, you can leave the fields blank.
If product has attributes, you need to create a parent product and some child products which have their own specfic attributes. Please see the next section Parent and Child Products for more info.
In “Price & Custom Fields” tab, you can set the sale price or the old price of your product. If your product needs custom fields which cutomers can select at checkout, you click “New Custom Field” button to create new custom field.
You need to give your custom field a name, select its type. There are 4 supported types:
- Textbox: Could be used to ask customers to enter short text.
- Textarea: Could be used to ask customers to enter long text, like notes.
- Checkbox: Could be used for a true-false or yes-no question.
- Radio: Could be used to ask customers to select 1 in many options.
If custom field is required (customers must enter something or select an option), you check “Required” checkbox.
If your product has custom fields, it is recommended that you select “Split into many items” for “If This Product Has Custom Fields, When It Is Added To Shopping Cart Many Times”, so that customers can select/enter many options fo every item in shopping cart.
If your product is shippable, in “Shipping & Tax” tab you set “Shippable” option to “Yes” and enter your product’s weight in “Weight” field (in gram).
To include your product in checkout’s tax calculation, you set “Include This Product In Taxes Calculation” to “Yes” and enter the IDs of the taxes you want to apply to this product in “Applied Taxes” field, tax IDs are separated by a comma, for example “TPS,TVQ”. The tax ID must be the exact same name that is defined in the dashboard or you can use the unique ID that is generated, you can find this ID in the URL when editing an existing tax. Note that the unique IDs will not be the same in Live and Test modes.
Parent and Child Products¶
If your product has many attributes, you must create a parent product and child products which have specific attributes.
The parent product is shown in product list. When viewing product detail, the attributes of the child products are shown for customers to select. The product which customer add to cart is the child product, not the parent.
Example: You sell t-shirt which has many sizes and colors, first you need to create a parent product for this t-shirt, depending on how many variants you have for your t-shirt, you need to create many child products for it. For example if your t-shirt has 2 colors green and blue, every color has 2 sizes small and large, then you need to create the following child products:
- a child product for green t-shirt in small size
- a child product for green t-shirt in large size
- a child product for blue t-shirt in small size
- a child product for blue t-shirt in large size
In this way, every child product has its own image, description, price, stock and unique ID (which can be used as SKU)...
Change Status¶
In product list, you can click on the green or red circle in “Status” column to change product status to “Published” or “Unpublished” state. You can do the same to products and order custom fields.
Delete Products¶
To delete products, you select them in product list and click “Delete” buton and click “Yes” in confirmation popup.
Sort Products¶
To sort products, you click “Ordering” column header in product list, then you click drag and drop the icons in “Ordering” column to sort the products.
Copy Product¶
If you need to to create many products which have similar info, it is faster if you create 1 product and copy it to many products. You can select a product in product list, click “Copy” button, you are taken to product form which has the info of the selected product filled automatically in the form, now you can just edit what needs to be changed.
This function is helpful when you create child products which are often have the same or similar info with their parent product.
Shopping Cart Module¶
Shopping cart module helps you show the current items in customer’s shopping cart, this is done by using Snipcart’s JavaScript API.
Go to Modules section in your Joomla! back-end by navigating to Extensions -> Modules. You can use the module “CM Snipcart - Shopping Cart module” in the list of your modules, it is installed and created automatically when you install CMSnipcart’s package. In case you don’t see shopping cart module in your module list, you can click “New” button on the toolbar to create one.
Just like any other Joomla! modules, in the module setting you can assign the module to a specific position in “Position” option and decide what pages the module is shown in in “Menu Assignment” tab.
You can show the shopping cart module in 3 ways:
- Simple: Only display shopping cart icon and item quantity.
- Dropdown: Display list of items in a button dropdown.
- Full: Display list of items vertically and cart’s total amount.
You can see the sample results in the screenshot below:
Products Module¶
Products module show your products, there are many options helping you configure what products to show.
In Modules section in your Joomla! back-end you find the module “CM Snipcart - Products module” or click “New” button on the toolbar to create one.
If you select “1” for “Products Per Row” option, your products are shown in 1 column (vertically).
You can limit the quantity of products to show with “Max Products To Show” option.
With “Category” option, you can configure to get products from all categories or only get from the selected category.
In “Select Products” option you can configure to get products randomly, get products by their ordering, or get the products which have less purchases first.
Profile Module¶
Profile module helps you show a link to open Snipcart’s login in order to view order history.
In Modules section in your Joomla! back-end you find the module “CM Snipcart - Profile module” or click “New” button on the toolbar to create one.
There are 3 options for this module:
- Type: The link is text or a button.
- Label: The label of the link (or the button). For example, “Your profile” or “Login”.
- FontAwesome’s icon: You can show a FontAwesome icon on the left side of the label. For example you can use “fa-user” icon. You can get the icon’s class name here. If you use FontAwesome icon, FontAwesome must be loaded in CMSnipcart component’s configuration or loaded by other extensions like plugins or your current template.
When you are not logged-in, the icon and the label are shown as the login link:
When you click on the link, Snipcart’s login popup appears, you can login or register a new account:
If you are logged-in, you can see your order history:
If you are logged-in and the Snipcart’s popup is closed, you can see your email displayed in the module. Click on the link again to open Snipcart’s order history.
Orders¶
To check your orders, in you back-end you browse to Components -> CM Snipcart -> Orders.
To view order’s detail, you click on the invoice.
In order detail page, you change change the status of the order or refund the order.
Customers¶
To view your customers, in you back-end you browse to Components -> CM Snipcart -> Customers.
To view customer’s detail, you click on the email address.
In customer detail, you can click on order’s invoce to view order detail.
Order Custom Fields¶
Order custom fields are displayed in “ORDER INFOS” tab which is inserted before “BILLING ADDRESS” tab during the checkout process.
You can use order custom fields to ask customers for various information, for example if they agree with your terms of service, if they need to leave notes for delivery, etc...
In your Joomla! back-end, navigate to Components -> CM Snipcart -> Order Custom Fields.
Click “New” button to create a new custom field.
You can create custom field as a textbox for customers to enter text, as a checkbox for true/false or yes/no question, or radio buttons if you want customers to choose 1 in many options.
When your custom field is radio type, you need to create some options for customers to choose.
To delete options, you click the red X button on the right side of option’s name.
If you check “Required” checkbox, customers must enter something (for textbox type), or check the checkbox (for checkbox type), or select an option (for radio type).
In custom field list, you can change the fields’s statuses by clicking the icons in “Status” column; you can sort the fields by drag and drop the icons in “Ordering” column; you can select the fields you want to delete and click “Delete” button.
Here is a sample result:
Discounts¶
You can create discounts in your Snipcart dashboard. However with Snipcart API, CMSnipcart helps you create and manage discounts right in your Joomla! back-end.
In CMSnipcart, you click “Discounts” in the left menu to access discount list.
Click “New” button to create a new discount.
You provide a name for your discount, select an expire date if you need one, set maximum number of usages if you want to limit how many times this discount is used.
In “Choose what the discount will do” section, there are various options depending what discount type you select:
- A prefixed amount will be deducted from the order: You need to provide the amount you want to deduct from order total.
- A percentage rebate on the total of the order: You need to provide the percentage amount you want to deduct from order total.
- A discount price provided by an alternate price list: This discount type is currently not supported in CMSnipcart.
- A discount on the shipping: You need to provide your shipping’s description, amount and guaranteed days to delivery
- A prefixed amount will be deducted on specified products: You need to enter discount amount and product unique IDs which you want to apply discount to.
- A rate will be deducted on specified products: You need to enter discount rate and product unique IDs which you want to apply discount to.
- Offer free products when a customer buys a specified quantity of a product: You need to enter the required quantity in order to have this discount and the quantity of free items.
In “Choose when the discount should be applied” section, there are various options depending what condition you select:
- Manually enter a discount code: You need to enter a discount code.
- When a specific product is added: You need to enter the unique ID of the required product.
- When an order reach a specific amount: You need to enter the minimum amount.
- When a product is added a number of times: You need to enter the quantity (or minimum and maximum quantity if you check “Specify an interval” checkbox), and the unique IDs of the products if you check “Triggered only when the quantity is reached on a product in particular.”.
- When cart only contains some specified products: You need to enter the unique IDs of the required products.
Localization¶
Snipcart allows us to override the default texts of Snipcart via JavaScript. You can do this easily in CMSnipcart without touching any JavaScript code.
Click “Localization” menu item on the left menu of CMSnipcart, you can enter your custom text for every Snipcart language text. Only the text which has override version is used, so you can leave the fields of the texts you don’t want to override empty.
Translation¶
CMSnipcart only comes with English by default however you can always translate CMSnipcart to other languages.
Installation¶
Before translating CMSnipcart to another language, you need to know install that new language.
In your Joomla! back-end, you go to Extensions -> Language(s). You can see the list of installed languages on your site. Click “Install Language” button on the toolbar to install a new language.
Search for the language you want to install, select it in the list and click “Install” button.
After installing new language, go back to the installed language list, you can see your new language in the list.
You need to remember the language tag of your new language. In the above screenshot, French language package is installed, and “fr-FR” is the language tag of French.
Preparation¶
You can use your favorite FTP software or file managers available in your hosting control panel to navigate to <Joomla! root folder>/components/com_cmsnipcart/language/ folder. In this folder you can see the folder “en-GB”, this is where the language files of English are stored.
In this “language” folder, you create a new folder for your new language, the name of the folder is the language tag. Follow the above example, you create a new folder “fr-FR”.
Go to “en-GB” folder, copy “en-GB.com_cmsnipcart.ini” file in this folder to the new language folder that you just create (“fr-FR” as in the example).
In the new language folder folder, rename “en-GB.com_cmsnipcart.ini” to “xx-YY.com_cmsnipcart.ini”, “xx-YY” is the language tag of your new language, eg “fr-FR”.
Translate¶
Open “xx-YY.com_cmsnipcart.ini” with a text editor and translate the English strings in this file to your new language.
Important note: Joomla! language INI files must be saved as UTF-8 without the Byte Order Mark (BOM). For more information on Byte Order Mark see http://unicode.org/faq/utf_bom.html#BOM
The above instruction is for translating the front-end of CMSnipcart component. To translate the back-end and other extensions, you need to repeat the above steps for the following folders:
- CMSnipcart component’s back-end: <Joomla! root folder>/administrator/components/com_cmsnipcart/language/
- CMSnipcart system plugin: <Joomla! root folder>/plugins/system/cmsnipcart/language/
- Products module: <Joomla! root folder>/modules/mod_cmsnipcart_products/language/
- Profile module: <Joomla! root folder>/modules/mod_cmsnipcart_profile/language/
- Shopping cart module: <Joomla! root folder>/modules/mod_cmsnipcart_cart/language/