StartToEndTutorial
- A standard buildout based installation of Plone. We tested on Plone v3.3.5. There is a port to Plone v4.0 available on the Plone_v4.0 branch, but it isn’t massively tested.
- Git installed. On Unices such as Debian Linux et al, this is easiest installed using something like `apt-get install git-core`. On Windows, there is a project called msysgit which at the time of writing works very well for client-only usage and there is a GUI for it called TortoiseGIT. If you want to set up a full SSH secured GIT server on Windows however, a cygwin based GIT works perfectly.
- You probably need root access on your deployment machine.
- And you really, really ought to test this on a local test machine first in case something really bad happens. We personally run VirtualBox based copies of our internet services which we synchronise using a 1-to-1 rsync, so it lets us play and undo any damage we do with real server copies (it also acts as a convenient backup which can always be rsynced the other way if needs be).
Be aware that some parts of Easyshop is of alpha code quality at present: it generally mostly works, but there are occasional bugs and glitches most of which are listed on the issue tracker. If you find a bug not listed there, please create an issue describing the bug and how to repeat it. Developers interested in Easyshop will tend to fix bugs relevant to their particular interest when they get round to it which may take weeks or months depending on their free time.
If you want a bug fixed quickly, you have one of two options. The first option is that you fix it yourself and submit it as a patch to the issue tracker where someone will eventually review it and apply it to HEAD (here is how to attach files to issues on Github). The second option is if you don’t want to or can’t fix it yourself whereupon you can contract one of the companies listed in CommercialSupport who will be able to quote a price for the work and how much lead time there will be if they are currently occupied elsewhere.
Note that unlike other source control management systems, GIT is entirely distributed. In other words, you can happily proceed with commits to your own local GIT repo clone without having to wait for HEAD to be updated frequently. It is due to this freedom from centralised control that Easyshop was migrated from Subversion to Git during the summer of 2010.
Note that we would absolutely love to fix all remaining issues in the issue tracker and get Easyshop up to full release quality as an egg in the Python Package Index. If anyone is willing to sponsor this work to finally deliver a fully featured e-Commerce platform to Plone please contact the project owner!
Since there aren’t any released eggs for easyshop.* you can install the latest easyshop.* eggs using a buildout part:
[easyshop]
recipe = zerokspot.recipe.git
repository = git://github.com/ned14/Easyshop.git
as_egg = true
# optional parameters
#rev = 8389876388712a14cf14
#branch = Plone_v4.0
paths =
src/easyshop.carts
src/easyshop.catalog
src/easyshop.checkout
src/easyshop.core
src/easyshop.criteria
src/easyshop.customers
src/easyshop.discounts
src/easyshop.groups
src/easyshop.information
src/easyshop.kss
src/easyshop.login
src/easyshop.management
src/easyshop.order
src/easyshop.payment
src/easyshop.shipping
src/easyshop.shop
src/easyshop.stocks
src/easyshop.taxes
...
Note: The paths can change depending on the branche you use … please check github first for the correct path. These path examples rely on the master branch
Now add your part to:
[buildout]
parts=
...
easyshop
and the EasyShopTranslations product to your instance products section like this:
[instance]
...
products =
...
${easyshop:location}/products
Your Plone installation is probably in something like `/usr/local/Plone/zeocluster` if you used the default settings for a ZEO deployment, so we’ll assume that. Firstly you need a copy of SVN HEAD of Easyshop as it is still at beta quality, and you’ll probably find a bug we haven’t as it always seems to be, so as root:
cd /usr/local/Plone/zeocluster/src git clone git://github.com/ned14/Easyshop.git
Leave that run till it’s done. If you’re on Plone 4, then do:
git checkout Plone_v4.0
Now do:
cd .. nano buildout.cfg
We now need to add a lot of easyshop stuff to the buildout process, so:
eggs =
...
easyshop.core
easyshop.carts
easyshop.catalog
easyshop.checkout
easyshop.criteria
easyshop.customers
easyshop.discounts
easyshop.groups
easyshop.information
easyshop.kss
easyshop.login
easyshop.management
easyshop.order
easyshop.payment
easyshop.shipping
easyshop.shop
easyshop.stocks
easyshop.taxes
...
zcml =
...
easyshop.core
easyshop.carts
easyshop.catalog
easyshop.checkout
easyshop.criteria
easyshop.customers
easyshop.discounts
easyshop.groups
easyshop.information
easyshop.kss
easyshop.login
easyshop.management
easyshop.order
easyshop.payment
easyshop.shipping
easyshop.shop
easyshop.stocks
easyshop.taxes
...
develop =
...
src/Easyshop/src/easyshop.core
src/Easyshop/src/easyshop.carts
src/Easyshop/src/easyshop.catalog
src/Easyshop/src/easyshop.checkout
src/Easyshop/src/easyshop.criteria
src/Easyshop/src/easyshop.customers
src/Easyshop/src/easyshop.discounts
src/Easyshop/src/easyshop.groups
src/Easyshop/src/easyshop.information
src/Easyshop/src/easyshop.kss
src/Easyshop/src/easyshop.login
src/Easyshop/src/easyshop.management
src/Easyshop/src/easyshop.order
src/Easyshop/src/easyshop.payment
src/Easyshop/src/easyshop.shipping
src/Easyshop/src/easyshop.shop
src/Easyshop/src/easyshop.stocks
src/Easyshop/src/easyshop.taxes
...
# You probably want this on: debug-mode = on
Lastly:
cd products ln -s ../src/Easyshop/products/EasyShopTranslations EasyShopTranslations cd .. bin/buildout
You should now be ready to run, but if you want a currency other than Euro, British Sterling and US Dollars then you need to do one more thing:
nano src/Easyshop/src/easyshop.core/easyshop/core/config.py
Here you can adjust various parameters for Easyshop, so if you want an extra currency you simply add it to the CURRENCIES section. You may also wish to edit VAT_COUNTRIES if you don’t live in the EU, and DEFAULT_COUNTRIES if the countries you wish to deliver to aren’t in the EU or USA. Lastly at the bottom is the all important PAYPAL_URL which lets you choose the Paypal Sandbox which is absolutely essential for testing that the shop absolutely & definitely will work with your customers in every conceivable scenario (e.g. if they are rejected, or they are using a stolen credit card etc).
Personally I find that running Zope directly instead of using bin/plonectl is the easiest for debugging, so do:
bin/plonectl zeoserver fg & bin/plonectl client1 fg &
… to start and a simple `bin/plonectl stop` to stop. This method prints all debug output to the terminal so you can see exception backtraces and such: very useful.
Get into the ZMI and create a Plone site – you probably don’t want to do this first time with an existing site until you’ve familiarised yourself with Easyshop’s quirks. Once in the site, go to portal_quickinstaller or View/Site Setup/Add-on Products and add the Easyshop product. Make SURE you fill in the Mail section of Site Setup with CORRECT values as Easyshop will need to send email to you and the customer, and having wrong details here will prevent many site error exceptions later.
Now you’ll get an “Easyshop” item in the Add New drop down menu. So go ahead and add an Easyshop, giving it a title of “Shop” and a Shop Owner of whatever you want to appear on your product invoices. On the Misc tab most options are fairly self explanatory, but to clarify some of them you can choose “Gross Prices” if all the product prices you enter already include taxes, but for most people it’s easiest to leave this turned off. If you are VAT registered and wish to allow VAT registered entities not in your local economy to have your local VAT rate removed, you can choose your local VAT country ID so Easyshop knows when it ought to charge VAT or not. Lastly, if you want Paypal as a payment option, you MUST fill in the Paypal account email address on the Payment tab.
So there you have it: your first Easyshop shop! After publishing it you ought to test it with an anonymous browser (i.e. one not logged in). I personally use IE8 for that as I never use IE for anything else :)
Easyshop uses categories to group products for your customers, whereas it uses groups to group products for you the admin only. Hence your products must always belong to at least one category for customers to find your product.
Before creating a category, you firstly need a Product to go into it. Click on Products in the Manager menu and do Add New/Product. Give it a Title of “Widget”, a description, image and base price (say 100). Choosing the Advanced tab lets you choose Stock Amount, whether the stock is unlimited (for say an electronic good or service), whether the item is for sale and its sale price, whether it has accessories and so on. Choosing the Size tab lets you enter the all important weight and box dimensions which are so crucial to calculating Shipping. Give it a stock amount of 5 and a weight of 10kg, then hit Save.
Next we’ll add some product options. Choose Product Properties and type “Case” and add the property. In the new Case field type “Gold Plated” in the Title field and type 50 into its price before hitting Add. Note that you can have product properties inherited from groups, so if you were selling say T-Shirts then you’d have a group of T-Shirts defining a common product property of “Size” which enables all products in that group to have the same product properties. Return to the view, and don’t forget to publish it.
After all that you should see something like this:
You’ll surely note that the price is €125 rather than the €100 originally specified – this is because of the default VAT customer tax which is defined to be 25% in a new Easyshop installation (you can remove this simply by choosing Taxes from the Manager menu, then the Contents tab and delete as usual). Note also that your “Case” property is available, and if you choose the drop down menu you’ll see “Gold Plated” as an option costing an extra €50. If you choose this, note that the overall product price is now €187.50 which is (base price + option) x (100 + customer taxes).
Now you need a category, so choose Categories from the Manager menu on the left. Type something like “Appliances” into the box and click on Add Category. Now choose the link that appears below it, then the Products tab and tick Widget before saving. Choose Appliances in the Categories list on the left and you should see your Widget. Publish the category now, and check that everything works using a non-logged-in browser by entering the Appliances category, choosing a Widget and adding it to your cart. If you view the cart using the cart summary in the right column you should see something like this:
You’ll surely note a few things from this. Firstly, shipping and payment method both cost €0 no matter what options you choose from the drop down box – this is because we haven’t set these up yet. Secondly, there is a bug where the incl. Tax value isn’t correct – I’ll get round to fixing this soon.
Before we leave this section you should choose “Carts” from the Manager menu. You’ll see a list of carts with their items along with their last modification dates – these are the carts which your website’s visitors created but never sent to order. Most of the time this is because your customer went elsewhere, maybe because you didn’t have a certain item in stock or maybe because they found a cheaper price elsewhere. Sometimes though it can be because the customer is building a cart over a few days. Either way, watching this can be an invaluable source of data when monitoring the performance of your shop.
One of the best parts of Easyshop is its comprehensive support for differing shipping methods and prices. Setting these up is extremely easy, so start by choosing Shipping Prices from the Manager menu which will show you “There are no shipping prices”.
Remedy this by adding the following Shipping Prices:
- “Electronic Delivery” costing €0. Once in the shipping price item page add a new weight criteria choosing < 0.01, then a further “Combined Length and Girth” criteria choosing < 0.01.
- “Courier to Ireland” costing €15. Once in the shipping price item page add a new “Country Criteria” choosing Ireland.
- “Courier to UK” costing €20. Once in the shipping price item page add a new “Country Criteria” choosing the United Kingdom.
- “Courier to Europe” costing €35. Once in the shipping price item page add a new “Country Criteria” choosing all European countries except Ireland and the UK.
- “Courier to Rest of World” costing €75. Don’t add any criteria here.
Enter the Shipping Prices Contents tab and select all the items and click on “Change State”. Tick “Include contained items” and change the state to “Publish”.
Now refresh the view in your not-logged-in web browser – you should see that shipping now has a value! Try choosing different countries using the Country drop down box: choosing Ireland should choose a shipping of €18.75 (€15 + VAT) via AJAX, some European country such as Austria should be €43.75 (€35 + VAT) and choosing the USA should be €62.50 (€50 + VAT).
Those familiar with VAT will know that VAT is not to be applied to customers outside the EU, so to fix this choose the Taxes option from the Manager menu and then choose VAT. Add a new country criteria including all European countries (so all but the USA). Note how VAT is now applied only when the destination is a European country, but is no longer applied when the destination is the USA.
By applying similar criteria you can configure different VAT rates according to destination country (which is now the law if your sales exceed a certain amount annually). You can also apply criteria which change price according to item weight or size, or have one set of customers get preferential shipping rates (e.g. if they regularly buy in bulk from you). One of the most obvious criteria is to set up two shipping methods i.e. “Standard 2-3 day delivery” and “Expedited next day delivery” and then have the shipping prices select on shipping method.
Remember that shipping prices are chosen in consecutive priority, so the “Courier to Rest of World” we added above was added last and is therefore placed at lowest priority. As it has no criteria, it will always be chosen if no other prior shipping price has its criteria met.
Lastly, setting up Payment Prices is identical to Shipping Prices. Easyshop comes with a range of default payment methods – simply delete those you don’t need. For any reasonably small shop, deleting all but Paypal is a good idea as Paypal will also process credit and debit cards for you if you register the account as a business account and unless you’re processing serious volume, Paypal’s fees will usually be cheaper than a merchant services account.
You now have a fairly complete shop, albeit with just one product. Now let’s try placing an order in the non-logged-in browser by hitting the Checkout button. The standard Plone login page will now appear and the site will have to allow registration to permit a new user to register. Once completed Easyshop will show the “Please add a new address” page which rather annoyingly currently requires the user to reenter their name and country.
You now get to choose between shipping methods, then between payment methods before being presented with the final order summary screen like this:
Hitting “Complete Order” brings you to the standard Paypal order screen where you either fill in your credit/debit card info or your Paypal account details. After completing the order you are returned to this screen:
Easyshop has an account and order management screen, so let’s look at that using the “My Account” link:
Choosing Orders shows the details of the order you just placed:
So far so good. If you check your email you will find that the Plone site administrator (unless you overrode it in the Shop settings) will have received an order placed email.
Return to your admin view of your Plone – in your Review List there is now an order:
Choosing this order shows the following order summary screen:
You’ll note the State of “pending” at the top right. This is the standard Plone workflow customised for ordering, so “pending” means that we are awaiting payment and/or the user didn’t pay for the order. This becomes “paid” when the payment processor sets it as such (or you do so manually), and “sent” when you have dispatched the item whereupon another email is sent to the customer telling them so. You can also cancel or close the order if you wish.
The final section of this start-to-finish tutorial is how to set up the zero rating B2B VAT support. Firstly I ought to explain/refresh your mind about VAT – what it is and how it works in the EU.
In the EU, because governments like to have their own special VAT regimes with completely different rules as to what VAT rate is charged for what product for their own economy, there is no way of mapping VAT rates between countries. So say for example that the UK has a VAT rate of 17.5% and Denmark has a rate of 25% – a luxury product like a computer will likely attract the full rate for each country. However a book (if educational/literary) gets a special 0% rate in the UK, whereas in Denmark it still gets 25%. Worse still in some countries the purpose of the item matters, so the UK traditionally reduces the rate to 5% when an item is used for repair even if when used in a different context it would be full rated.
When say a German person buys a product in a shop in say France then they pay the French VAT for that product and the French government pockets the cash. For the average citizen this is fine because all consumers are supposed to pay VAT somewhere and most consumers buy locally rather than from the lowest VAT rated country (excepting the internet, but new rules have just been brought in in 2010 setting completely different VAT charging rules for distance selling in order to avoid countries using low VAT to attract business). However, VAT is never supposed to be applied to business consumption, but to avoid consumers dodging paying VAT what happens is that everyone including businesses pays VAT and then the business reclaims the VAT they paid from the government.
Of course this is fine for when a German business is reclaiming VAT they paid on goods bought in Germany. It is not so good when a German business has paid VAT on goods bought in France because now they must reclaim that specially from the French government. Needless to say most governments have a huge incentive to make reclaiming VAT by non-local businesses as difficult as possible, and most businesses simply don’t bother especially as it takes nine to twelve months before they repay you (and you must absorb any currency exchanges losses which occur in the meantime).
Rather than fix this problem by forcing local governments to refund all VAT claims no matter the source (the government services loudly objected), or even better to harmonise VAT across all of the EU (not the rates, just what rate is applied to which product categories), they came up with yet another scheme which is to allow VAT registered entities to zero-rate the VAT they charge when selling to another VAT registered entity NOT based in the same country according to a series of complex rules. So, to clarify, a German business must charge VAT when selling to other German businesses, but it may zero-rate the VAT tax when selling to any EU business that isn’t German.
<rant on>
Complex no? Well it gets even better, because what I just wrote applies to physical products which are conveyed physically only. Other rules apply if one is supplying services, and still other rules again apply for certain categories of good or service such as gasoline and insurance. All of these extremely complex rules are designed to avoid VAT fraud but to be honest, this is very much building a skyscraper out of straw because you wouldn’t have any of this efficiency-killing bureaucracy if European governments weren’t so selfish and prone to believing that their particular slightly different implementation of VAT is sacrosanct.
<rant off>
If you want to know more about whatever insane rules are currently in force, please consult http://en.wikipedia.org/wiki/European_Union_Value_Added_Tax which will probably remain fairly current.
What I have implemented into Easyshop is a drastic simplification of the rules: you tell Easyshop in which country you’re VAT registered in the Shop settings which enables a new VAT id box in the cart. Customers filling this in – if the country code is different – cause ALL consumer taxes to be disabled which is an effective zero-rating. Note that default taxes continue to be applied i.e. not the consumer ones.
Under the current rules for any business with typical revenues to another country not exceeding €100,000 in a year then this simplification ought to work just fine. If you do exceed it then you’re required to register yourself for VAT in that foreign country and to charge that country’s VAT rate using that country’s native currency.
Currently Easyshop cannot handle this situation as it only knows of one “home” country – however support would not be hard to add. Also, currently Easyshop cannot handle multiple currencies simultaneously which is a problem only with the UK, Sweden and the Eastern European countries. Support for this would be harder to add, but it could be done.
Once you have VAT support turned on you’ll get the following in the order screen instead:
As you can see, it inserts an iframe containing a query of the VAT number with the EU’s VIES service which will tell you if the VAT number is valid or not. Seeing as you have the legal responsibility for checking the validity of VAT numbers, this particular feature saves a LOT of time.