Zen Cart® for WordPress (zen4wp) — Version 1.3.0

About this Plugin

If you are interested integrating Zen Cart and WordPress, it's probably because you want to mention the products from your Zen Cart store in your WordPress blog. Wouldn't it be nice to be able to put links to your products into the relevant blog posts and pages? Wouldn't it be nice to have the ability to display your New or Featured Products on the home page of your WordPress blog and have those listings update automatically as your Zen Cart store changes?

WordPress is known as one of the best open-source Content Management Systems (CMS) for creating blogs while Zen Cart is a one of the best open-source frameworks to build an on-line shopping cart. Each has its own outstanding features, but the combination of them will create a great product which we are calling "Zen Cart® for WordPress (zen4wp)". Basically, zen4wp is a WordPress plugin that can be used to integrate Zen Cart into WordPress so that shopowners can display Zen Cart content on their WordPress site via a series of widgets and shortcodes.

Credits

This series of widgets and shortcodes that provide linkage between a Zen Cart and an associated a WordPress installation are based on specifications created by Crystal Hill-Jones of Over the Hill Web Consulting (Opens in a new window). Code development by Cindy Merkin of Vinos de Frutas Tropicales (Opens in a new window). The cookie-handling that makes the shopping-cart widget possible is based on the Zen Cart plugin Keep Cart (Opens in a new window).

Prerequisites

Following are the prerequisites for this series of WordPress widgets and shortcodes to operate properly:

• A Zen Cart store installed and operable. Tested with Zen Cart v1.5.1.
• WordPress installed and operable. Tested with WordPress versions v3.5.1 through current versions.
• The Zen Cart and WordPress installations share a common mySQL database.
• The Zen Cart and WordPress installations must share the same domain.
• You must first install the (free) base plugin
• A properly-edited Settings->Set Zen4Wp Options to identify the configuration of the two installations.
• The visitor to your Zen Cart store and WordPress blog must have both cookies and javascript enabled for the shopping-cart widget and the cart attribute of the product short-code to function properly.

What it does

This series of WordPress widgets and shortcodes provide methods to seamlessly link your Zen Cart products to your WordPress blog. All the methods available are listed below; the methods provided are dependent on the zen4wp package you choose. To use the premium (paid) features, you must first install the (free) base plugin:

Behind the Scenes

The magic that happens behind the scenes takes place in your WordPress installation's /wp-content/plugins/zen4wp directory. The majority of the files there (like zen4wp_functions_prices.php) were "cloned" from the similarly-named modules in Zen Cart v1.5.1 (like functions_prices.php) and adapted to use the WordPress database class to access the common database items. In each case, the header comment from the Zen Cart base file has been left intact, so that future changes to those files can be detected more easily. Wherever a language-based element (like a product's description) is pulled from the database, the languages_id value has been left as part of the mySQL SELECT statement but hardcoded the value as 1 (usually English) to allow for possible future multi-lingual support.

The file zen4wp_init_configuration.php pulls the Zen Cart configuration values that are currently used from the database for use by the cloned Zen Cart functions and classes. If modifications are made in the future, the list of configuration_key values should be checked to ensure that any additional configuration keys' values are properly initialized!

Installation

This section lists the files that make up the full set of zen4wp options, consisting of the base files, the Premium — Option 1 files and the Premium — Option 2 files. (Premium — Option 1 files also included in Premium — Option 2)

