Zen Cart Auto Add

---

Auto Add is a Zen Cart module which allows you to automatically add items to the cart. It allows you to specify a trigger item (the item which fires the Auto Add function when it is added to the cart), and the item(s) to be added. Auto Add requires you to add the trigger item and items to be added to the module itself - they are not configured through the admin panel. This sounds complicated, but it's not that bad, and many examples of common practices are provided.

The calling conventions for building an Auto Add are simple: in the setup() function of includes/modules/auto_add.php add the call

$this->add_trigger_item(<required_purchase>);

Then underneath this, specify the item(s) to be automatically added.

   $this->auto_add(<item_to_be_added>);

The notation used to describe required purchases and items to be added is taken from my other mods and will be familiar to people who have used Better Together and friends.

For example,

$this->add_trigger_item(PROD, 12);
   $this->auto_add(PROD, 32);

This says, "whenever product 12 is added to the cart, add product 32."


Items which are set to Auto Add must be able to be added to the cart from a normal listing page. For example, if you search for the item, the search results page shows the item with "Add to Cart" functionality and not a "More Info..." link). What this means is:

• The item does not have non-defaultable attributes.
• The item is in stock (or you permit out of stock sales).
• The item does not have a Product Qty Maximum which will be exceeded by adding the product to the cart.

Here are some examples, based on Better Together discounts.

Suppose you had Better Together configured with

         $this->add_prod_to_prod(12, 11, "%", 100); 

or in Better Together Admin,
To automatically add product 11 when product 12 is added, you would configure Auto Add like this:

function setup() { 
   $this->add_trigger_item(PROD, 12); 
      $this->auto_add(PROD, 11);
}

Similarly, if your Better Together setup was:

         $this->add_cat_to_prod(4, 11, "%", 100); 

or in Better Together Admin,
To automatically add product 11 when a product from category 4 is added, you would configure Auto Add like this:

function setup() { 
   $this->add_trigger_item(CAT, 4); 
      $this->auto_add(PROD, 11);
}

Please note that if you are using Auto Add primarily to support your Better Together discounts, you should really look at Auto Add Plus Better Together Support.

The following types of parameter statements are currently supported:

• auto_add - Specifies the item to be added when the trigger is pulled
• set_wholesale_level - indicates the auto add is only applicable to certain wholesale levels (for Dual Pricing users)

An add_trigger_item() must be done before any parameters, and a parameter applies to the add_trigger_item which directly precedes it.

Detailed Description:

Triggers and parameters are specified in the setup() function of includes/modules/auto_add.php There is no admin interface; you must modify the file directly.

Note that CAT has the Big Chooser/Big Spender/Combination Discounts semantics, not the Better Together ones. In Better Together, CAT only includes items directly below the specified category (i.e. CAT means "parent category" based on the master_categories_id field in the products table). In Auto Add, CAT includes all items below the specified category, whether they are directly below or in subcategories.

Men's Clothing (category 3)
     |
     ---->  Shirts (category 5)
     |      |
     |      -------> shirt A 
     |               shirt B
     |               shirt C 
     ---->  Pants (category 6)
     |      |
     |      -------> pants A 
     |               pants B
     |               pants C 
     ---->  Shoes (category 7) 
            |
            --->  Dress Shoes (category 12) 
            |     |
            |     -------> dress shoes A 
            |              dress shoes B
            |              dress shoes C 
            --->  Casual Shoes (category 18) 
                  |
                  -------> casual shoes A 
                           casual shoes B
                           casual shoes C 

Specifying "Men's Clothing" as a category in Auto Add will include all items in Shirts, Pants and Shoes.

Specifying "Shoes" (CAT 7) as a category will include both dress shoes and casual shoes. This cannot be done in Better Together.

Note that "parent category id" is determined using the master_categories_id field from the products table. So if casual shoes A is also linked into a category called "Hot Products," the parent category is still category 18 (Casual Shoes). For more details on category handling in Auto Add, please see the Category Issues page.

Installation Instructions:

1. Back up everything! Try this in a test environment prior to installing it on a live shop.
2. cd to the directory appropriate for your Zen Cart version, and upload those files. Note that you will have to merge any modified files.
3. cd to the common_files directory, and upload those files.
4. Decide on the Auto Add products you wish to offer. Add them to the setup() method of includes/modules/auto_add.php
5. Note: If you have already installed the Default Attribute module, you must merge the changes in this mod to includes/classes/shopping_cart.php It's just 4 lines of code; search for hook for auto_add_to_cart

