Zen Cart Documentation – Storefront

Dev: Bootstrap in Zen Cart

Mon, 01 Jan 0001 00:00:00 +0000

Bootstrap in the Bootstrap Template

Bootstrap template version 3.X is based on Bootstrap 4. You can find the exact version of Bootstrap (major.minor.patch) in use by looking at the file includes/templates/bootstrap/common/html_header.php, which pulls in the Bootstrap javascript and css.

The Bootstrap template is described in more detail in the storefront documentation on Bootstrap template.

Bootstrap Version	Storefront Bootstrap Template
BS 4.6.2	Template Version 3.X

Bootstrap in Zen Cart Admin

Bootstrap has been used in the Zen Cart admin since Zen Cart version 1.5.5. The following chart shows the association between Bootstrap and Zen Cart versions.

Bootstrap Version	Zen Cart Admin
BS 3.4.1	ZC 1.5.6-2.2.x
BS 3.3.7	ZC 1.5.5

There is work underway to move the Zen Cart admin to Bootstrap 5. You may follow this effort by monitoring this PR.

Bootstrap in zc_install

Bootstrap has been used in the Zen Cart upgrader (zc_install) since Zen Cart version 2.1.0. The following chart shows the association between Bootstrap and Zen Cart versions.

Bootstrap Version	Zen Cart zc_install
BS 5.3.3	ZC 2.1.0

Help on Bootstrap

Dev: Building a Form

Mon, 01 Jan 0001 00:00:00 +0000

Adding a custom form to your site is a common customization. There are a few guidelines for when you do this:

Always submit your form data using POST. Never use GET for forms. (There are exceptions of course, but if you don’t already grok best practices for that, then never use GET for forms!)
Use zen_draw_form, not the HTML <form> tag. Note that when you use zen_draw_form, you get the securityToken with no extra work.
Sanitize your inputs.

A good model for all of this is the Ask a Question feature, which has been part of Zen Cart since 1.5.7. See the following files:

includes/modules/pages/ask_a_question/header_php.php
includes/templates/template_default/templates/tpl_ask_a_question_default.php

Alternative Approach - Use a Form Builder

Another option which is highly recommended for storeowners who don’t have a developer is to use a form building tool like Wufoo.

A Wufoo form can easily be embedded on a extra define page (page_2, page_3, page_4) or an existing page like Contact Us. In the case of Contact Us, you would just edit the template file (includes/templates/YOURTEMPLATE/templates/tpl_contact_us_default.php) and replace the built-in form with the script from Wufoo. Similarly, using a define page would just mean editing the template file and inserting the script below the content div.

Dev: Displaying Custom Fields

Mon, 01 Jan 0001 00:00:00 +0000

Once you have finished adding a field to the database, you will need to figure out where you want to display it, and write the code to do that. Here are some guidelines.

Case 1: New field in products table

a) Adding the new field to the product_info page:

Modify includes/modules/pages/product_info/main_template_vars.php to retrieve the field and create a variable to store it.
Modify includes/templates/YOURTEMPLATE/templates/tpl_product_info_display.php to show the variable.

b) Adding the new field to the product listing page:

Modify includes/modules/pages/index/main_template_vars.php to retrieve the new field.
Modify includes/modules/YOURTEMPLATE/product_listing.php to display the field.

(Some people shortcut this process by skipping the first file and just doing the query in the second file.)

Case 2: New field in orders table

If you add a field to the orders table which is set during order creation, add the field to includes/classes/order.php in the query() method.

Then you can reference it as needed in

tpl_account_default.php
tpl_account_history_default.php
tpl_account_history_info_default.php

On the admin side, you may also wish to reference it in

admin/invoice.php
admin/orders.php
admin/packingslip.php

In the query() method from includes/classes/order.php, add it to whatever array makes sense (info, customer, or delivery), then reference it in any of the files above the same way other fields in that array are referenced.

Adding a field to the products table

