Contribution:Stock by Attributes

From Zen Cart(tm) Wiki
Jump to: navigation, search

Contents

IMPORTANT WARNING

These notes apply to the versions of Stock by Attributes from 4.0 to 4.7. They are not guaranteed to be correct for the MULTIADD version, which appears to be unsupported.

Introduction

This add-on is based on a Zen Cart contribution by dafonz (products_with_attributes_stock), which was adapted by danielcor for Zen Cart 1.3 and further adapted by kuroi for 1.3.5, 1.3.6, 1.3.7 and 1.3.7.1.

This current version (4.7) is designed specifically to work correctly with version 1.3.8 of Zen Cart and is unlikely to work with earlier versions. If you are running Zen Cart 1.2.5-1.2.7d, please use the "products_with_attributes_stock" add-on by dafonz. If you are using versions 1.3.0 - 1.3.0.2 please use "Stock Attributes by danielcor". If you are using version 1.3.5, please use version 4.2 of this mod, for 1.3.6 use version 4.3 of this mod. Versions 4.4, 4.5 and 4.6 should be compatible with versions 1.3.7 and 1.3.7.1 of Zen Cart (though obviously the latter versions of Zen Cart and this add-on are recommended).

What This Module Does

This add-on allows a store owner to set a stock quantity for each variant of a product. For example, if you have three sizes, large, medium and small, this module will allow you to keep track of all the different quantities. It will work for a virtually unlimited number of amount of attribute combinations. For example, if you offered cotton or polyester shirts in green, red or blue and small medium or large sizes, this add-on would allow you to enter and maintain a separate stock level for each of the 18 possible combinations.

What Version 4.6 of the Module Does

Previous versions of the module insisted that once installed you maintained stock at attribute level for products with attributes (otherwise the products would be treated as being out of stock). This version (4.6) gives you the choice of managing stock at a product or an attribute level on a product-by-product basis.

If you enter stock for any combination of product attributes (product variants), stock calculations will done using attribute level data. Any attributions that have not been set up will be treated as having zero stock. However, if you have no product variants set up, or delete them all, stock for that product will be calculated based on its overall product quantity.

Installation

Create a new database table and a new configuration switch by running the 'stock_attribute.sql' via Admin->Tools->Install SQL Patches. If you prefer to use another method to create this table, you will need to edit the file if you use a prefix such as "zen_" for your tables.

Prepare the package for upload to your server by renaming the following folders to match your template name: includes/modules/YOUR_TEMPLATE and includes/templates/YOUR_TEMPLATE.

If you are installing onto a new install or upgrade of Zen Cart 1.3.5 or later then with most good FTP programs (such as WinSCP) you can simply drag and drop the admin and includes directories into the root directory of your site. The files are already arranged in their directory structure.

There are six core Zen Cart files modified by this add-on. If you have installed other add-ons or customised your cart since your Zen Cart installation or upgrade, you will need to check whether they have changed any of the following files:

  • admin/orders.php
  • admin/includes/stylesheet.css
  • includes/classes/order.php
  • includes/functions/functions_lookups.php
  • includes/modules/pages/checkout_shipping/header_php.php
  • includes/modules/pages/shopping_cart/header_php.php

In addition, one file is over-ridden

  • includes/templates/template_default/templates/tpl_shopping_cart_default.php

If you, or any mods that you have installed, have changed any of these files (or over-ridden the last one), then you will need to merge the any changes into the relevant file.

Upgrade from earlier versions

To upgrade from any version 4.x to 4.7, it is easiest to overwrite all the files. No changes are needed to your database. If you are upgrading from version 4.0 - 4.4 you should also delete the following file To upgrade from versions 4.0 - 4.4, it is easiest to overwrite all the files and then delete the following file (unless you have made other changes to it):

  • includes/modules/YOUR_TEMPLATE/attributes.php

Amendments from the Previous Version (3.0.1)

1. Removed "zen_" prefix from table creation SQL allowing it to be run by Admin > Tools > Install SQL Patches (bug fix)

2. Changed quantity field to float in products with attributes table allowing fractional stock quantities (bug fix)

3. admin/orders.php updated for compatibility with Zen Cart 1.3.5

4. admin/products_with_attributes_stock.php updated to pass a languages_id to functions get_products_attributes and get_attributes_name each time they are called (bug fix)

