Version: 2.4
Release: Jul 31, 2006
Compatibility: QC v1.0+
Languages: en
Author: Wizzud
Contact: rb@wizzud.com

Product Attributes

Plugin module for Quick.Cart by OpenSolution.org

Synopsis

This plugin offers ...
  • Attribute definition, grouped by the type of attribute
  • Price offset per attribute, as an amount or percentage
  • Assignment of any attribute to any product, on a per-product basis
  • Reserved attribute group for optional user-input fields
  • Special Price for any product
  • Compatible with Last Product and Random Product plugins NEW in v2.1!
  • Compatible with Image Watermark v1.1 plugin NEW in v2.2!
  • Compatible with sendOrderToClient v0.2 plugin NEW in v2.2!
  • Simplified installation and maintenance*
* Please note the Prerequisites for running this plugin. Due to the complexity of the interaction with the core Quick.Cart code it is necessary to use the facilities provided by the Plugin Manager. If this causes any problems I apologise in advance, but it is unavoidable.

Compatibility

Quick.Cart versions prior to v1.0 : Not compatible.
Quick.Cart versions 1.0 upward : Compatible at the time of writing.
Other Plugins : At the time of release, this plugin is known to be compatible with the following available plugins (other than those listed as Prerequisite):
  • productsInRow v1.1
  • lastProduct v0.2
  • randomProduct v0.2
  • imageWatermark v1.1 New in v2.2!
  • sendOrderToClient v0.2 New in v2.2!
Any other plugins not mentioned above may or may not work in conjunction with Product Attributes, but it is always worth checking their available documentation to see if they specify compatibility with this plugin.

Prerequisites

Plugin Manager v2.0+ : Uses the Plugin Manager's 'extendTplParser' class extension.
None other, assuming that the Compatibility requirements have been met.

Upgrade

There is an upgrade path starting with version 2.0 of this plugin. Lower versions are not upgradable.

Upgrading v2.3 to v2.4

The files that have changed are
  • /plugins/productAttributes/AboutThisPlugin.html
  • /plugins/productAttributes/setup.php
  • /plugins/productAttributes/checkAttributes.js
  • /templates/pa.products_list.tpl
  • /templates/pa.products_more.tpl
  • /templates/pa.products_print.tpl
  • /templates/pa.productsInRow.tpl
  • /templates/productAttributes.css
so you can, if you wish, simply unzip the v2.4 release file, find these files, and overwrite the v2.3 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.

Upgrading v2.2 to v2.3

The files that have changed are
  • /plugins/productAttributes/AboutThisPlugin.html
  • /plugins/productAttributes/setup.php
  • /templates/productAttributes.css
  • /templates/pa.products_more.tpl
so you can, if you wish, simply unzip the v2.3 release file, find these files, and overwrite the v2.2 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.

Upgrading v2.1 to v2.2

The files that have changed are
  • /plugins/productAttributes/AboutThisPlugin.html
  • /plugins/productAttributes/checkAttributes.js
  • /plugins/productAttributes/productAttributes.php
  • /plugins/productAttributes/setup.php
  • /templates/productAttributes.tpl
so you can, if you wish, simply unzip the v2.2 release file, find these files, and overwrite the v2.1 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.

Upgrading v2.0/1/2/3 to v2.4

  1. Make a note of your plugin's current configuration, then follow steps 1, 2 and 3 of the Installation instructions below, replacing old files/folders with the new versions. If you have made your own modifications to previous v2.0 files, re-apply changes as necessary!
  2. Go to the Configuration - Plugins option on the Admin menu. You will see a warning that the Product Attributes plugin version number has changed. If Plugin Manager has been configured for Version Checking then the plugin will also have been disabled and the Configuration button greyed out.
    • Click the Reload Setup button for the Product Attributes plugin
    • Click the Configuration button for the Product Attributes plugin, make any changes necessary, and Save
    • Re-enable the plugin, and Save
For anyone upgrading from earlier versions of Quick.Cart, the db/attributes.php file has had an extra field appended to it - which can be editted in by appending an extra dollar to each record - but the db/product_attributes.php file has been restructured and is not so simple to update. I would suggest that the simplest course, therefore, is to clear down the db/product_attributes.php file and re-assign all attributes. A transform utility program could be used, but has not been provided with this release.

Install