Dev: Font Awesome in Zen Cart

Mon, 01 Jan 0001 00:00:00 +0000

The Font Awesome library provides a set of vector icons and social logos for your website. It is one of the most popular icon sets available. See Font Awesome for storeowner docs.

Font Awesome Versions in Zen Cart

Both the admin and provided storefront templates (template_default and responsive_classic) use the same version.

Font Awesome 6.4 is included in Zen Cart 2.0.0 and above.
Font Awesome 4.7 is included in Zen Cart 1.5.5-1.5.8.

Font Awesome Versions in the Bootstrap Template

The Bootstrap template uses its own version of Font Awesome, which may not be the same as the version used by template_default.

Bootstrap template version 3.5.0 and above uses Font Awesome 5.15.

Font Awesome Help and Icons

Help	Icons
Font Awesome 6 Help	Font Awesome 6 icons
Font Awesome 5 Help	Font Awesome 5 icons
Font Awesome 4.7 Help	Font Awesome 4.7 icons

Backwards Compatibility

In Zen Cart 2.0.0 and above, for backwards compatibility with plugins that have not yet been updated, by default, the Font Awesome v4 shim is loaded so that older Font Awesome classes may be used. Loading the shim can be switched off in the site specific overrides.

An example of the kind of change that needs to be made to older code to go from V4 to V6 is shown in this image:

Dev: jQuery in Zen Cart

Mon, 01 Jan 0001 00:00:00 +0000

jQuery in the Zen Cart Storefront

The use of jQuery in the Zen Cart storefront is very much template dependent, with each template making its own choices.

Template Default in general will use the same version as the admin does.

To see which jQuery version your template uses, look at includes/templates/YOUR_TEMPLATE/common/html_header.php. You will see something like

<script src="https://code.jquery.com/jquery-3.6.1.min.js" integrity="sha256-o88AwQnZB+VDvE9tvIXrMQaPlFFSUTR+nldQm1LuPXQ=" crossorigin="anonymous"></script>

which shows you version 3.6.1 is in use.

You can also open a browser window to the storefront, open the Chrome Developer Tools console and type

jQuery().jquery

to see the jQuery version.

jQuery in Zen Cart Admin

jQuery has been used in the Zen Cart admin since Zen Cart version 1.5.5. The following chart shows the association between jQuery and Zen Cart versions.

jQuery	Zen Cart Admin
jQuery 3.7.1	ZC 2.1.0-2.2.x
jQuery 3.6.1	ZC 1.5.8-2.0.1
jQuery 3.5.1	ZC 1.5.7
jQuery 3.4.0	ZC 1.5.6
jQuery 1.12.4	ZC 1.5.5

jQuery UI

The jQuery UI library has been used in the Zen Cart admin since 1.5.6.

jQuery UI	Zen Cart Admin
jQuery UI 1.14.0	ZC 2.1.0-2.2.x
jQuery UI 1.13.2	ZC 1.5.8-2.0.x
jQuery UI 1.12.1	ZC 1.5.6-1.5.7

Help on jQuery and jQuery UI

Dev: Template Settings and the $tplSetting object

Mon, 01 Jan 0001 00:00:00 +0000

Starting with Zen Cart v2.0.0 there is a $tplSetting object which can be used to access site configuration settings that are customized to a specific template.

This means you can have the usual global settings configured in the Admin as usual, but allow for template-specific overrides which only take effect when a certain template is used.

One benefit of this for both storeowners and developers is the ability to try out a new template without destroying the existing configuration settings, so that your live site can function normally even while you’re experimenting with new things.

It also allows template authors to distribute configuration settings with their template, without those settings messing with a store’s already-configured settings.

NOTE: This can be used in tandem with the init_site_specific_non_db_settings.php feature available since Zen Cart v1.5.8 - see Site Specific Overrides.

Starting in Zen Cart 2.1.0, the template settings file may be viewed from your admin page.

