PHP-Fusion eShop

Copyright © 2014 J.Falk ( Domi )

Version

1.1
INTRODUCTION
eShop is a functional e-commerce solution made for PHP-Fusion.
eShop has the goal to be simple but still able to suit many needs out of the box.
This software package is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License (AGPL) as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This software package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this software package. If not, see www.fsf.org.

Legal


You are not permitted to remove the footer copyright notice : eShop Đ 2013-2013 without a PHP-Fusion license.
When you run a commercial site you need the Commercial Core License.
For copyright removal please refer to our license purchase page at Commercial Core License (CCL).
For copyright removal regarding PHP-Fusion please refer to PHP-Fusion license information page at License Purchase.
All eShop installations are granted a free CRL upon purchasing a license from PHP-Fusion.
INSTALLATION
Before installing the eShop you need to check the requirements for this version:
- PHP 5.1.2 or higher
- MySQL 4.1 or higher

1. Upload the contents of the files folder to your web server.
Double check so the folder eshop goes to your infusions folder.

2. Login to your site as the Super Administrator. Go to your Administration,
click the System Administration tab, select Infusions and find Eshop in the list.
Mark this in the selection and press infuse.

3. You will need to CHMOD the following files and folders to 777 for the image uploads to work :
4. Go to your Administration,click the Infusions tab.
You should find and cart icon here now, click it and get started !
When adding products there are helpers attached next to each option explaining what it does.
In the settings you will also get a description to the right of what each setting does.
UPGRADING
The upgrade is a smooth process

1. Upload the contents of the files folder to your web server and replace all current files.
Double check so the folder eshop goes to your infusions folder.

2. Login to your site as the Super Administrator. Go to your Administration,
click the Infusions tab, find eShop in the list.

3. Go to settings in your eShop Administration
At the bottom of the page you should find a text saying that an upgrade is available
click this link to upgrade and to complete the upgrade process.
A few features the eShop have
SUPPORT
If you have any questions or problems, please visit The main development site at www.php-fusion.co.uk and post a message on our support forums.

Extra

Bonus material

You will find the connections to these in eshop/purchasescripts
The purchase scripts are not to be considered complete.
They are just proof of concepts atm.
The eshop_jqcategory_panel is a jquery driven tree panel for the handy ones, please note that it dosenīt follow eShop settings.
Documentation

Introduction


The eShop is designed to work with most PHP-Fusion standard installations.
However I do not recommend to run the eShop on fullscreen themeīs as it is for now, around 1024px fixed width is the recommendation.
Please find and download eshop theme if you need examples, iTheme2 will also work well with the shop with default layout.
If you need to run three columns itīs not a problem.
You will need to adjust your product listing per row and the width of from the settings section.
I do recommend that you go to Administration > Settings > Main > Find Exclude Left Panels: or Exclude Right Panels: and paste this section :


The eShop have many settings that can be customized out of the box with no coding at all.
A couple of examples is the buttons and the layout of your product listings.
The eShop will try to have a self explaining experience.
You can find a help icon next to most fields in the admin interface.
If you move your mouse over these a text will appear with a explanation of what the current field do.
Some fields are self-explaining while others could need a explanation.
This readme will also cover the Administration sections with the below chapters.

Products Administration


Almost each field here have a helper that letīs you know what the field are for.

Product title
The title of your item.

Category
All product categories are selected before handling products, the default category is always your selected one.

Your Art.no
If you have a article number for your product, this is the field.
If you do not have a article number each product will automatically get itīs database ID as article number.

Supplier Art.no
Most suppliers have article numbers on the products, it can be nice to have it stored directly with the product in question.

Primary Image
The front image of your product.

Price
Price.

xprice
Filling the xprice will make a strikethru on the ordinary price and mark the new price in red.

Weight
You need to put weight with a . As separator like 0.2 or 0.125 or 1.6 etc.
If you use this value it will be totaled and added to shipping cost if you want your shipping increased per KG/LBS with some methods.
Many costumers are also interested in the total weight of their purchases, itīs a nice service to offer!
You can select between KG / LBS in settings.

Dynamic
This is a double blank field section.
These input fields can have any value.
Itīs good for things such as sizes,lengths,weights etc.
The button Add value will populate the content of this field dynamically with any number or letter you put in.
You can write size in the left blank and then start to type S and click the Add value then type M and Add value and keep going until you have all sizes available in the list.
Or you can write height and even combine 10 FT 1M etc in the populateable list.