Formal Syntax of Configuration

The following commands, which are specified in the setup() function of includes/modules/auto_add.php, are the mechanism for configuring a store's Auto Add items.

Auto Adds always begin by specifying an add_trigger_item. All subsequent parameters (until the next add_trigger_item) apply to this item.

add_trigger_item

Perform the following actions when an item matching the trigger is added to the cart.


where:

required_purchase

is the string PROD, CAT, or MANUF, followed by an identifier (product or category id, or manufacturer id)

Parameters - auto_add

The auto_add() command instructs Auto Add to add the specified item after the trigger fires.


where:

item_to_be_added

is the string PROD, followed by a product id.

Parameters - set_once_only

The set_once_only() command instructs Auto Add to only add the specified item if it does not already exist in the cart.

Major Versions

• 1.9 12/24/2018 - Updates for 1.5.6.
• 1.8 08/01/2016 - Updates for 1.5.5, updates for default attribute, added auto_add_ifnone feature.
• 1.7 01/02/2015 - Updates for 1.5.4.
• 1.6 01/01/2015 - Removed restriction on auto adding identical item.
• 1.5 07/12/2014 - Updates for 1.5.2 and 1.5.3.
• 1.4 02/06/2013 - Added set_once_only parameter
• 1.3 09/19/2012 - Updated for Zen Cart 1.5.1 (no functional changes)
• 1.2 11/06/2011 - Updated for Zen Cart 1.5.0 (no functional changes)
• 1.2 09/24/2011 - Updated to latest shopping_cart file in 1.3.9.
• 1.1 03/09/2011 - Added set_wholesale_level for Dual Pricing users.
• 1.0 04/25/2010 - Updated to 1.3.9
• 1.0 03/01/2010 - First Release (Zen Cart 1.3.8)

FAQ

Q: Why do you have to add PHP code to setup()? Why didn't you put this in the Admin panel?
A: Although it's a bit tedious to have to manually code the associations, it maximizes the module's flexibility. If you need help with the setup logic, I will be happy to do it for you for a small fee, but first look at the many examples in this page.

Q: What do you mean by "defaultable attributes" or "single valued defaultable attributes?"
A: The two terms mean the same thing. They're just attributes for which a default value can be selected without needing input from the product info page. "Single valued" means the attribute has just one value. For example, a radio button with just one value (such as "PDF" or "ZIP file") is single valued. A radio button with two values (such as "red" or "green") would not be single valued. Similarly, "defaultable" means the single value can be easily set without needing additional input. For example, product with a single TEXT attribute would be single valued but not defaultable, since it's not known what the correct value would be. Similarly, a product requiring a file upload would not be defaultable.

Note that in order to take advantage of defaultable attributes, you need my Default Attribute contribution if your Zen Cart version is lower than 1.5.7. (It has been built in since Zen Cart 1.5.7.)

Q: How do I Auto Add a downloadable product?
A: You can specify a downloadable product to be auto added, but first you must install my Default Attribute module, which permits this.

Q: How do I turn Auto Add off?
A: Remove all the code from the body of the setup() function. It should look like this:

  function setup() {
  } 

Q: When I use PROD, it works, but I can't seem to get CAT to work. Why?
A: The CAT value you specify is matched against the master_categories_id field in the products table. Sometimes this value is not what you expect it to be, either because of a database upgrade or because you're using linked categories. Please see the Category Issues page for solutions.

Q: What's the difference between Auto Add and Buy Both Now?
A: Buy Both Now allows you to have a single button add for two items with a prod_to_prod linkage in Better Together. However, both items must not have non-defaultable attributes. With Auto Add, you can have as the trigger an item which has attributes, and have as the Auto Add an item which does not, and you will get the same "one click buy" functionality.

Q: Are there any rules against using Auto Add?
Q: Some interpretations of the EU Consumer Rights Directive are that Auto Add should not be used in the EU. You should only use Auto Add where it is permitted.

Q: All these rules and parameters and combinations make my head hurt. Will you configure this for me?
A: Naturally. Contact me with your requirements for a quote.

---