Version: 2.4
Release: Jul 31, 2006
Compatibility: QC v1.0+
Languages: en
Author: Wizzud
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
- 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!
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.
- Copy the entire productAttributes folder from the release/plugins/ folder into your Quick.Cart plugins/ folder.
- Copy the contents of the release/templates/admin/ folder to your Quick.Cart templates/admin/ folder (2 new files: productAttributes.tpl and productAttributes.css).
- Copy the contents of the release/templates/ folder to your Quick.Cart templates/ folder (6 new files, NOT the Admin folder!).
- 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.
- 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>
- 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:
- Those that provide limited Block replacement of core Quick.Cart templates, eg. /template/pa.products_more.tpl, and
- 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 ~~