Colors
This was a tricky thing to make. A selector can be very hard to pick close or the right colors.
I ended up with a function that have a total of 135 colors in the list, pick each color you have available for your product.
You can find the color you need fast by left clicking on the arrow next to the list and push the first letter of your color key on your keyboard, push enter to insert it and keep going until you covered what you need.
The list will automatically populate with each color you select.

Order
Displays or selects your current default product order.
If you add a new item it will always go last per default if left blank.

Sellcount
Current sellcount of a product, sellcount will increase on put orders. It will also decrease on deleted orders.

Campaign
If you want a product to be listed as a Campaign you can simply toggle it here.
Campaign ribbon will be shown and it will be listed in the dedicated campaign section.

Allow coupons
You can exclude a product from your coupon system with this option.
All products will be included per default.

Image gallery
Each product you add also have a gallery option.
You can manage these from top menu Gallery.
Currently at least 3 Images are recommended for best view. You need to add images to each product like it was a photo gallery.
The method was decided to enable ordering for each image in your product gallery's.
It gives you more control over the images.

Version
If you sell programs or similar that have versions you can use this.
If you leave it empty nothing will show.

Demo
URL to a demo you could have.
If you leave it empty nothing will show.

Show stock
Let people know if your product is in the stock or not.

Stock
Displays your current stock status.
If you have Show stock off this wonīt show.
0 Items will display stock3.png (empty boxes)
5 items or less will show stock2.png (yellow boxes)
10 items or more will display stock1.png (green boxes)
The stock will be automatically adjusted if an order is deleted.

Delivery time if stock is empty
Delivery value can be anything from 5 - 30 days.
This is to inform the customer that ordinary shipping will not be valid since the product is out of stock.
The shipment method will otherwise specify delivery times on checkout.
Just leave blank for no new information.

Buyable
Setting buyable to No will make the ribbon Incoming appear and the cart options will not be available.

Active
Setting this to Disabled will remove the product from your lists.

Add to cart
Allow or disallow the Add to cart button.
This are useful for PayPalīs customized return scripts for single item purchases or similar solutions where you do not want or need a cart to be active.

Allow to buy multiple items
Allow or disallow purchase of multiple items of a product.

Default number of items
How many items should be in the no of items box per default for this product.
Nothing will be shown if Allow multiple items is off.

Allow buy now button
Allow or disallow the Buy now button.
This is PayPal only for single product purchases that calls the buynow.php file.
It was implemented as a cart override when you plan to sell licenses, programs etc.
Remember to Disallow shopping Cart,Dynamics,Quantity for this product type.

Callback script file
The callback script file are only in conjunction with the buy now button.
Your customized scripts can need to be in the folder infusions/eshop/purchasescripts.
Any .php file that are put there will appear here.
the CRL , personalfiles scripts are there included as examples for you.
Default callback script file from cart actions are defined from your settings section.

Access
Select the user group that will be allowed to view this product.

Short description
Show a short product introduction text.
This can be disabled from the Settings section "Use and display product intro text".

Full description
Complete product description text.
Embed codes and even html codes works here.
You can display videos or even have complete HTML table layouts for each product.
You can try to embed a Youtube video to see the results.
To make a new row you need to insert a
if you do not use HTML.

Advanced tabs feature
These are the customizable description tabs.
If you have a lot of info you can add it to these tabs.
One could be named Features next could be License and third could be Changelog etc.
Embed codes and even html codes works for each tab.
You can display multiple videos or even have complete HTML table layouts for each product.
You can try to embed a Youtube video to see the results.
To make a new row you need to insert a
if you do not use HTML.

Gallery Administration


Each product will create a editable album for your product in here.
If you click on a album/product in question you can start uploading images with valid titles.
the images will resize and go by your settings from the settings page.
You can and also select and arrange the order of each image.
Remember that the image you upload to your product is always the first one.
To make it easier if you have a lot of products I added a quick search function in this section.
Item names, Art.no and Supplier Art.no works in this search.

Category Administration


This is a complete category system with full hierarchy function for unlimited sub categories.
You can add your own category images to each category by uploading them to infusions/eshop/categoryimgs.
If you populate your image folder with your category images they will appear in the image fields droplist.
The displayed size of these images are set from your settings section (Category image height/width ).
You can also select to have the categoryīs displayed as buttons rather than images from the settings.
You can set access on categories and also disable whole category sections.
If you have a main category with sub categories products will not be listed in the first main category.
You need to use the featured section to add products to a main category from sub sections.