Requirements

There are two requirements, using Zen Cart v2.0.0 or newer:

the template must use $tplSetting to access settings instead of directly referring to the global CONSTANT
the template’s /includes/templates/YOUR_TEMPLATE_NAME/template_settings.php file must contain the override settings. (See the 2 kinds of overrides, explained below)

Two Kinds of Settings Available

1. Overriding a CONSTANT such as an admin configuration setting

Many site configuration settings used by templates (and modules that supply data to templates) are controlled via the Admin configuration pages.

Here’s an example of how to override the setting by making an adjustment to your template file and defining the override separately for each template which desires to use something other than the Admin configuration setting.

Zen Cart’s banner feature can be used to show in-site ads or offsite ads or other messages to customers. Some templates use the feature to control a gallery/slider-effect of images.

Banners are rendered in various positions of the template, and it’s possible that one template wants the feature turned off completely, but another template leverages it specifically. This is a good time to use template-specific settings.

Determine the CONSTANT that is used in the Admin for accessing the configured value. The Developers Toolkit can be useful here. If looking in the database at the configuration table, it’s the configuration_key that we’re looking for, because a CONSTANT is declared for the configuration_key, with its value set to what’s stored in configuration_value.

In the case of our example, we’re looking at the controls for SHOW_BANNERS_GROUP_SET2.

Replace the constant with $tplSetting->foo in the template.

Look in your template files for wherever that SHOW_BANNERS_GROUP_SET2 constant is used, and replace the constant with a reference to $tplSetting->foo where foo is that constant.

