Zen Cart custom software development, Zen Cart modules, Zen Cart Expert eCommerce with Zen Cart!

Zen Cart Extended Family

Zen Cart Extended Family

Extended Family for Zen Cart simplifies the process of showing related products based on products or categories, with easy one-click adding for products with no attributes. (Note: Products with defaultable attributes may be used, if you have installed my Default Attribute mod.)

Extended Family also works with Discount Chooser as a "package builder". See package discounting and promotion for more details.

Relevance: Zen Cart™ 1.3.9, 1.5.x You must have JavaScript enabled in your browser.

Current Version: 1.7. (version history)

Support Thread: My commercial software is not supported on the Zen Cart forum. Please email me questions instead.

Cost: $25 (Note: this low price covers software only for self-installation.)

Buy Now

Would you like to ask me questions before buying? I'm happy to help likely purchasers make the right decision. Please use my contact form.

Installed Cost: $200.00 (Professional installation by That Software Guy)

Installation Difficulty: Moderate-High

Installation Instructions: click here for Installation Instructions

Common Installation Issues: click here for Installation Issues

Buy: Buy Extended Family!
Pre-purchase questions? No problem! Just Please contact me with your question.

FAQ: click here for FAQs

Configuration: Configuration of Extended Family is done by the built-in admin panel.

Video: You may watch this cross sell being created in Extended Family v1.0 Admin panel in this video:



Add-Ons: Extended Family is even more powerful when used in conjunction with Discount Chooser to build product pages. See package discounting and promotion for more details.

Bugs: click here for bugs

Incompatibilities: This software will not work with AJAX add-to-cart mods.

Overview:

Extended Family allows you to specify a list of triggers (products or categories), and an associated list of offers. Here's what the blank screen looks like:

Extended Family Cross Sell Initial Screen

Zen Cart Extended Family Admin Panel

For example, the configuration below shows that if you display either product 8 or product 19, you should show products 16 and 12 as cross sells.

Extended Family Cross Sell Creation

Zen Cart Extended Family Admin Panel

The page is broken into two areas: on the top, a list of existing cross sells, and on the bottom, a form to allow you to add new cross sells.

When you press the Submit button, a new cross sell gets created and displayed at the top of the screen. In this case, it looks like this:

Extended Family Cross Sell Creation

Zen Cart Extended Family Admin Panel
Here are what a group of cross sells look like.

Extended Family Cross Sell List

Zen Cart Extended Family List of Cross Sells


Cross sells are listed in reverse chronological order. Cross sells can currently be deleted or deactivated but not edited directly. The cross sells which are currently inactive are shown in red.
On the catalog side, now that we have created a cross sell for products 8 and 19 to show products 16 and 12, if you go to the product info page for product 8, you will now see a centerbox offering the two cross sold items.

Extended Family Cross Sell Results

Zen Cart Extended Family

Notice that each of these items has a checkbox - checking the checkbox allows them to be added to the cart right along with the main item when the Add to Cart button is pressed. As you might expect, the checkbox follows the same rules that adding a product from the listing page does: in order to show the checkbox,
  • The item must not not disabled (out of stock or otherwise).
  • The item must not have non-defaultable attributes.
An easy way to test this is to search for the item, and ensure the search results page shows the item with "Add to Cart" functionality and not a "More Info..." link).

Categories and products with attributes are still shown on the Related Items list, just without the checkbox.

Another Extended Family Example

Zen Cart Extended Family Admin Panel

In this example, the when the product info page for any item in the Printers category is shown, the customer sees Mice, Keyboards and CDROM drives shown in the Extended Family centerbox, which is shown below:

Zen Cart Extended Family Centerbox

Note that since these are all categories, no checkbox appears.

Sorting the Extended Family

The list of related items on the product info page is randomized by default, but can be sorted by product specific fields, (alphabetically by name, by price low to high, or by price high to low) or category id if desired. If you install Zen Cart Common XSell Sort Order , you may also sort by a special purpose field (common_sort) added to the products table.