Coupon Administration


When you click on coupons tab the coupon system will automatically generate a 15 digit random code based on both numbers and capital letters.
To make a new code you can simply click on the coupon tab again.
The coupon system supports both fixed sum discountīs and percent based discountīs.
Our PayPal plugin is configured to support these methods along with our other pre-configured payment options (Invoice,Prepayment).
To have certain products excluded from this system you need to edit each product you need to exclude from the products admin.
The Coupon system does not take shipping or handling surcharges in to account, only cart items are viable for discounts.
Coupons are only available to registered members.
Each coupon that are used can only be used once per customer.
You can also edit a customer in the customers section to remove specific coupon codes that have been registered as already used if needed.
You can set a wide range of valid periods for your coupons.

Code
The field for your coupon code, it dosenīt need to be the system generated one.
Itīs required that it contains only letters and numbers.

Title
Title is what you will name your campaign to.
It can be anything from a discount that is percent based or X-Max campaign 2013 that only runs on X-Max eve etc etc.

Type
This can be Percent or Sum.
If you enter 10 and select percent would result in a 10% discount.
If you select sum it would result in 10 (Your currency setting).

Value
This one need to be in absolute numbers.

Start / End
Select the time span of your coupon validity.

Active
Enable or Disable a specific coupon.

Settings Administration



Paypal E-Mail
PayPal E-mail if you use PayPal as a payment option.

Default return page
The default file to handle returns from PayPal.

VAT
Standard rate of VAT/TAX in numbers if you have 25% VAT you type 25.

Product prices listed Inc VAT
If you list your products with VAT included, set this to yes.

Default currency
The currency for all your products.
The currency follows PayPal currency standard.

Timer for new ribbon
Select how long you want the new ribbon to be displayed.
It can also be disabled from this setting.

Free shipping
The value you enter here will gives your customers free shipping if their cart value reach this value.
A 0 value will disable this function.

Default weight scale
Selected option displays weight numbers in this scale.
Currently KG or LBS are selectable.

Share buttons on
If you want the builtin share buttons in product detail view.
You have Facebook,Twitter,G+.

Buttons in product listings
This allows you to slimeline the main shop listings if you want.
It will toggle the display of buttons such as add to cart,Buy now,info,colors,quantity etc.

Width of product itembox
You can have values either like 160px or 100%.
Itīs recommended to have a fixed width else your image sizes and other options risks to break the layout.
You also need to consider how many items per row you list.

Height of product itembox
You can have values either like 330px or 100%.
Itīs recommended to have a fixed height else your image sizes and other options risks to break the layout.
Use and display product intro text
If set to No only a centered image will be shown in product listings.
Enabled you will need to use the short description field when adding products.

Intro text width
You can have values either like 200px or 100%.
Itīs recommended to have a fixed with for optimal layout.
You need to consider how many products per row you list.

Use and display product price in main listings
If set to No the prices will not show when browsing categories or displaying products.
The users will need to click on a product to see the price.

Products on first page
Sets how many products you display on the eShop frontpage.
If you use the featured function this dosenīt count.

Itemīs per row
Selects how many items per row to display.
You need to take theme width and both description text, image sizes in to consideration here.

Ratios
Keep the uploaded images aspect ratios when browsing products.
This is good if you use a photo program or similar to set a pre-size for your images before adding them to the shop.
Disabling this function will force the fixed ratio you enter to displayed image width,height.

Displayed image width
The displayed image width when browsing products (Ratios need to be off).

Displayed image height
The displayed image height when browsing products (Ratios need to be off).

Image width in detail view
The width of a larger picture when viewing a product (Ratios need to be off).
Also see imageclass in eshop.css for details regarding product albums.

Image height in detail view
The height of a larger picture when viewing a product (Ratios need to be off).
Also see imageclass in eshop.css for details regarding product albums.

Max image width
Max width of a uploaded image.

Max image height
Max height of a uploaded image.

Image size
The maximum size allowed to upload images.

Width of the thumb
Width of the uploaded image thumb.

Height of the thumb
Height of the uploaded image thumb.

Width of the thumb 2
Width of the uploaded image thumb 2.

Height of the thumb 2
Height of the uploaded image thumb 2.