1. Make sure to backup your database before making any changes! The installation consists of copying the following files from the WordPress Plugin folder to your WordPress environment:
   1. /wp-content/plugins/zen4wp/css/zen4wp_best_sellers.css
   2. /wp-content/plugins/zen4wp/css/zen4wp_categories.css
   3. /wp-content/plugins/zen4wp/css/zen4wp_featured.css
   4. /wp-content/plugins/zen4wp/css/zen4wp_new.css
   5. /wp-content/plugins/zen4wp/css/zen4wp_manufacturers.css
   6. /wp-content/plugins/zen4wp/css/zen4wp_reviews.css
   7. /wp-content/plugins/zen4wp/css/zen4wp_shopping_cart.css
   8. /wp-content/plugins/zen4wp/css/zen4wp_specials.css
   9. /wp-content/plugins/zen4wp/css/zen4wp_testimonials.css
   10. /wp-content/plugins/zen4wp/css/zen4wp_zenprod.css
   11. /wp-content/plugins/zen4wp/js/zen4wp_cookie_monitor.js
   12. /wp-content/plugins/zen4wp/zen4wp.php
   13. /wp-content/plugins/zen4wp/zen4wp_best_sellers.php
   14. /wp-content/plugins/zen4wp/zen4wp_categories.php
   15. /wp-content/plugins/zen4wp/zen4wp_config.php
   16. /wp-content/plugins/zen4wp/zen4wp_cookie_handler.php
   17. /wp-content/plugins/zen4wp/zen4wp_currencies.php
   18. /wp-content/plugins/zen4wp/zen4wp_featured.php
   19. /wp-content/plugins/zen4wp/zen4wp_functions_categories.php
   20. /wp-content/plugins/zen4wp/zen4wp_functions_general.php
   21. /wp-content/plugins/zen4wp/zen4wp_functions_lookups.php
   22. /wp-content/plugins/zen4wp/zen4wp_functions_prices.php
   23. /wp-content/plugins/zen4wp/zen4wp_functions_taxes.php
   24. /wp-content/plugins/zen4wp/zen4wp_html_output.php
   25. /wp-content/plugins/zen4wp/zen4wp_init_configuration.php
   26. /wp-content/plugins/zen4wp/zen4wp_init_templates.php
   27. /wp-content/plugins/zen4wp/zen4wp_manufacturers.php
   28. /wp-content/plugins/zen4wp/zen4wp_new.php
   29. /wp-content/plugins/zen4wp/zen4wp_reviews.php
   30. /wp-content/plugins/zen4wp/zen4wp_shopping_cart.php
   31. /wp-content/plugins/zen4wp/zen4wp_shortcodes.php
   32. /wp-content/plugins/zen4wp/zen4wp_specials.php
   33. /wp-content/plugins/zen4wp/zen4wp_testimonials.php
2. Log into your WordPress admin and click Settings->Set Zen4Wp Options. You'll use this screen to configure the file and database settings needed for Zen4WP to operate:
   • HTTP_SERVER. This value is usually set to the same value as HTTP_SERVER (/includes/configure.php).
   • HTTPS_SERVER. This value is usually set to the same value as HTTPS_SERVER (/includes/configure.php).
   • DIR_WS_CATALOG. This value is usually set to the same value as DIR_WS_CATALOG (/includes/configure.php).
   • DIR_WS_CATALOG_HTTPS. This value is usually set to the same value as DIR_WS_CATALOG_HTTPS (/includes/configure.php).
   • ENABLE_SSL. This value is usually set to the same value as ENABLE_SSL (/includes/configure.php).
   • DB_PREFIX. This value is usually set to the same value as DB_PREFIX (/includes/configure.php).
   • DIR_FS_CATALOG. This value is usually set to the same value as DIR_FS_CATALOG (/includes/configure.php).
   • OTHER_IMAGE_PRICE_IS_FREE. This value is usually set to the value of the like-named define in /includes/languages/english/other_image_names.php.
   • OTHER_IMAGE_CALL_FOR_PRICE. This value is usually set to the value of the like-named define in /includes/languages/english/other_image_names.php.