Where possible, the release folder is laid out in the correct folder structure to aid installation.
  1. Copy the entire productAttributes folder from the release/plugins/ folder into your Quick.Cart plugins/ folder.
  2. Copy the contents of the release/templates/admin/ folder to your Quick.Cart templates/admin/ folder (2 new files: productAttributes.tpl and productAttributes.css).
  3. Copy the contents of the release/templates/ folder to your Quick.Cart templates/ folder (6 new files, NOT the Admin folder!).
  4. Copy the contents of the release/db/ folder to your Quick.Cart db/ folder (2 new files: attributes.php and product_attributes.php) and give them the same file permissions as all other files in that directory (read and write access). This stage is actually optional - if the files don't exist, the plugin will attempt to create them for you.
  5. Add a link in the admin menu bar to access the attributes maintenance screen(s). Please remember to make a copy of the template file before you change it!
    Edit templates/admin/page.tpl and somewhere within the <div class="menuBar"> section (which begins at roughly line 37) ...
    Insert the 1 line below
    CODE
    <a class="menuButton" href="?p=attributesList"
       onmouseover="return buttonClick(event, 'attributes'); buttonMouseover(event, 'attributes');"
       >$lang[attributes]</a>
    Note that the position in the Admin navigation bar depends upon whereabouts among the existing links you place the new link.
    Then look a couple of lines down from there, for a line containing just "</div>",and immediately below this line paste the following 3 lines
    CODE
    <div id="attributes" class="menu" onmouseover="menuMouseover( event );">
       <a class="menuItem" href="?p=attributesForm"><span class="menuItemText">$lang[Add_attribute]</span></a>
    </div>
  6. Go to the Configuration - Plugins option on the Admin menu, and configure and then enable the productAttributes plugin.

User Guide

Configuration

The plugin's configuration parameters are accessible via the Plugin Manager, and full explanations have been provided for each and every setting. Please read them carefully!