Button colors
Many buttons in the shop have itīs own color options.
You can select to have specific colors on the following buttons :
Buy Now , Checkout , Cart , Add to Cart , More info , Return.
The selectable colors are :
Theme Default,Blue,Green,Red,Magenta,Orange,Yellow.

Categories
On or Off.
If you do not use the category system products will be listed in the left column instead.

Show cat images or buttons
When listing category's we can either show an image you have selected to each category or the built-in buttons with category name in it.

Products to list per page
Sets how many products that will be listed per page.

Category items per row
Selects how many category items to list on a single row.

Category image height
The displayed category image height.

Category image width
The displayed category image width.

Link target
For new window type _new for self type _self etc.

Folder links
Select true to make a middle subcategory populateble with content.
This setting is best used when you have a advanced strategy to combine the Features section on main category's that have subcategories.
Subcategories will always be listed below a Main category selection.
If you have a main category with subcategories products will not be listed in the first main category.
You must use the featured section to add products to a main category from sub sections.

Highlight selected
If true categories will be highlighted when selected.
See eshop_menu_panel/eshop_menu_panel.css for styles.

Use cookies
Use cookies to save category selection.

Show lines
Show lines leading to a category in the tree.

Show icons
Show and allow the selecton of a present category image in the tree.

Status text
Displays category names in the statusbar instead of the url.

Close same level
Only one category within a parent can be expanded at the same time.

In order
If on parent category's are always added before children.

Terms & Conditions
The Terms & Conditions your customers need to approve before checking out.
HTML is allowed.

Featured


In the Featured section you can select what products to promote.
Itīs two separate system in the same interface.
1, Featured products.
2, Featured banners.
In the first window you will need to select what section to handle.
It can be either the front page or a specific category.
If you have a Main category with subcategories the system will also list all products from these subcategories.
If you have a main category with subcategories products will not be listed in the first main category.
You need to use this featured section to add products to a main category from itīs sub sections.
The front page selection will let you chose any product from all your categories.
You can set the desired order for both items and banners.
The system is designed to instantly give you a preview how it will list for each banner or product you add.
The products you add will be connected to your shops product ID.
When the shop loads either index page or a category it will always check for content in the featured sections first.
The banner system have a total of three methods to connect banners with content.
1, Attach a banner to a selected product from all current subcategories.
2, Attach a banner to a selected category from all current subcategories.
3, Attach a banner to a custom URL of your choice.
If you add only one banner to a category the slideshow will be disabled and the title, banner will be shown on top of all products in that selected category.
If you add a custom banner you will only show the uploaded banner.
The banner system is designed to hold banners with dimensions of 728*90px.
If you need to change this you need to modify the featured banners section in eshop/eshop.css.
You also need to modify this css section manually to change background image or colors.
If you change dimensions you will also need to find buildeshopbanners function in eshop/functions.php to change image width and height.
To create a good featured sections attached to main categories where you have subcategories you will need to have folder links set to true.
That way would also be the way I designed and planed how to use the featured section in conjunction with categories.
If you add a featured section to a main category that also have products added to it, you could be listing certain items twice on the same page.
The featured items are listed the same way as ordinary products.
The system just actīs as a category / front page - what to display in what order override.
The eShop will automatically expand all subcategories the belong to the main category for this reason.
The featured banner system is a different story, you can add banners independently above all product categories and promote special items in each and everyone of them since you link in to the items.

Payment Administration


You have three pre-made methods delivered as default.
Invoice.
PayPal.
Prepayment.
The payment methods can be added and configured in two ways.
The first way is to create a file with your payment handler codes.
You can place any customized scripts in the folder eshop/paymentscripts.
The payment scripts need to be handled as PHP-Fusion panels.
All these scripts are are run by eshop/checkedout.php.
You can see the included scripts for various examples.
All current payment scripts have a image attached to it.
To add additional icons you need to put your images in eshop/paymentimgs.
The other way to configure and add payment scripts is with the built-in text field.
In this field your can add HTML, PHP etc, anything goes.
If you have any information in the customized code field any selected files will be ignored.
Surcharge is a field where you can add a single extra cost for handling an invoice or creditcards.
The description field is pretty much what it says, you can add a small description of your payment method.
An option to toggle active on or off is also available for each method here.

Shipping Administration


In the shipping section you can add both categories and methods for each category.
If you have multiple UPS methods you can order them by adding them to your UPS category.
The system will currently not make any difference for categories all methods will be listed straight up.
The eShop will be able to calculate total order weight if you add it to each product entered.
You will be able to add the shipping methods with the following options :