3. If you purchased the Premium — Option 2 package:
   • Rename the /YOUR_ADMIN directory within the plugin's Zen Cart Modified Files folder to match the name of your Zen Cart's admin folder.
   • Log into your Zen Cart admin console.
   • Copy the files from the plugin's Zen Cart Modified Files folder to your Zen Cart's file structure:
     1. /includes/auto_loaders/config.zen4wp.php
     2. /includes/init_includes/init_zen4wp.php
     3. /includes/languages/english/zen4wp_add_product.php
     4. /includes/modules/pages/zen4wp_add_product/header_php.php
     5. /YOUR_ADMIN/includes/auto_loaders/config.zen4wp.php
     6. /YOUR_ADMIN/includes/init_includes/init_zen4wp_config.php
   • Click the "Admin Home" link at the top of your Zen Cart's admin console. You'll see the message Zen Cart for WordPress (zen4wp) install completed! at the top of the screen.
   • Click Configuration->Sessions and set the configuration values necessary for the Zen Cart/WordPress shopping cart communications:
     1. Enable zen4wp Shopping Cart?. This control enables (True) or disables (False, the default) the creation of the shared cookie between the Zen Cart and WordPress installations.
     2. zen4wp Domain. Identifies the root domain value that is common between the Zen Cart and WordPress installations. Currently-supported configurations are:
        1. Subdirectory installation. One of the installations is accessed as a subdirectory of the other, e.g. www.example.com/blog or www.example.com/store.
        2. Peer subdomain installation. Each of the installations is accessed as a subdomain with the same root, e.g. blog.example.com and store.example.com.
        3. Subdomain installation. One of the installations is accessed as a subdomain of the other, e.g. blog.example.com and www.example.com.
        For each of the examples above, this field would be specified as example.com.
     3. zen4wp Secret Key. Identifies a secret value shared between the Zen Cart and WordPress installations, allowing the WordPress widget to ensure the validity of the information present in the shared root-domain cookie. You may enter any random value; the secret key should be at least 10 digits in length and should contain both numbers and a combination of upper- and lower-case letters. You can use a password generator like the one at http://passwordsgenerator.net/ to create your secret key. When using the Secure Password Generator service, be sure to un-check the following options: Include Symbols, Exclude Similar Characters and Generate On The Client.
   • Note: The file /wp-content/plugins/zen4wp/zen4wp.php contains a block of language constants that are used in the creation of the add-to-cart/buy-now button (such as "Sold Out" and "Call for Price"). The values assigned to these constants are based on the default wording present in the Zen Cart v1.5.1 release's /includes/languages/english.php file.

Upgrading from v1.2x to v1.3.0

Remove wp-content/themes/YOUR_THEME/zen4wp_shortcodes.php.altogether from your store. This file has been moved to a new directory.

Don't forget to edit /wp-content/themes/YOUR_THEME/functions.php to remove the following line:
include ( 'zen4wp_shortcodes.php' );

Un-install

To remove Zen4WP altogether from your store, follow the normal WordPress process for deactivating and deleting plugins. If you have purchased the premium Option 2, you will also need to delete the new files that were previously copied to your Zen Cart installation. There are instructions in the comments of the zen4wp_uninstall.sql file regarding how to remove the configuration table values.

Zen4WP Usage

For each of the widgets, the client will need to use the WordPress admin'sPlugins->All to Activate them. Once activated, the client can use the WordPress admin's Appearance->Widgets to place and configure each of the widgets.

Widget and Shortcode Details

Best Sellers Widget

The Best Sellers widget (zen4wp_best_sellers.php) interrogates the Zen Cart database and retrieves the products with the largest products_purchased count. Just like the Zen Cart best_sellers sidebox, its output is an HTML ordered-list containing links to each of the products and using each product's name as the anchor-text.

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of best-sellers to include in the list.
3. Include sales count. A checkbox that indicates whether or not to include the products' purchase-count in the display.

Categories Widget

The Categories widget (zen4wp_categories.php) interrogates the Zen Cart database and retrieves a list of top-level categories. Just like the Zen Cart categories sidebox, its output is collection of HTML links that reference each of these categories using the category's name as the anchor-text. This widget is hideCategories-aware; top-level categories that are currently hidden are not included in the display. The following configuration settings from the Zen Cart admin's Configuration menus are used:

1. My Store
   1. Show Category Counts
2. Layout Settings
   1. Categories Separator between the Category Name and Count
   2. Categories Count Prefix
   3. Categories Count Suffix
   4. Categories with 0 Products Status

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.