eg:

  if (SHOW_BANNERS_GROUP_SET2 != '' && $banner = zen_banner_exists('dynamic', SHOW_BANNERS_GROUP_SET2)) {

becomes the following, where two replacements are made:

  if ($tplSetting->SHOW_BANNERS_GROUP_SET2 != '' && $banner = zen_banner_exists('dynamic', $tplSetting->SHOW_BANNERS_GROUP_SET2)) {

To test, things should work as they did before, without any change yet because we haven’t configured an override setting yet. We’ll do that next:

Set the new value into the $tpl_settings array in template_settings.php:

In your template’s template_settings.php file, find the list of array entries for $tpl_settings, and add one for the setting you’re overriding.

eg: $tpl_settings['SHOW_BANNERS_GROUP_SET2'] = 'current_promotions';

You can now refresh the template page in your browser, and the new banner group will be applied. (Of course, you will have to have already defined a banner group by the name you’re using here. If the banner group exists and banners are assigned to it, they will be displayed.)

2. Defining a public variable that is used someplace in a template or module file.

Sometimes templates or modules are coded to be alert to the pre-existence of a variable that could be overridden by setting it earlier in the PHP code execution process.

Defining such variables is sometimes referred to as a “soft” setting/override.

Example:

The product_listing.php module has the ability to specify some CSS classes that should be applied to the grid used when in “fluid” mode (where Product Listing Columns Per Row is set to ‘0’).

If your template doesn’t need to customize anything other than the CSS style class names for the product-listing to display as desired, you could define those classes in template_settings.php instead of creating an override module file and directory for product_listing.php.

The responsive_classic template sets the following variables in its template_settings.php file to define those CSS classes:

$grid_product_cards_classes = 'row row-clmns-3';
$grid_product_classes_matrix = [
    '480' => 'row row-clms-1 row-clms-sm-2 row-clms-md-3 row-clms-lg-4 row-clms-xl-6',
];

Potential Conflicts

Be aware that if you are setting any of these public/“soft” variables using the site-specific-settings, there might be a clash. See the Technical Information For Developers section below for troubleshooting clashes.

Using `template_settings` in tandem with `init_site_specific_non_db_settings.php`

It is recommended to put template-specific settings into the template_settings.php file.

You may leave your preferred site-wide defaults as variables in init_site_specific_non_db_settings.php, but they will be overridden by template_settings.php when it is loaded.

This can work in your favor.

Technical Information for Developers

About the `$tplSetting` helper object

Lookup Order

The $tplSetting object looks for a value to return using this order:

The global $tpl_settings array for a key matching the $setting requested. (It loads that array upon instantiation.)
A defined CONSTANT matching the $setting requested
If nothing is found, null is returned

Casting types

The $tplSetting object allows you to set a type to cast each setting to upon return.

eg: ACCOUNT_STATE_DRAW_INITIAL_DROPDOWN is an admin configuration setting, stored as a string.

So echo $tplSetting->ACCOUNT_STATE_DRAW_INITIAL_DROPDOWN; would normally return 'false' as a string.

But if we set it to boolean, like this: $tplSetting->setType('ACCOUNT_STATE_DRAW_INITIAL_DROPDOWN', 'bool');

then echo $tplSetting->ACCOUNT_STATE_DRAW_INITIAL_DROPDOWN; returns false as a boolean.

Combining types and values in `$tpl_settings[]` array

The basic use of the $tpl_settings array lets you establish values to return when a specific key is referenced.

But if you want to also specify how to cast those values into a certain PHP type without manually calling ->setType() on each one, you can declare them in the initial $tpl_settings array as nested values of value and type (see example below). The $tplSetting` object will look for this nested-array format and use it automatically if the array keys match, instead of treating the setting as an array.

Example:

$tpl_settings['GET_VALUE_OF_TWO'] = '2';
// $tplSetting->GET_VALUE_OF_TWO will return the string '2'.

$tpl_settings['GET_VALUE_OF_TWO'] = [
    'value' => '2',
    'type' => 'int',
    ];
// $tplSetting->GET_VALUE_OF_TWO will return the integer 2.

Load Order

Zen Cart loads certain features/settings in a prescribed order. If you have a setting defined earlier in the process, it will be overridden if something else defines the same thing later on.

Also, due to the way PHP works, any CONSTANTs you’ve defined earlier in the process will NOT be overridden/definable later in the process, since they can only be defined once.

Related init-system load-order information:

extra_datafiles including site_specific_overrides before breakpoint 0
db CONSTANTs (admin-defined config settings) at breakpoint 40
non-db CONSTANTs and variables in init_non_db_settings and init_site_specific_non_db_settings.php at breakpoint 45
functions and extra_functions files at breakpoint 60
template_settings.php at breakpoint 110
followed by language-defines and extra_definitions for the current language

Zen Cart Documentation – Storefront

Dev: Bootstrap in Zen Cart

Bootstrap in the Bootstrap Template

Bootstrap in Zen Cart Admin

Bootstrap in zc_install

Help on Bootstrap

Dev: Building a Form

Alternative Approach - Use a Form Builder

Dev: Displaying Custom Fields

Case 1: New field in products table

Case 2: New field in orders table

Related Articles

Dev: Font Awesome in Zen Cart

Font Awesome Versions in Zen Cart

Font Awesome Versions in the Bootstrap Template

Font Awesome Help and Icons

Backwards Compatibility

Dev: jQuery in Zen Cart

jQuery in the Zen Cart Storefront

jQuery in Zen Cart Admin

jQuery UI

Help on jQuery and jQuery UI

Dev: Template Settings and the $tplSetting object

Requirements

Two Kinds of Settings Available

1. Overriding a CONSTANT such as an admin configuration setting

Example: Banner Group #2

2. Defining a public variable that is used someplace in a template or module file.

Example:

Potential Conflicts

Using template_settings in tandem with init_site_specific_non_db_settings.php

Technical Information for Developers

About the $tplSetting helper object

Lookup Order

Casting types

Combining types and values in $tpl_settings[] array

Load Order

Using `template_settings` in tandem with `init_site_specific_non_db_settings.php`

About the `$tplSetting` helper object

Combining types and values in `$tpl_settings[]` array