5. includes/functions/functions_lookups.php updated for compatibility with Zen Cart 1.3.5

6. products_with_attributes_catalog_dhtml.php file created so that catalog_dhtml.php no longer needs to be over-written (new feature)

7. Language file for Admin is now used, which together with earlier bug fix should allow full integration with carts whose Admin is not in English (new feature)

8. Multiple changes to allow all data and add-on generated text to correctly reflect Admin language.

9. Re-enabled check stock and disable checkout feature for all products (bug fix)

10. Fixed "Out of Stock" indicators in Shopping Cart for products with attributes (bug fix)

11. Added "Stock Available" to shopping cart page for display when stock is low. This can be turned on and off via the Admin > Stock menu (new feature)

12. Low stock email now triggered by low stock on an attribute, even if overall stock for product remains above stock reorder level (new feature)16. Fixed occasional corruption of product variants on stock page (bug fix)

13. Removed all uses of the <? shortform php tag (best practice)

14. Moved the inline styling on the Products with Attributes Stock page to a stylesheet (best practice)

15. Added model to Products with Attributes Stock page (new feature)

16. Fixed occasional corruption of product variants on stock page (bug fix)

Amendments from 4.0 to 4.1

Incorporated two Zen Cart bug fixes in the files used by this mod.

Corrected a missing double quote in the SQL patch file

Removed a stray diagnostic line

Amendments from 4.1 to 4.2

Corrected the "invalid argument supplied for foreach()" in order.php

Corrected the problem with product variants sometimes not showing on the stock screen (actually a database corruption)

Improved the layout of the stock page by adding some extra CSS.

To upgrade from 4.1, just replace all the files.

Amendments from 4.2 to 4.3

Multiple small changes in accordance with the security patches incorporated in Zen Cart 1.3.6

Minor change to define statements to eliminate a hard-coded English-language "Quantity" missed in previous releases.

To upgrade from 4.1 or 4.2, just replace all the files.

Amendments from 4.3 to 4.4

Minor changes to the following files to keep them in line with the new functionality in Zen Cart 1.3.7 and avoid a duplicate include of the http_client class:

* admin/orders.php
* includes/classes/order.php
* includes/modules/pages/checkout_shipping/header_php.php

To upgrade from 4.1 or 4.2, just replace all the files To upgrade from 4.3, replace the three files above.

Amendments from 4.4 to 4.5

Two Zen Cart security patches from 1.3.7.1:

* admin/orders.php
* includes/modules/pages/checkout_shipping/header_php.php

A minor change to make the HTML generated for orders easier to read. This is a Zen Cart 1.3.7.1 change that will make debugging and maintenance easier, but not affect functionality:

* includes/classes/order.php

Allowance for recent Zen Cart changes for paypal in the shopping cart:

* includes/templates/YOUR_TEMPLATE/templates/tpl_shopping_cart_default.php

Removes the attributes.php file from the includes folder. The only thing that this file was doing was blocking a small Zen Cart enhancement introduced in version 1.3.5.

* includes/modules/attributes.php

Additional styling for the input labels in the Admin - just makes the world a slightly nicer place:

* admin/includes/stylesheet.css 

Slight change to the low stock message switch wording to make clear that this for showing stock levels in cart when there is insufficent to meet the customer's order

* stock_attribute.sql

Amendments from 4.5 to 4.6

Re-working (and commenting) of the function that obtains stock values

* includes/functions/functions_lookups.php

Amendments from 4.6 to 4.7

Integration of changes in Zen Cart 1.3.8 into the following files:

admin/orders.php

* includes/classes/order.php
* includes/functions/functions_lookups.php
* includes/modules/pages/checkout_shipping/header_php.php
* includes/modules/pages/shopping_cart/header_php.php
* includes/templates/YOUR_TEMPLATE/templates/tpl_shopping_cart.php

There are no functional enhancements.

How to Use Stock by Attributes

To use, log into the admin area, click on Catalog->Products with Attributes Stock to modify inventory levels of your products by attributes. You will also want to consider the settings in Configuration->Stock. The settings here will determine things such as whether or not a customer will be allowed to checkout when insufficient stock is on hand. As well as controlling the new feature that allows you display the amount of stock available on the shopping cart page if a customer tries to buy more than the recorded stock.