Featured Products Widget

The Featured Products widget (zen4wp_featured.php) interrogates the Zen Cart database and retrieves a list of products that are currently configured as "featured". Just like the Zen Cart featured sidebox, its output is collection of HTML div's that contain links to each of the products and using each product's image and name as the anchor-text — the product's price is also included.

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of random featured products to include in the list.
3. Number of Columns for the Display. The number of columns to use when displaying the list.

Manufacturers Widget

The Manufacturers widget (zen4wp_manufacturers.php) interrogates the Zen Cart database and retrieves a list of the manufacturers in the Zen Cart. Its output is collection of HTML div's that contain links to each of the manufacturers' index-listing pages, using the manufacturer's name as the anchor-text. The following configuration settings from the Zen Cart admin's Configuration menus are used:

1. Maximum Values
   1. Manufacturers List - Verify Product Exist
   2. Length of Manufacturers Name

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.

New Products Widget

The New Products widget (zen4wp_new.php) interrogates the Zen Cart database and retrieves a list of products that are currently configured as "new". Just like the Zen Cart new-products sidebox, its output is collection of HTML div's that contain links to each of the products and using each product's image and name as the anchor-text — the product's price is also included. The following configuration settings from the Zen Cart admin's Configuration menus are used:

1. Maximum Values
   1. New Product Listing - Limited to ...
2. New Listing
   1. Mask Upcoming Products from being included as New Products

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of random new products to include in the list.
3. Number of Columns for the Display. The number of columns to use when displaying the list.

Products on Special Widget

The Products on Special widget (zen4wp_specials.php) interrogates the Zen Cart database and retrieves a list of products that are currently configured as "on special". Just like the Zen Cart specials sidebox, its output is collection of HTML div's that contain links to each of the products and using each product's image and name as the anchor-text — the product's price is also included.

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of random special products to include in the list.
3. Number of Columns for the Display. The number of columns to use when displaying the list.

Product Reviews Widget

The Product Reviews widget (zen4wp_reviews.php) interrogates the Zen Cart database and retrieves a list of product reviews. Just like the Zen Cart reviews sidebox, its output is collection of HTML div's that contain links to each of the reviews and using the reviews text and star-rating and the associated product's image as the anchor-text.

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of random product reviews to include in the list.
3. Number of Columns for the Display. The number of columns to use when displaying the list.
4. Display this many characters from the review's text. The maximum number of characters of each review's text to display.

Shopping Cart Widget

The Shopping Cart widget (zen4wp_shopping_cart.php), if enabled in the shared database, interrogates a root-domain cookie created by the Zen Cart's processing to retrieve the customer's current login and cart (number of items, total amount and currency) information.

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Display link to shopping_cart page?. A check-box to indicate whether or not to display the link.
3. Display link to login/logoff page?. A check-box to indicate whether or not to display the link.
4. Empty cart display. A check-box to control whether or not to display the widget even if the cart is empty.
5. Display format. A check-box to control the format of the shopping cart widget's display. Check the box to have the cart display in a Zen Cart sidebox format; leave the box unchecked to have the cart display in a single-line "header" format.
6. Cart icon filename. If the Display format specified that a header-format is to be used, this field identifies the name of the shopping cart icon to use. The file resides in the Zen Cart current template's icon directory — /includes/templates/CURRENT_TEMPLATE/images/icons.

Testimonials Widget

The Testimonials widget (zen4wp_testimonials.php), if the Testimonial Manager plugin is installed in the shared database, displays a collection of testimonials from the Zen Cart store. The following configuration settings from the Zen Cart admin's Configuration menus are used:

1. Testimonial Manager
   1. Number Of Testimonials to display in Testimonials Sidebox
   2. Display Truncated Testimonials in Sidebox
   3. Length of truncated testimonials to display
   4. Display View All Testimonials Link In Sidebox
   5. Display Add New Testimonial Link In Sidebox
   6. Testimonial Image Width
   7. Testimonial Image Height

