Readme.html

Product Attributes - Option Type Feature

by Chandra Roukema <chandra@OpenStoreSolutions.com>

This ReadMe Created: September 6, 2002

Last Updated: September 2, 2003

Released under the GNU General Public License

For more information visit http://www.OpenStoreSolutions.com/option_type_contribution.php

-------------------------------------------------------------------------------------------------

Index:

1. Introduction

2. Acknowledgements

3. Installation Instructions

4. How to Setup Products to Use Different Option Types

5. Frequently Asked Questions

-------------------------------------------------------------------------------------------------

1. INTRODUCTION

What does this contribution do?

This contribution allows the use of various option types when setting up product attributes. With the current milestone of osCommerce, all options are displayed as select lists. This contribution specifically adds Text Options, Radio Buttons, and Checkboxes. It is written so that it can be extended with other option types as well.

To make this more clear, lets look at the example of a store that sells coffee mugs with the end customer's name printed on them. The store owner might want a coffee mug to have a size option, a color option, a first name option, a last name option, an option to have the package gift wrapped, and an option to fill the mug with candy. In this case the available options section of the product info page might look something like this:

Size:

Color:

Blue

Yellow

Orange

First Name:

Last Name:

Gift Wrap:

Fill with Candy:

Additional Functionality

As of version 1.1 of the Option Type Feature, you can also specify a comment to be displayed to the left of an option. The comment functionality is applicable to any type of option.