Frequently Asked Questions

Although is set to prevent it, the mod is allowing clients to checkout even when there's insufficient stock. How do I stop this?

This is almost certainly because not all the files needed by the mod have been installed properly. A quick test for this is to download the includes/classes/order.php file from their site. If line 8 doesn't say something like the line below then there is a problem with the installation.

 @version $Id: order.php 0000 2007-09-19 00:00:00Z kuroi $

If that's the case, re-upload the files and check that none are being rejected, and that if your FTP client asks if you wish to over-write existing files, you say yes.

How can I show the amount of stock available next to each attribute on the product information page?

This is relatively straightforward if you have only a single attribute such as size of color for each product. Code for this is proposed in this archive thread[1]. Seek out post #110 by Grayson, and her correction in #132 and apply the changes to the includes/modules/attributes.php file instead of includes/modules/pages/product_info/main_template_vars_attributes.php

Can I use Stock by Attributes for languages other than English?

Many of the changes made to this add-on from its previous incarnation were to support proper language support in the Admin functions and an additional "stock available + quantity" message in the shopping cart. To take advantage of these facilities three files need to be created. As a guide, I have included my translations of these files into French in the release pack. If you are using a language other than French, edit the directory paths from "french" to your language and similarly edit the three files contained within those directories.

I offer my customers a choice of gift wrapping / ring setting / picture frame / container / monogram style, but don't want to create product variants for every combination of products and gift wrapping ... How can I avoid this?

This is an important issue that is affecting a number of stores as the variety of situations mentioned in the question above indicates. A workable solution is discussed from posts 199 to 204 in an archived stock by attributes thread[2]. However, as this intrudes into critical Zen Code and tables there are no plans incorporate it into this mod, though it will be considered for inclusion when the function is incorporated into Zen Cart's core code.

I have a product where customer can add several options via checkboxes, but Stock by Attributes treats them as though the customer must have exactly one of them

An example of this the "A Bug's Life "Multi Pak" Special 2003 Collectors Edition" product in the Zen Cart demo database. A customer can choose any combination of gift wrapping, autographed memorabilia card or collector's tin or none at all. However, stock by attributes can create variants only for those situations where a customer choses exactly one of the options. Unfortunately this is a limitation in the current structure of stock by attributes which will be considered when the function is incorporated into Zen Cart's core code.

Could the shopping cart alerts and stock message be changed to look like ...?

The mod sticks very closely to the existing Zen Cart defaults. These can be changed by making minor edits to the tpl_shopping_cart_default.php file or the .alert class in your stylesheet.

Can I use Bunyip's Improved Attributes Controller with this add-on?

I can see no reason why not. In fact, I recommend it.

The low stock email shows values such as 57,469. What are these?

These were attributes references. It now shows the name and value of the relevant attributes.

Would it be possible to show when attribute stock is low on the product information page?

This is a frequent request and it's relatively easy when a product has only one attribute. However, it rapidly becomes much more complex for both customers and coding when there is more than one attribute. Although I understand that various solutions have been proposed in the past (e.g. an AJAX-based approach) this does not form part of this mod.

Could attributes for which there is no stock be suppressed from the product information page?

Another one that works best when each product has at most one attribute, but is much more complex when combinations of product are involved.

Would it be possible to add quantity to the Attribute Controller screen where we already enter the option's name and value?

A good idea in principle, but unfortunately yet another of those that really only works when each product has just one attribute. It would also involve a large intrusion into a piece of core Zen Cart code which I am keen not to do.

It might be a good idea to (optionally) disable the stock field in the Catalog > Categories/Products section of Admin to maintain stock integrity.

Yes it would and I would certainly recommend this to the Zen Cart team. However, it's a little more complex than first meets the eye as you would only want to do it for products with attributes, and then only attributes that are not just for information and don't affect stock (e.g. choice of gift wrapping). It would also mean intruding into core code.

Could we have an Attributes Stock icon next to the Attribute Features icon in the Categories/Products menu and a 'Back' button in the Attributes Stock section?

It's a good idea, but not included in this mod.

Does this mod automatically restock attributes when an order is cancelled?

No.

There isn't any multi-currency support when adding attributes. All the drop down lists are in dollars.

This is a general point about attributes and the Options Values Manager in particular. Stock by Attributes doesn't go anywhere near this.