Each instance of the widget can be customized to specify:

1. Title. The title used on the blog-site for the information.
2. Maximum Number to Display. The number of random testimonials to include in the list.
3. Number of Columns for the Display. The number of columns to use when displaying the list.
4. Display this many characters from the testimonials's text. The maximum number of characters of each testimonials's text to display.

Note: The widget will only display if one or more testimonial has previously been written.

Zen4WP - Shortcodes

To use the various Zen4WP shortcodes, you must first activate the shortcodes function. Go to the WordPress admin's Plugins->All to activate the Zen4WP - Shortcodes plugin. Word4WP shortcodes will not work until you activate this plugin.

[zencat] Shortcode

The [zencat] shortcode (in zen4wp_shortcodes.php) creates an HTML anchor, linking to the specified Zen Cart category's listing page, using the category's name as the anchor-text. If a category with the specified ID is not found, the shortcode generated some category not found text instead.

Within a blog entry, you use the shortcode as:

[zencat id=categories_id]

using the associated category's Zen Cart categories_id value. The shortcode generator looks up the categories_id value in the database and creates an HTML anchor tag to the category's listing (e.g. index) page.

[zenprod] Shortcode

The [zenprod] shortcode (in zen4wp_shortcodes.php) creates an HTML block that contains information about a particular product in your Zen Cart. If a product with the specified ID is not found, the shortcode generates the message: The product with id of xx was not found.. The following configuration settings from your Zen Cart admin's Configuration menus are used:

1. Attribute Settings
   1. Read Only Option Type - Ignore for Add-to-Cart
2. Product Listing
   1. Display Add to Cart

Within a blog entry, you use the shortcode as:

[zenprod id=products_id name=name_sort image=image_sort price=price_sort cart=cart_sort]

The elements styled with bold are required and the cart attribute is ignored unless you've purchased the Premium — Option 2 package. Each of the xxxx_sort attribute values identify the order in which the associated information is output. The value is specified as a positive integer value; a value of 0 indicates that the associated information is not to be output. If neither of the name and image attributes are specified, the shortcode will be interpreted with name=1.

Each [zenprod id=nn name=ww image=xx price=yy cart=zz] shortcode is formatted using the following formats, with each item output in the order you specified:

<div class="zenprod zenprodwwxxyyzz zenprod-id-nn>

  <div class="zenprod_name"><a href="{products_link}">{product_name}</a></div>

  <div class="zenprod_image"><a href="{products_link}"><img src="{product_small_image}" alt="{product_name}" /></a></div>

  <div class="zenprod_price">{product_price_info}</div>

  <div class="zenprod_cart">{product_cart_info}</div>

</div>

The file /wp-content/plugins/zen4wp/css/zen4wp_zenprod.css is automatically loaded if the current WordPress page includes one or more zenprod shortcodes.

[zenmfgr] Shortcode

The [zenmfgr] shortcode (in zen4wp_shortcodes.php) creates an HTML anchor, linking to the specified Zen Cart manufacturer's listing page, using the manufacturer's name as the anchor-text. If a manufacturer with the specified ID is not found, the shortcode generated some manufacturer not found text instead.

Within a blog entry, you use the shortcode as:

[zenmfgr id=manufacturers_id]

using the associated category's Zen Cart manufacturers_id value. The shortcode generator looks up the manufacturers_id value in the database and creates an HTML anchor tag to the manufacturer's listing (e.g. index) page.

Version History

• v1.2.2, 2013-09-23, Initial release
• v1.2.3, 2013-10-03:
  • Incorrect display of some sale prices, especially Salemaker sales and some free products. Changed zen4wp_functions_prices.php.
• v1.3.0, 2014-03-30:
  • Provided enhancements to the [zenprod] Shortcode.
• v1.3.1, 2014-09-18:
  • Best Sellers widget: Throwing "printf() too few args" on line 97
  • Correct various PHP notify errors (a couple of which were variable "misspellings").
  • Duplicated definition: ZEN_TABLE_PRODUCT_TYPES