Shipping method
This is the name of your option.

Delivery time
How long will they need to deliver with this option. Example : (1 - 4 Days).

Destination
You have three options where shipping is allowed to here.
International.
National.
Local.

Min weight (System setting scale)
This is merely informational atm. The system does not check this vs incart weight.

Max weight (System setting scale)
This is merely informational atm. The system does not check this vs incart weight.

Initial fee
How much will you charge for the selected shipping method.

Fee per (System setting scale)
How much will you charge extra for weight per KG/LBS.

Active
Allows you to toggle shipping methods on or off.

Customers


The customers section is an important element for your registered customers.
Any member of your PHP-Fusion site will automatically have itīs own customer data saved upon a completed order.
Guest who shop will naturally not be registered other than in the order information.
You can manually add customers in here and connect them to a existing PHP-Fusion user.
The customer database is searchable for both first and last names to make it easy for larger databases.
If a coupon is used by a customer it will also be registered in this section for that customer.
You can edit the customer and also remove individual coupon codes to let them be used again by this customer.

Orders


The orders section is where new and unhandled orders are stored.
The orders are sectioned in two sections.

Paid orders that are waiting for delivery.
If you have scripted a confirmation that a order have been paid but yet delivered it will be in here as a priority order.
You can also edit orders and set it to paid manually when you need to verify payments.

Orders that are waiting for payment confirmation.
If you need to verify payment before handling an order itīs listed here.
Only you have a confirmation you need to edit the order and flag it to paied.
The orders are still visible on the orders page with or without the paid flag.
For an order to be considered completed and removed from this page it need to be flagged as Processed.
This is done by selecting completed when viewing orders here.
You also have an option to add some notes that is for Administration eyes only to each order.
All orders that are placed will be given an OrderID and connected to the customer placing the order if registered.
You can also instantly print any order places with one click on the visual printer.
If you delete an order both sellcount and stock status will be adjusted for each item sold.
Orders are quick sortable from A-Z , 0-9.
You can also search for both Order Id and Customer names to find orders.

Order history


This is the section where all handled orders endup.
Orders will be listed by Year / month down to days in the selected month.
On the first page here you will see stats on total amount of orders for each month sorted by year.
If you click in on a month you will see total order stats by days for the selected month.
When you select a day the orders for that day will be listed.
You can print, edit delete etc just as any order handling from this section.
You can also search for both Order Id and Customer names to find orders in this section.

Changelog 1.1


* The shop can now handle . Separated prices. ( 9.49 ) etc
* All instances with http://"+window.location.hostname+"/ have been changed to '.$settings['siteurl'].' in functions, it will add better support for subdirs.
* Cart is no longer visible on checkout when purchasing buynow products.
* Buy now products will from now on be saved to the records as intended.
* Changed ouid from int to varchar for guest IPīs to be stored, this change also fix the no orderID bug when a PM is sent from guests that shop.
* Fixed a bug with filters that would reset on category change.
* Customer phone and fax fields have increased from 10 to 20 chars.
* Fixed a bug in productsearch.php where pagenav would not be active if filters had not been initiated by user.
* Fixed a bug where pagenav could go inactive within categories and featured products.
* Added an automatic replace of , to . for weight when saving products to avoid faulty input and denied messages.
* Added an automatic replace of , to . for price when saving products to avoid faulty input and denied messages.
* Added better support for other locale special characters in the preg_match section for product handling.
* More special chars are allowed in the Title and Dynamic fields.
* Added a category check to admin photo galleryīs edit link.
* Guestīs customer names is not linkable in to the customer DB anymore.
ACKNOWLEDGEMENTS

A huge thanks goes to people who helped me to test and made the Development for this shop possible


Happy Svensson {KEFF}
Helmuth Mikkelsen {Helmuth}
Frederick Chan {hein}
Arda Kilicdagi { Arda }
Simonov Konstantin { Jikaka }
Nicolae Crefelean { Kneeko }
Philip Daly {Hobbyman}
Tyler Hurlbut { Tyler }
Grimloch
And to all my friends out there, none mentioned - none forgotten

{ YOU ? } > Visit our thread @ www.php-fusion.co.uk and contribute with improvements!
The ribbon concept I use comes from : http://css-tricks.com/snippets/css/corner-ribbon