The sort setting is configured on Admin > Configuration > Extended Family. If one of these sort orders is used, the categories are shown at the bottom in alphabetical order (since they don't have prices). Here's a list of related items sorted by name

Zen Cart Extended Family Centerbox

and here's the same list sorted by price low to high.

Zen Cart Extended Family Centerbox


If you install Zen Cart Common XSell Sort Order , you may also sort by a special purpose field added to the products table.

Defaulting the Checkboxes to Checked

For some stores, it makes sense to display the checkboxes for Extended Family items in "checked" state. Here's how to make that change:
Edit includes/templates/YOUR_TEMPLATE/templates/tpl_extended_family.php
Look for the call to zen_draw_checkbox_field.
Change
              echo zen_draw_checkbox_field($xsell_id,'',false, 'id="'.$xsell_id .'"');
to
              echo zen_draw_checkbox_field($xsell_id,'',true, 'id="'.$xsell_id .'"');
Then your checkboxes will be prechecked. Here's a screenshot using a different template:
Zen Cart Zen Cart Extended Family with Options prechecked


Some stores might only want this behavior for "kit" or "bundle" type products. Here's how to set this flag if the product name contains "Kit" or "Bundle".
In includes/templates/YOUR_TEMPLATE/templates/tpl_extended_family.php
Change
              echo zen_draw_checkbox_field($xsell_id,'',false, 'id="'.$xsell_id .'"');
to
              if ((strpos($products_name, "Bundle") !== false) ||
                  (strpos($products_name, "Kit") !== false)) {
                  $checked = true;
              }         
              echo zen_draw_checkbox_field($xsell_id,'',$checked, 'id="'.$xsell_id .'"');


Package Discounting and Promotion

If you're building packages, Discount Chooser becomes even more powerful when used in conjunction with Extended Family.

Suppose you want to sell these three items as a package:
  • monitor - product #186
  • keyboard - product #25
  • mouse - product #3
The retail on these items is $219.98, but you'll sell the package for $199.

Build the package with Discount Chooser:
Zen Cart Discount Chooser plus Extended Family


If Extended Family is installed, an extra button labelled "Family" will appear when the Free Gift offer is shown. Zen Cart Discount Chooser plus Extended Family

Pressing this button will create corresponding entries in the Extended Family tables. Zen Cart Discount Chooser plus Extended Family

You will now be able to show something even more powerful on the product info page - a detailed cross sell list.
Zen Cart Discount Chooser plus Extended Family

Clicking the "Select all" checkbox means all the products will be added to the cart when the main product is added to the cart.

There is only one rule for applying discounts for packages (Package Final Price or Package Percent Off) which is different from other discounts in Discount Chooser: all items in the package must be present. So in the case above, if a customer had only the Monitor and the keyboard in their cart, they would not be eligible for a package discount until the mouse was added.

Here's a video showing all of this put together.




Installation Instructions:

  1. Back up everything! Try this in a test environment prior to installing it on a live shop.
  2. Copy the contents of this unzipped file to the root directory of your shop. NOTE that these files assume your template name is "custom," so any file with "custom" in its name will need to be renamed if you are using a different template name.
  3. Run the extfamily.sql file against your database, using Admin > Tools > Install SQL Patches.
  4. Add the field products_xsell_sort_order to the products table and the product editing screens, as shown in Adding a Text/Integer Field to the Zen Cart Products Table. (Note that (A), adding the field to the database, was done in the previous step; you just have to do the file edits.)
  5. Edit the file includes/templates/YOUR_TEMPLATE_NAME/templates/tpl_product_info_display.php and make these changes:
    a. In the block
    <!--bof Form start-->
    <?php echo zen_draw_form('cart_quantity', zen_href_link(zen_get_info_page($_GET['products_id']), zen_get_all_get_params(array('action')) . 'action=add_product', $request_type), 'post', 'enctype="multipart/form-data"') . "\n"; ?>
    <!--eof Form start-->
    
    change action=add_product to action=add_product_ccs
    b. Below the block that ends with
    <!--eof Attributes Module -->
    
    add this block:
    <!-- bof Extended Family Module --> 
    <?php
      require($template->get_template_dir('/tpl_extended_family.php',DIR_WS_TEMPLATE, $current_page_base,'templates'). '/tpl_extended_family.php'); 
    ?>
    <!-- eof Extended Family Module --> 
    

    Note: If you are using the 1.5.5 responsive_classic template, positioning this change below the Product description looks better.
  6. Extended Family may now be configured under Admin > Tools.


Installation Problems:

The most common installation problems for this module are as follows:
  1. Unfamiliarity with installing mods. Please review my Guide to Mod Installation on Zen Cart.
  2. A misunderstanding of "category." A category in Extended Family is "the master category of the product, and all ancestors of that category" OR "a linked category for the product." See the Category Issues page for a discussion of the treatment of categories in my mods.
  3. Some hosts require scripts which are run from a URL - for example,
    http://your-store.com/your-admin/extended_family.php
    
    to have permissions 644. You may see a message like
    HTTP 500: Internal Server Error
    
    The server encountered an internal error or misconfiguration and was unable to complete your request.
    
    when running Extended Family Admin if this is the case with your host. Simply set the permissions of admin/extended_family.php and admin/extended_family_backend.php to 644 using your FTP client (or perhaps your cPanel File Manager).
  4. If try to run the Admin Panel and get an error like
    1146 Table 'yourdb.zen_extended_family' doesn't exist
    in:
    [SELECT * FROM zen_extended_family ORDER BY id DESC ]
    If you were entering information, press the BACK button in your browser and re-check the information you had entered to be sure you left no blank fields.
    
    this means you ran the sql script in phpMyAdmin without adding the prefix manually. You can avoid this problem by running SQL scripts in Admin > Tools > Install SQL Patches.
  5. Prior to version 1.6a, granting access to Extended Family to a non-superuser required a core change. Now it is built in. To add this prior to version 1.6a, update admin/includes/extra_datafiles/extended_family_defines.php with the latest copy, and run this SQL command in Admin > Tools > Install SQL Patches:
    INSERT IGNORE INTO admin_pages (page_key, language_key, main_page, page_params, menu_key, display_on_menu, sort_order) VALUES ('extendedFamilyBackend', 'BOX_TOOLS_EXTENDED_FAMILY_BACKEND', 'FILENAME_EXTENDED_FAMILY_BACKEND', '', 'tools', 'N', 999);
    
    Then edit the Admin Profile you want to change, and check Extended Family Admin and Extended Family Admin Backend. Press Save at the bottom to save your changes.
  6. If you are pulling in jQuery and/or jQueryUI already in your admin panel, you will need to comment out the require statements that do that in ./admin/extended_family.php.
  7. If you are running 1.3.9 or prior with the Admin Profiles contribution, there are a few more steps. you must install the software, then go to Admin > Tools > Admin Settings, and check 'Extended Family' under the tools menu. Then go to Admin > Tools > Extended Family, and you'll get an error message in the form where cross sells are entered. Go back to Admin > Tools > Admin Settings, and check 'Extended Family backend'. Now Admin > Tools > Extended Family will work.
  8. The "Select all" checkbox in the related items block depends on jQuery. Most templates already have jQuery built in (and recent versions of Zen Cart include it too) so for most stores this shouldn't be a problem.
  9. Some templates include css stylesheets that set checkboxes to display:none. If yours does this, you'll have to style the extended family checkboxes to prevent this. For example,
    .cartWrapCheckDisplay > input[type=checkbox], #checkall {
       display: inline !important;
    }
    
  10. Got a blank page? Review the guidelines for Debugging a blank page in Zen Cart