Attribute Admin

  • You add attributes using Admin - Attributes/Add Attribute, in the same manner that you would add products or categories.
  • An attribute belongs to a Group, and has a Name.
    Using colours as an example, the Group name would be "Colour" and the attribute Names might be "Red", "Yellow", "Blue", etc. (The name of the Group is restricted to one word, for technical reasons).
  • Each attribute can have an Offset applied to it. Offsets can be positive/negative amounts, or positive/negative percentages (indicated by checking the checkbox). An Offset is applied to the base price of the product to which the attribute is attached, allowing price modification depending upon the customer's selection.
    For example, given a T-Shirt with a base price of $5.00, attributes could be set up for Small (0.00 offset, ie price = $5.00), Medium (0.20 offset, ie. price = $5.20, and Large (0.50 offset, ie. price = $5.50).
    Alternatively, set up a Tankard at a price of $50, with attributes of Silver (0.00 offset, ie. price = $50) and SilverPlate (-12.00 as percentage, ie. price = $44.00) - eg. discounted!
    Percentage offsets are always calculated as a percentage of the base price, not compounded.
  • All Attributes and their settings are listed by Group on the Admin - Attributes page. From here, Attributes can be editted or deleted.
  • Deleting an attribute will also remove that attribute from any products to which it may have been assigned.
    Be wary of deleting attributes, because if you have any orders that include products with those attributes selected, they will no no longer be visible via Admin!
  • After one attribute has been added, when adding or modifying any subsequent attribute(s) a drop-down select box will give you a list of the Groups currently in existence so that they will match accurately. Note that the User Input Group will always appear in the dropdown, even if no attributes have been defined for that Group (see the User Input Fields section below).
  • When attributes have been added, they can be asigned to any number of products from the Product List form, by clicking on a new Attributes button next to the 'Edit Product' button.
  • Hovering the cursor over the Attributes button on the Product List form will display the assigned Attributes for that Product (if there are any) and the appearance of the button itself indicates which products have attributes assigned.
  • On the Attribute Assignment form, all attributes are listed within their allotted Groups. Simply check the relevant boxes to allocate them to the product. Repeat for all appropriate products.

User Input Fields

There is a reserved Group which can be used to define an Attribute as a User Input field, which means that instead of all the attributes within this Group being uniquely selectable from a dropdown, any assigned User Input Attribute is presented as an input box for the User to enter text.
  • Attributes defined in the User Input Group can be set as optional (all other standard Attributes are considered mandatory).
  • The Attribute Name is used as the label for the input field when presented to the User.
  • Offset and Percentage have no meaning for User Input Attributes.
Beware of using the Optional flag too liberally - if a product only has optional attributes assigned, then the User is not automatically redirected to the Product More page from the Product List page, as happens with mandatory assigned Attributes.

Special Prices

From the Attribute Assignment form a product can be assigned a Special Price. That price is then displayed on the Product List form, alongside the price it overrides. A Special Price can be removed simply by clearing the field on the Attribute Assignment form (a button is provided especially for that purpose, but you still have to remember to submit the form!).
A Special Price overrides the product's real price (as set through Product Maintenance) throughout the shop front-end, including when calculating any Attribute Offsets that might also be applied to the product.
One point to note is that the Attribute Assignment form is only available if at least one attribute has been set up. This means that if you wish to use the Special Price capability but you do not need any attributes, you should still set up one 'dummy' attribute (you don't have to assign it to any products) so that the Attribute Assignment form will be displayed for entering a Special Price.

Shop Front-End

  • With the exception of optional User Input fields any attribute is considered to be a required input field.
  • The Product List does not show attributes, but clicking on the Add-To-Cart button will redirect to the Product More page if there are attributes assigned to the product.
  • On the Product More page, standard attributes are presented in drop-down selection lists below the Quantity input box, with the offset (if applicable) in brackets after it.
    The User Input fields are presented below any assigned standard attributes, with their relevant Name (Label) just above them.
  • Selection of a valid entry is checked using a script, except where a User Input field has been declared optional.
  • Where an offset is applicable, the price displayed for the product is adjusted.
  • All Basket displays will list the selected/entered attribute values in brackets after the product name.
  • You can add the same product to the Basket but with different attribute values selected/entered. Adding the same product with the same attribute values will simply increase the quantity of the existing entry.

Language

By default this plugin is only supplied with an English language file - /plugins/productAttributes/lang-en.php.
If you wish to provide translations for your own language, copy lang-en.php to lang-[2-char-code].php (within the same folder), where [2-char-code] is the recognised code for your language. For example, a Polish language file would be /plugins/productAttributes/lang-pl.php.
The plugin will automatically load the English file first, and then look for the language file in the Shop's configured language, so that the English text is always there as a backup.

Template Files

A number of template files have been provided as part of this plugin, some of which are obvious - the productAttributes.tpl/.css files, for example - and some of which are less so. The template files that begin with the prefix 'pa.' fall into 2 categories:
  1. Those that provide limited Block replacement of core Quick.Cart templates, eg. /template/pa.products_more.tpl, and
  2. Those that provide limited Block replacement of other plugin templates, eg. /templates/pa.productsInRow.tpl.
The modifications contained in any 'pa.' prefixed template file can be editted into the file it replaces. There is a configuration variable (an array of template names) that controls which template file the Product Attributes plugin uses. An entry in the array means that Product Attributes will use the 'pa.' prefixed version of that template file, so if you integrate the changes into the Quick.Cart standard templates (or template(s) from other plugins) then the entry needs to be removed from the array. Meantime, please be aware that these 'pa.' prefixed files exist and that if you wish to make changes to layout you may need to edit these files rather than their original counterparts.
For example, if you wish to modify the format of the original and Special prices displayed on the Product More page, you might need to look at the /templates/pa.products_more.tpl in conjunction with the /templates/productAttributes.css files in order to effect the required changes.
You sould also be aware that the Product Attributes plugin uses functionality provided by the extendTplParser class extension, part of the Plugin Manager release. This class extension enables intercepts on calls to the template parser, which allow for functions to be run prior to parsing templates, and for additional templates to be parsed during and after handling any particular parsing call - without having to change core code! This means that it can sometimes be a bit tricky to track down exactly which template file is providing a certain bit of HTML, but the huge advantage is the improved simplicity of installation when editting of templates can be kept to an absolute minimum.

sendOrderToClient v0.2

The sendOrderToClient plugin has its own template file - templates/sendOrderToClient.tpl - with a block in it called LIST_LIST. This block has been overidden by a new block called BASKET_LIST_LIST_SOTC in the templates/productAttributes.tpl file. The new block has the same text-only fields as the original, but also includes the attributes that have been selected for the basket item.

Change Log

Version 2.4

  • Templates : modified pa.products_more.tpl to pass currency symbol to javascript in HTML rather than as a Javascript variable; modified pa.products_list.tpl, pa.products_more.tpl, pa.products_print.tpl and pa.productsInRow.tpl to provide compatibility with QCv1.3 and productsInRow v1.2 (maintaining backwards compatibility).
  • CSS : minor addition for backwards compatibility pre-QCv1.3, given template changes above.
  • JS : fixed bug in checkAttributes_Offset function that caused zero price to be displayed for certain currencies.
  • Setup : upped version number.
  • Documentation : updated to v2.4.

Version 2.3

  • Templates : fixed bug in pa.products_more.tpl whereby the standard price of a product with selectable attributes was losing its currency symbol whenever the price was modified by an attribute offset.
  • CSS : made a small modification to the styles for the selectable attributes in the Add To Cart box to provide more width for the attribute dropdowns.
  • Setup : upped version number.
  • Documentation : updated to v2.3.

Version 2.2

  • Code : updated checkAttributes.js so that it doesn't break when/if the Prototype JavaScript Framework is included (used by Lightbox v2.02 in the imageWatermark v1.1 plugin); updated productAttributes.php to handle the sendOrderToClient plugin
  • Templates : added 2 extra blocks - BASKET_ATTRIBUTES_SOTC and BASKET_LIST_LIST_SOTC - to handle the sendorderToClient plugin.
  • Setup : upped version number.
  • Documentation : added sendOrderToClient and imageWatermark compatibility; updated to v2.2.

Version 2.1

  • Code : updated intercept 'run-before' functions (attributes.php and actions_client.php) to make Last Product and Random Product plugins compatible with Product Attributes.
  • Templates : removed spaces from within a link in pa.products_more.tpl - for XHTML compliance
  • Setup : upped version number.
  • Documentation : added warning about trying to use Special Prices without having any attributes defined; updated to v2.1.
~~ The End ~~