Color:	(Here's a comment)
First Name:	(And another comment)

More Information

For more information visit http://www.OpenStoreSolutions.com/option_type_contribution.php. This page contains links to an example site using the contribution.

-------------------------------------------------------------------------------------------------

2. ACKNOWLEDGEMENTS

A special thanks to Dominik Guder <osc@guder.org> who was instrumental in version 1.4 of the contribution.

Thanks to everyone who has provided comments and pointed out bugs.

-------------------------------------------------------------------------------------------------

3. INSTALLATION INSTRUCTIONS

STEP 1. Add new fields to db

Add the following fields to table products_options

You can either use the enclosed option_type_feature.sql or the following definitions

NAME: products_options_type

TYPE: int(5)

NULL: No

DEFAULT: 0

NAME: products_options_length

TYPE: smallint(2)

NULL: No

DEFAULT: 32

NAME: products_options_comment

TYPE: varchar(32)

NULL: Yes

DEFAULT: NULL

Add the following field to table customer_basket_attributes

NAME: products_options_value_text

TYPE: varchar(32)

NULL: Yes

DEFAULT: Null

STEP 2. Install files containing the feature into your version of osCommerce

If you are using a clean osc-MS1 installation, then you can replace the files. But don't forget to backup your files first!!! Be especially careful with catalog/includes/configure.php. If you configure your webserver and database in this file, then you will need to merge this file (not replace it) even when using osc-MS1. See instructions below on how to merge catalog/includes/configure.php.

If you are not using a clean osc-MS1 installation then you must merge (*NOT* replace) the files.

The following table lists the files that were changed in the process of implementing the "Option Type Feature" along with a high level description of the changes to each file.

File	Summary of changes
catalog/product_info.php	Checks option type and properly displays options on the product_info page.
catalog/shopping_cart.php catalog/includes/classes/shopping_cart.php	Checks option type when adding products to the shopping cart. Performs special handling for products with text attributes.
catalog/checkout_process.php catalog/includes/classes/order.php	Checks option type when creating/submitting an order. Performs special handling for products with text attributes.
catalog/includes/configure.php	Sets configuration parameters used by the option type feature.
catalog/includes/functions/general.php	Updates function tep_get_uprid to work correctly for products with text attributes. Adds function tep_decode_specialchars.
admin/products_attributes.php	Adds a dropdown for setting option type
admin/includes/languages/*/products_attributes.php	Adds appropriate text defines for the file above

The files are included in the zip with this readme. The original version of these files are from the osc-MS1 distribution. A copy of the original version of the files are also included in the zip. If you are merging the files, then you are strongly encouraged to use your favorite diff program to compare the files and view the changes. Free and easy to use diff programs for MS Windows platforms include ExamDiff (http://www.prestosoft.com/ps.asp?page=edp_examdiff) or WinMerge (http://winmerge.sourceforge.net/).

All changes start with (or are near) a comment beginning //CLR or //dogu

configure.php

Only minor changes have been made to the file catalog/includes/configure.php. To merge this file add the following lines to the end of your catalog/includes/configure.php:

// CLR 020605 defines needed for Product Option Type feature.
define('PRODUCTS_OPTIONS_TYPE_SELECT', 0);
define('PRODUCTS_OPTIONS_TYPE_TEXT', 1);
define('PRODUCTS_OPTIONS_TYPE_RADIO', 2);
define('PRODUCTS_OPTIONS_TYPE_CHECKBOX', 3);
define('TEXT_PREFIX', 'txt_');
define('PRODUCTS_OPTIONS_VALUE_TEXT_ID', 0); //Must match id for user defined "TEXT" value in db table TABLE_PRODUCTS_OPTIONS_VALUES

STEP 3. Set up your TEXT Option Value.

Add a new record to the table products_options_values.

You can either use the enclosed insert_text_option_value.sql or you can manually update the table.
(Note: The file will create three entries with products_options_values_id=0. One with language_id=1 (English), one with language_id=2 (German), and one with language_id=3 (Spanish). If you use other languages then you must create a new entry for each additional language.)

products_options_values_id	language_id	products_options_values_name
An id that is unique to the table. Recommend 0 if it is unique or last id + 1.	Set to your language id	TEXT

IMPORTANT: You should create *exactly one* TEXT Option Value. Once you create this value, you should not change it.

If you use a products_options_values_id that is different than 0, then you also need to update the following line in your catalog/includes/configure.php file.

define('PRODUCTS_OPTIONS_VALUE_TEXT_ID', 0); //Must match id for user defined "Text" value in db table TABLE_PRODUCTS_OPTIONS_VALUES

-------------------------------------------------------------------------------------------------

4. HOW TO SETUP PRODUCTS TO USE DIFFERENT OPTION TYPES

4.1 How to Create a Text Option (or two or three...)

To explain how to create a text option, we'll walk through the example of adding a text option called First Name to a product called Coffee Mug.

STEP 1. Use the admin tool to create a new Products Option. (In upper left table)

OPTION NAME: First Name

Set the Option Type equal to 'Text'. This is done using the option type dropdown. (If you don't see an option type dropdown, then you likely didn't install the admin files that came with this feature.) The option type can also be updated manually in the table products_options.

OPTIONAL:

Also in table products_options set the products_options_length and/or products_options_comment. These values must be manually edited in the table.

The products_options_length determines the max length of the text option. It is limited to 32 characters. (This limit is based on the size of fields in the customer_basket and order tables where the text value is later stored. This limit can not be changed without effecting other functionality. Be sure you know what you're doing if you attempt to increase the length beyond 32 characters.)

The products_options_comment is the optional comment that is displayed next to the option. It is limited to 32 characters. (This limit can easily be changed by adjusting the size of the product_options_comment field. Changing the size of this field does not effect other functionality.)

STEP 2. Use the admin tool to create a new Product Attribute.

PRODUCT NAME: Coffee Mug

OPTION NAME: First Name

OPTION VALUE: TEXT

VALUE PRICE: 0

PREFIX: +

STEP 3. Update the Product Options to Product Options Values mapping.

Some contributions require that the products_options_values_to_products_options_id table list the mapping of option types to option values. If you use one of these contributions, then you must add a new record to the products_options_values_to_products_options table whenever you setup a new text option. Currently there is no admin tool for this step, so you must do it manually.

products_options_values_to_products_options_id	products_opitons_id	products_options_values_id
Let this autogenerate	Id from step 1	value of PRODUCTS_OPTIONS_VALUE_TEXT_ID (likely 0)

It is recommended that you keep the products_options_values_to_products_options_id table up to date, even if you don't use contributions that require you to do so. This is to ensure compatibility with future enhancements that you may want to use.

You're done with the set up. On the product info page for "Coffee Mug" there will now be the option "First Name" followed by a text box for user input.

4.2 How to Create a Select List or Radio Button

You add a select list to a product exactly the same way you would if you were not using this contribution.

1. Create an Option. (the default type is select).

2. Create Option Values

3. Create product attributes that associate your Option and Option values with a product.

You add a radio button control to your product in the same way as you would a select list. The only difference is you set the Option Type of the Option to "Radio" instead of "Select".

4.3 How to Create Checkboxes

The important thing to understand about checkboxes is that the Option Value is not displayed on the product_info page.

For example if you set up an Option named "Gift Wrap" (with type equal Checkbox) and an Option Value named "Checked" and associate these with your coffee mug product, then on your product_info page you will see.

Gift Wrap:

If Gift Wrap is checked, then in the shopping cart, order confirmation, and confirmation email you will see

Coffee Mug

- Gift Wrap Checked

This approach allows you to add as many checkboxes to your products as you like.

-------------------------------------------------------------------------------------------------

5. FREQUENTLY ASKED QUESTIONS

Q. What if I'm using a different version of osCommerce then what the contribution was designed for?

A. You can still use the contribution, but you will need to merge the contribution files with your files. If you're using an older version of osCommerce, then check the older versions of this contribution to see if one matches your osCommerce version. For example there is a version of this contribution that works with osCommerce 2.2 Milestone 1. If you use an older version of the contribution, then check the release notes (ReleaseNotes.txt) to make sure the older version of the contribution contains the features that you need.

Q. What if I have customized my osCommerce store, but I want to use this contribution?

A. You can still use the contribution, but you will need to merge the contribution files with your modified files. The contribution is easiest to install when you use an unmodified version of the osCommerce Milestone that the contribution is designed for.

Q. The Option name isn't being displayed in the shopping cart, order confirmation, or confirmation email?

A. This almost always indicates a problem with your data. Make sure that

define('PRODUCTS_OPTIONS_VALUE_TEXT_ID', 0); is set correctly in your configure.php. Also make sure that your product attribute is associated with the correct Option and Option Value. A common mistake is to associate a text Option with an Option Value other than TEXT.

Q. My confirmation email is displaying TEXT instead of the custom text that the user entered?

A. This typically indicates a problem with either catalog/checkout_process.php or catalog/includes/classes/order.php. Check that you have installed or merged these files correctly.