If you are having trouble installing this module, you should also refer to my Guide to Mod Installation on Zen Cart. I'm also happy to install most of my mods for a fee.

Major Versions

  • 1.7 03/07/2022 - Updates for PHP 7.3+.
  • 1.6a 09/26/2021 - Allow non super-users to run.
  • 1.6 09/01/2021 - Updates for Bootstrap template.
  • 1.5a 08/06/2021 - Updates for Bootstrap template.
  • 1.5 06/04/2021 - Updates for Zen Cart 1.5.7 and newer MySQL versions.
  • 1.4 08/01/2017 - Add "select all" checkbox on product info page.
  • 1.3 04/02/2017 - Updates for MySQL 5.7
  • 1.2 09/01/2016 - Updates for Common Cross Sell Sort Order.
  • 1.1 08/01/2016 - Updates for Default Attribute.
  • 1.0 02/01/2015 - First release

Bugs

  • Prior to version 1.2, there was a bug in setting the sort under Admin > Configuration > Extended Family. To fix this, run fix_1.1.sql (in the installation package) from Admin > Tools > Install SQL Patches.


FAQ

Q: Why do Linked Categories only work in Extended Family?
A: The definition of a "category" in Extended Family is different from all other mods (such as Table Cross sells, Big Chooser and so forth). It is "the master category of a product, and all that category's ancestors" AND "a linked category for the product." See the Category Issues page for a discussion of the treatment of categories in my mods.

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: Why do I have to enable Javascript to run the Extended Family Admin Panel?
A: Because it uses AJAX, a Javascript based technology. This creates a faster, more responsive user interface. If you do not enable Javascript in your browser, you will see a flashing red error message at the top of the page, and the Extended Family Admin Panel will not operate.

Q: Why is it called Extended Family?
A: Because it shows related products!

Q: I want the Extended Family checkboxes on the product info page to all be checked. What changes are required?
A: Here are instructions on how to make the Extended Family checkboxes checked by default.

Q: What's the difference between Extended Family, Kitbuilder, Checkbox Cross Sell and Impulse Buy?
A: They are all bundle-building plugins for Zen Cart, but they each do different things.
  • Kitbuilder uses the product info page like Extended Family, but the products in a kit are fixed and cannot be deleted individually by a customer. Also, Extended Family allows you to cross sell categories or products with attributes, whereas Kitbuilder does not.
  • Checkbox Cross Sell uses the Better Together configuration to determine what should be shown - either the original configuration in PHP in Better Together, or the Better Together Admin Panel configuration.
  • Impulse Buy appears only on the checkout shipping page and has its own configuration, which is hardcoded in PHP, whereas Extended Family has its own admin panel.


I charge a fee of $25 for the Extended Family. Buy Extended Family.
The fee covers software only; installation is extra if you require help.