An osCommerce Demo is now available. This demo is the default install from the cPanel Fantastico setup wizard available with many hosting packages. This install requres no technical skills and takes about a minute to install. No significant modifications have been made after the install in order to demonstrate the basic features included.

Please note that the basic install displayed in the demo is the “core” install without modifications. Check out our osCommerce Forum to get some examples of configured operational sites.

Well we have finally reached the end, although perhaps the most important part. The reason we went through all the trouble, and actually display something on a page in our store. Before we get our hands dirty today, I want to explain the prime motivation of this series. I may very well be that you have been sitting there for a spell of time with the dire need to add a sample file field to your products listing, and shortly you may have all of it worked out for you. If that is the case, excellent!, I am happy to help out.

However my aim here was not to try and target a small handful of people with that particular need. Rather my hope has been and is to provide some tips which cover a wide range of modifying osCommerce. I have attempted to take you through some of the thought process, I have gone through myself trying to learn and figure out the system. Most of the knowledge I have gained concerning osCommerce has come from digging into the code and just plain old figuring it out. So hopefully this series has been helpful to a few or more of those reading. Even more I hope that it sparks your abilities to take things even further as you use this very robust system. And now off to the races....

So we've taken care of the admin portions of this project. Now we need to display something on a page in our store which makes it all worthwhile. In the process we will be working with several files, configure.php, a language file, and a few others.

There are a couple of different approaches we could take, however for this tutorial we'll take the simple and straight forward approach. We'll use a simple HTML link which our site's visitors will be able to click on in order to listen to the sample file. We will also display the link on the Product Information page (product_info.php). An alternative approach would be to display the link on the grid listings of products, however that gets a little more complex and I want to finish this series without a couple of more steps. You should however be able to apply the information here if you did choose to display the link on any other pages than what will be demonstrated.

If we look at the Product Information page, we have the product title and price at the top. Below is the product description. Further down are the product attributes and finally the 'Review" and 'Add to Cart' buttons. We will be placing our link directly below the product description. The link will contain the text 'Listen to a Sample'. Therefore the first thing we need to do, because we are placing text on the page, is add an entry to the language file for the page. If you have had a change to read my article on language files, you know that you will need to open /includes/languages/english/product_info.php. Since I've also covered the territory in the other article I won't repeat myself here, if you haven't read that article now would be a good time.

With the /includes/languages/english/product_info.php file open, add this line of code just above the final ?> tag, and of course save the file when you are done:

define('TEXT_LISTEN_SAMPLE', Listen to a Sample');

OK with that step complete lets turn our attention to the physical location of our sample file. We can store the sample files anywhere that we want on the web server, for this example we will use a 'samples' folder which is directly under the root folder for osCommerce which is usually 'catalog'. That would make the location of the samples folder catalog/samples/.

When we are adding or updating a product it will make things a lot easier if all we have to do is enter the file name for our samples rather than the complete path. What will enable us to do that is an entry in the includes/configure.php file. Just like with the language file, anywhere above the final ?> tag, insert this line of code:

define('DIR_WS_SAMPLES', 'samples/');

Save and close the configure.php file and now its time for home stretch. Open up the product_info.php file. It should make perfect sense that anytime the system displays something like product information that is stored in the database, the first thing that needs to happen is for the system to query the database for that information. On line 72 is where this happens:

$product_info_query = tep_db_query("select p.products_id, pd.products_name, pd.products_description, p.products_model, p.products_quantity, p.products_image, pd.products_url, p.products_price, p.products_tax_class_id, p.products_date_added, p.products_date_available, p.manufacturers_id from " . TABLE_PRODUCTS . " p, " . TABLE_PRODUCTS_DESCRIPTION . " pd where p.products_status = '1' and p.products_id = '" . (int)$HTTP_GET_VARS['products_id'] . "' and pd.products_id = p.products_id and pd.language_id = '" . (int)$languages_id . "'");

In case you aren't familiar with the way osCommerse does SQL selects here's a brief explaination. Take a look at this portion of the code:

TABLE_PRODUCTS . " p

osCommerce uses the database_tables.php file to define the table names in the database. 'TABLE_PRODUCTS' is defined as the 'Products' table. The above line of code therefore would translate out to 'Products p'. In SQL the 'p' then becomes an alias for 'Products'. Now look at this piece of code:

p.products_id

This is the same as saying 'products.products_id' or the 'products_id' column of the 'Products' table. Way back in part 2 of this series we added the 'products_sample' to the 'Products' table. Therefore we need to retrieve that value when we do the query. It makes no difference where its added as long as it is before the 'from' keyword in the statement. Also remember to insert a comma between each column being retrieved. When complete a portion of the statement might looks like this:

select p.products_id, p.products_sample, pd.products_name, pd.products_description,

The SQL statement should now be complete. The following line after the SQL statement is:

$product_info = tep_db_fetch_array($product_info_query);

tep_db_fetch_array is another osCommerce function that performs the retrieve on the database and returns the result set in the form of an array, in this case $product_info. The values contained in the array are then accessed using the array subscript in this manner: $product_info['column_name']. We will need to add the code to grab the sample file name from the array, on line 88 is a closing ?> tag. Insert a line above that tag and add this code:

$sample_file['sample_file']

And now we are on the home stretch. On line 120 is this line of code:

<p><?php echo stripslashes($product_info['products_description']); ?></p>

Insert a line directly below that one and add this which will be our link display:

<p><?php echo '<a href="' . tep_href_link(DIR_WS_SAMPLES . $sample_file) . '">' . TEXT_LISTEN_SAMPLE. '</a>'; ?> </p>

And guess what? We are all done! Now from that line of code we have the constant name for the samples folder, so say our sample file for this product was tune1.mp3, the link would look like:

http://www.storexyz.com/catalog/samples/tune1.mp3

And the displayed text for the link would be 'Listen to a Sample' as we have defined it.

This concludes this multipart series of Adding a Field, I hope that you the reader have gained some knowledge and enjoyed reading as much as I have writing. My great love in life is sharing knowledge to those anxious and willing to learn. I would hope that you would take some of the principles and ideas here and apply them in your own way. I would also encourage anyone working with osCommerce to have a test/development installation of the system so that you may experiment and try things out. In my opinion there is no better way to learn.

Happy Coding!

Now that we have a spot in our database and an input form for our new field, we can turn our attention to processing that form and adding the data collected to the database. If you haven't done so already go back and review the previous parts of this series as I intend to just right in.

You will recall that the action property of our new product form contained a property of "action='new_product_preview'. If you have been using osCommerce for any length of time, and I assume you have otherwise you probably wouldn't be reading this article, you know that when adding a new product after all the data is entered you click on a 'Preview' button, you are then taken to a review page. However it's not a complete preview, the preview only shows a few pieces of information such as the item title, description, image, and price.

If I haven't said so before and if I have it's worth saying again, the categories.php file is very long and complex. Fortunately Dreamweaver, my favorite PHP/HTML editor, has a handy find and replace tool. Performing a search on 'new_product_review', I find on line 596 the following:

} elseif ($action == 'new_product_preview') {

This just happens to be the 'elseif' for the 'if' that initially loaded our form. The page is self posting, so again the first time through the form is loaded and the second time through we load the preview presentation. All of this is accomplished by changing the action parameter and simply running a different section of code each time. If we browse through the code below line 596 we may see the code is dealing with the gathering and display of items which appear on the preview page. Our new sample file field is not a part of the preview, so we don't need to be too concerned just yet. However there is something interesting on line 610:

$form_action = (isset($HTTP_GET_VARS['pID'])) ? 'update_product' : 'insert_product';

It's beginning to look like categories.php is even more polymorphic than we could have imagined. Line 610 is setting the action property for the form which is the preview page. What we see here is form of 'IF" statement short hand. The syntax goes something like this:

$var = (some condition) ? if true $var = this : if false $var=this

In other words $var will be equal to the value after the '?' if the condition is true or it will be equal to the value after the ':' if the condition is false. What line 610 is saying is if the pID exists we are going to perform an update of the product. However if there is no pID then we have a new product so therefore we are going to do an insert. Browsing through the remaining code down to the form end tag confirms we do not have to code anything for our new field at this point.

As far as we are concerned this is not a situation of 'either/or' because we will need to deal with both conditions, we will need to have the capacity to work with the new sample field when we create a product and later if we happen to want to update it. Follow the natural progression we'll start with 'insert_product'.

Performing a text search for 'inset_product' look what we find on line 205:

case 'insert_product':

I told you we would get back to the case statements eventually, and the time is now. A quick note here, you might be thinking, we were down at line 610 how did we get all the way back up to line 205? Well remember each time we click a submit button, the page posts back to itself and we start at the top again. So we know from the discussion in part 3 that when we find a case condition that is true, the code below it until we hit 'break' will be executed. An look what we find on line 206:

case 'update_product':

That's right, it appears that we are only going to have to work with one block of code for both the insert and the update, that's a nice little relief. We are getting closer and closer to having our project complete and that's always a good feeling. Moving forward we skip down to line 215 to 222:

$sql_data_array = array('products_quantity' => tep_db_prepare_input($HTTP_POST_VARS['products_quantity']),
'products_model' => tep_db_prepare_input($HTTP_POST_VARS['products_model']),
'products_price' => tep_db_prepare_input($HTTP_POST_VARS['products_price']),
'products_date_available' => $products_date_available,
'products_weight' => tep_db_prepare_input($HTTP_POST_VARS['products_weight']),
'products_status' => tep_db_prepare_input($HTTP_POST_VARS['products_status']),
'products_tax_class_id' => tep_db_prepare_input($HTTP_POST_VARS['products_tax_class_id']),
'manufacturers_id' => tep_db_prepare_input($HTTP_POST_VARS['manufacturers_id']));

As it turns out this is the only section in this block of code and the last in categories.php we will need to modify. However I want to explain a couple of things. The above section of code is adding most of the fields from the new products/update products form to an array, $sql_data_array. The function 'tep_db_prepare_input' is another handy funtion built into osCommerce. The function serves to format things into a SQL statement. If you have ever had to write code that generates SQL insert or update statements, you know just how handy it is. Moving down to line 233 we find:

tep_db_perform(TABLE_PRODUCTS, $sql_data_array);

'tep_db_perform is another function which is abstract to us, it takes care of either the insert or update and we don't have to worry about anything else. Ok so lets go back to $sql_data_array, for the sake of simplicity I'm only going to show the last line:

'manufacturers_id' => tep_db_prepare_input($HTTP_POST_VARS['manufacturers_id']));

We need to add 'products_sample_file' to this array so once we are done the last two lines will look like this:

'manufacturers_id' => tep_db_prepare_input($HTTP_POST_VARS['manufacturers_id']),
'products_sample' => tep_db_prepare_input($HTTP_POST_VARS['[products_sample']));

So now our new sample file field will become part of the array and part of the insert/update statement to the database. And there you have it, we're all done with the admin side of things. However we do have one important step to go, and that is how we are going to display things to our customer who visits our store. We'll cover that in the next and final part of this series.

Happy Coding!

Ok ok, I know apologies are in order. I never anticipated it would take me this long to finish this series, not to mention having so much time transpire between entries. However some times life has a way of directing your attention to other areas. So it happens, enough said about that, however I am sorry it has taken me so long.

I also started this series with the assumption I would be able to complete this process in three steps. Another dose of reality, its going to take a few more, there is simply too much left to be covered. So expect a few additional parts to this series. Ok ready? I think I am so lets get started.

In the previous parts we were able to determine the need and we managed to set up the database for our new field. It is now time to dig into some code. The file/page in question can be found at /admin/categories.php.

As with several of the files in the admin are of oscommerce, this file actually performs several purposes. Also as a quick side note here, because there were standards applied with the development of oscommerce, the design here and the skills I will talk about here may be applied to other areas, so keep that in mind.

The categories.php file provides management of both categories as well as products. In relation to those two, this file performs the processing which enables the store administrator to Insert new, Update existing, Delete existing, and Move existing items. The file manages to perform all of this functionality through the use of a PHP "switch" function.

If we were to go into the admin area of our store, click on the Catalog->Categories/Products link, and from there click on the "New Product" button, we would see the page to enter a new product. And if we were to examine the URL in the address bar of our browser, we would see something like this:

http://www.somestore.com/catalog/admin/categories.php?cPath=&action=new_product

Of course the URL points to the categories.php file, however it also has a couple of parameters. One of these is "action". The "action" parameter is what tells the file which functionality, as outlined above, it is being asked to perform. In this case we clicked the "New Product" button and the action is "new_product".

Lets take a look at the code. On line 18 of the current default installation we see the following:

$action = (isset($HTTP_GET_VARS['action']) ? $HTTP_GET_VARS['action'] : '');

Since "action" is being passed through the URL, it is known as a "GET" variable. This line of code takes the "action" get and passes it to the PHP variable $action.

Scrolling down a few more lines, we find this code:

if (tep_not_null($action)) {
switch ($action) {

The first thing we are going to do is check to make sure that "action" is not null. If "action" is not null, then we can go ahead and move forward. We move forward by calling the switch function and passing the value of $action to the function. The syntax of a switch function works like this:

switch(some variable){
case value of variable: execute some code // if this is the value of the variable, then run this code
break; // stop processing and get out of the switch function
}

Based on that syntax we can search through the code looking for "case 'new_product' ". The problem is we don't find it, however on line 357 we do find:

if ($action == 'new_product') {

I know what you might be thinking, "why go into this explaination about the switch function when its not being used?" Well that is correct in this specific case it is not being used. However we will be using it later and what I am attempting to do here is go through the process you might go through to find code you wish to modify. We are going to encounter that switch function when it comes time to process our form. However for now, it does not apply to our currect page display. Why things were designed this way, will become a little more clear as we progress. For now just have a little bit of faith there is some form of reason to what at this point might appear as madness.

The if statement above includes many lines of code, and if you haven't gotten the idea by now, like a significant portion of oscommerce code performs more than one task. For the present time lets jump over some of this code and drop down to line 463. On that particular line, we begin to define our input form. If you are familiar with HTML code, which if you have gotten this far I assume you are, you might expect a form tag to look something link this:

form action="somefile.php" method="post"

However, oscommerce doesn't normally use standard HTML tags especially when it comes to things like forms. Oscommerce uses functions which encapsulate many HTML type tags. These functions are defined inside /admin/includes/functions/html_output.php and /includes/functions/html_output.php. So in this case rather than the standard HTML tag <form> we see:

echo tep_draw_form('new_product', FILENAME_CATEGORIES, 'cPath=' . $cPath . (isset($HTTP_GET_VARS['pID']) ? '&pID=' . $HTTP_GET_VARS['pID'] : '') . '&action=new_product_preview', 'post', 'enctype="multipart/form-data"');

Being familiar with the HTML <form> tag, most of these parameters should make sense. Scrolling down through the code we see many other such functions being called, tep_draw_radio_field defines a radio button, tep_draw_pull_down_menu defines a drop down list, tep_draw_input_field defines a text input box, and so on. We know that we are going to be using an input box for our new field, so lets take a closer look at tep_draw_input_field.

When it comes to making a modification of oscommerce code, the easiest way to approach this I've found is to look for something similiar and use it as a model. Browsing the code, I've found something we can use beginning at line 548:

<tr>
<td class="main"><?php echo TEXT_PRODUCTS_QUANTITY; ?></td>
<td class="main"><?php echo tep_draw_separator('pixel_trans.gif', '24', '15') . ' ' . tep_draw_input_field('products_quantity', $pInfo->products_quantity); ?></td>
</tr>

It appears this will work for us, so lets copy this code and paste it as a new input box for the form. Line 594 contains the end tag for the form, so paste it just before that line. Make sure that its after the <tr> that is currently on line 593. For this particular phase of our task, all we need to do is make a few changes so that things reflect our new field. We need to change the label and of course the name of the field. Once we are done, things should look like this:

<tr> <td class="main"><?php echo TEXT_PRODUCTS_SAMPLE_FILE; ?></td>
<td class="main"><?php echo tep_draw_separator('pixel_trans.gif', '24', '15') . ' ' . tep_draw_input_field('products_sample', $pInfo->products_sample); ?></td>
</tr>

Now of course, TEXT_PRODUCTS_SAMPLE_FILE is the label for the form object and represents a language file constant. So we will need to go into /admin/includes/languages/english/categories.php and add that definition. Something like this:

define('TEXT_PRODUCTS_SAMPLE_FILE', 'Sample File');

Once we have performed that step, we are done, with the presentation part anyway. However we still have much work to do. Next time we will look at how we are going to process the form once it is submitted.

Happy Coding!

Last time we talked about our plan to add a new field to the products display. We discussed what we are going to do, now its time to talk about how to do it. There is a lot of information to cover, and technical information at that so lets jump right in.

A common tool for managing databases which is available with many web hosts is known as phpMyAdmin. It's the tool I always use, so these instructions will based around using phpMyAdmin and will serve as a mini tutorial on the tool itself. If you don't have phpMyAdmin available and you haven't worked on you database directly before, you'll want to check the documentation that comes with your hosting control panels or contact you hosting company for advice.

phpMyAdmin provides a graphical user interface for working with databases that makes most tasks fairly easy to perform. Its accessible through an icon or link on your hosting control panels. My web hosting uses cpanel and I also have an unlimited number of databases available to me. Therefore when I click on the database icon within my control panels, I'm presented with a screen which allows me to manage the user accounts for my existing databases as well as create new ones. Scrolling down to the bottom of the screen, I find a link to phpMyAdmin, which I click on to take me to that tool. If yours is layout differently and you have trouble finding phpMyAdmin, consult your web host for directions.

Ok, so now hopefully we are all inside the phpMyAdmin tool. Again because I have multiple databases available to me, I'm provided with a dropdown list to select the database I wish to manage. If that is the case for you, find your osCommerce database in the dropdown list and select it. If you only have one database available, you will likely already have the database selected.

phpMyAdmin uses a frames layout, so with the database selected, in the left hand frame you have a list of the tables that make up your osCommerce database. We want to scroll down that list and look for the "products" table. The listed name is a link, so clicking on it changes the display in the main frame on the screen.

Once we have clicked on the "products" table name in the left hand frame, we are presented with a structure view of the products table inside the main frame area, which looks something like this:



Here we see a list of the existing columns within the products table with their respective attributes. At the bottom of this list and underneath a horizontal bar is a small input form which is used to add a new field:



The default is to add one (1) new field, however we can change that value to add as many new columns as we like. In this case one is all we need so we'll leave it at the default. Next we have a series of radio buttons which allow the ability to change the order of the entry point for the new field. In most cases added it to the end of the table works just fine, so we'll also leave things in the default. Everything is all set so we can go ahead and click on the "Go" button.

We now arrive at a new screen which is a form for our new column definition. I've cropped the image to make it display better on this page, yet kept the important input boxes for our task:



The inputs we will be working with here are Field, Type, Length/Values, and Null. I'll give a brief explanation as to the type of information that needs to be entered as well as what should be entered for our specific example.

Field is the name of our new column and how the column will be identified with any SQL calls we make in our code. We'll enter "products_sample" here. The osCommerce convention is to use column names which are prefixed by the table name followed by an underscore and a descriptive name. In most cases its best to keep that descriptive name short yet long enough to be self documenting. The reason for keeping it short is that we are going to have to type that name in our code, obviously keeping it short means less typing and less chance for errors.

Type refers to the data type of the column. There are many different types available although they primarily fall into four categories, text, numeric, date, and Boolean (true/false). The default here is varchar which happens to be the most common column data type. Varchar is a type of text or character type which provides some efficiency in the way the data is stored. Varchar has the ability to adjust downward to the size of the data which is stored within the particular column. This helps to decrease the amount of disk space required to hold the data base. Since our new column will hold character data, we'll leave the default at varchar.

Length/Values defines the size of the new column and with varchar refers to the number of characters the field will hold. It's good practice to define the size of the column at a reasonable size, in other words not to go overboard yet large enough to hold the foreseeable data which it will hold. If need be we can always go back and make the column larger, however generally speaking you don't want to be doing that on a regular basis. In our example we need enough space to display the file name with it's extension. We'll store all the sample files in a central location so the path will be common to all sample files and therefore we won't need to store the path. I'm thinking 50 characters should do the trick, so we'll enter 50 for the Length/Values input box.

Null tells the database whether or not it will accept a new row in the table with the column not having any value entered. There are some fields which should always contain a value, for example name. However if there is a chance the column will be empty and the application will still function normally we can define the column to allow nulls. Since there may be situations where we don't have a sample file for one or more of our products, we are going to change the default value here from "not null" to "null".

Let's review what we have entered in our new field definition. In the Field input box we entered "products_sample", for type we left things at the default of "varchar", in the Length/Values input box we entered 50 for the maximum allowable characters, and we selected "null" as the value for the null dropdown list. Ensure all these values are entered correctly and click the "Save" button at the bottom of the page.

Assuming all has gone as expected, we should now be taken back to the structure view of the products table. We should see that our new column now appears at the bottom of the list of column names. We're all set, this step is complete.

In part 3 we will get into the PHP code, we'll work on the product detail screen adding a new field to the form. We'll also write some code to capture the data entered into that new field and save it to the database.

Happy Coding!

A question I see asked from time to time in the osCommerce support forums is "how do I add a field to the products table?" That's a question that requires an answer a bit more involved than what can normally be provided in a forum post, so I thought I give a little tutorial on the process. There is quite a bit to cover so I am going to dispense with my normal mode and extend this one this one over several articles. As with most things its a little easier to grasp in smaller bites.

If you really want to know the truth, doing things like modifying the database or other such more "involved" changes is where the real satisfaction working with osCommerce comes in. In my mind it goes over and above making cosmetic changes and installing contributions. It's something where you can stand back when finished and have a sense of satisfaction that you have created something that is truly yours. Speaking of contributions, if you come up with something valuable you have the opportunity to support the community by sharing your work if you wish.

All of the things we will talk about here can be applied across the board for other things you might find yourself wanting to do with the system. I'll also share with you some of my lessons learned, so hopefully you might avoid some of the mistakes I've made as I too learned the system. One I'll share with you right off the bat. When I first started working with osCommerce I was mostly concerned with making it work and function the way I wanted. I didn't pay a lot of attention to the standards and structure of the application. That was ok from the sense that I accomplished my goals, however later on down the line, that get it done, make it work attitude came back to bite me. So we'll concentrate on doing things the osCommerce way.

Necessity is the mother of invention, so there of course needs to be a reason we want to add a field to the products table. Lets take a step back in time and talk about the need before we get into the solution. Suppose on our e-commerce web site, we are marketing original music. Since the music is original, our site's visitors are not going to be familiar with the product we have to offer. If we happened to be marketing hard goods, we can give our potential customers a taste of the product by displaying a picture. However with music a picture is not going to quite cut it. We need to give them a sample, a short edit of each song should do the trick and hopefully entice them to buy.

Browsing the new product input form we see fields for name, price, description, image, price, etc, however there isn't a field for "sample file", so we'll have to create one for our music store. Doing so is going to give us the opportunity to dig into the osCommerce source code. The job will require some effort an and hour or two of time, but its certainly an achievable goal.

The task of adding a field for our store's products will be accomplished in three distinct step. First we'll need to modify the database table by adding the new field. Second we'll work on the input form, adding the display of the new field and handling the code which will save the new field to the database. We'll also need to ensure the functionality works so that we can go back later and edit the new field when we need to. The last step will be to display the new field on the product listings page.

Now we have a plan in place, in part 2 we'll jump in with our DBA hat on and start making some database changes.

Happy Coding.

While osCommerce straight out of the box comes as a working shopping cart application, seldom will you ever see a production site using a completely stock version of the e-commerce application. In previous articles, we've talked a little bit about making some cosmetic changes. Today we are going to talk about functionality.

If I had to name the best feature of osCommerce, I would say without a doubt my answer would be that it is open source software. The fact that it is open source enables and environment where anyone is free to modify or enhance the software anyway they like. osCommerce benefits from a very large and active community, who not only participate by offering their help and advice, but also in the sharing of their work. In the osCommerce community this sharing of work are know as Contributions.

As I write this article there are over 3100 contributions available for free download on the osCommerce Contributions page. The available contributions cover nearly every feature one could imagine for an e-commerce web site. Quite frequently in the support forums, the answer to the question "can osCommerce do.......?" is check the contributions. There are contributions that cover everything from payment and shipping modules to template systems. I have to admit that one of my guilty pleasures is to browse the contributions looking at all the interesting and fun tidbits that can be added to a shopping cart. Everyone needs extra toys to play with, right? And while some might fall into that fun nice to have category, even more so contributions are there to fulfill valuable business needs.

Some of the more popular contributions are:

Credit Class & Gift Voucher - Enables a store owner to offer discount coupons and to make available gift cards for purchase.

Header Tags Controller - Enhances the SEO of your e-commerce web site by dynamically modifying the page title, description, and keywords so that they relate to the products being displayed on the particular page.

Simple Template System - Provides the ability to design the layout and visual design of your site through the use of HTML templates.

Pay with an Account - In the base install of osCommerce, the stores customer must create an account before she is allowed to check out. Pay without an Account allows your customers to complete a transaction without having to go through the registration process.

Installing a contribution can be a little confusing at first, however its not overly difficult with a little advanced knowledge of what to look for. Following the link to a contribution's page, its very common to find a list of downloads for the contribution. This happens for two reasons, one being either the original developer or others may discover and correct bugs in the contribution. Secondly further enhancements are frequently made to a contribution to the degree they often are listed with version numbers.

Generally speaking you would want to download the top listed file. However be aware that occasionally someone will fix a bug or make a small enhancement and only upload the files which were modified. In that case you would need to scan the list and find the latest full package, download it as well as everything that appears above it on the list. There is no doubt this can be a hassle at times, unfortunately its just the way it goes.

Once you have the file or files downloaded and unzipped, its very important to start by reading the "Read Me" file. This will generally give you the information you need to successfully install the contribution. In the case of having to download one or more small update files, the read me file will normally explain how to apply that fix to the full package.

The files for the contribution will normally be delivered in a directory format that follows that of the complete osCommerce package. If the update requires any database mods, there will usually be a *.sql file for that purpose. This sql file can normally be run in the query interface within the phpMyAdmin interface on your web host. Then its usually just a matter of modifying existing or uploading the packaged files to your web site, its normally the former and I'll explain.

The "Read Me" file will normally contain instructions for installing on a "clean install" and for a non clean install. A clean install, is an instance of osCommerce that has not had any changes applied to it, in other words straight out of the box, except for changes that might have been performed in the Admin Configuration tool. Once you have made any changes to your shopping cart, or applied any contributions you no longer have a clean install. That is important to know, because the instructions for installing a contribution on a clean install normally involve uploading the files in the package as they are. Doing so however over writes the existing files on the site. If you've made any previous changes to those files, the changes will be lost.

The installation for a non clean install is a little more involved and can at times be tedious. However don't be scared off, due to generally great documentation most people are able to perform the changes correctly. In most cases you can employ copy and paste from the new files to the existing ones. Most contributors will provide examples of existing code and line numbers to make it easier to find the correct locations to make the changes. The new code will also frequently comment the blocks of code being added to make it easier to identify the changes down the road.

The most important things to remember about applying a contribution are first to ALWAYS make a backup of any files before you change them. As a matter of good practice its a good idea to keep a complete backup of your osCommerce files away from your work environment. Its also important to take things easily and under control, don't rush through. If after you have completed the install of a contribution and it doesn't work right or you receive errors, take a deep breath and carefully retrace your steps to find the source of the error. Its not uncommon to have a misplaced comma or apostrophe. It can be difficult to debug when you are stressed out, but can be like a treasure hunt when you're relaxed.

One thing more while I'm thinking about it. It's important to not put yourself into a stressful situation when it might not be necessary. Don't try to install a major contribution the night before you "have to" go live. Give yourself plenty of time to design your site, especially if you haven't worked with osCommerce before. All too frequently I see posts in the support forum from people who are desperate for help because they need to make a deadline. Most of the time they are simply struggling just to get their feet under them. Take the time to learn and understand the system, and feel comfortable with it before you make promises. Its a great system and I believe most people can learn how to modify and manage it, just takes a little time and a little experience under your belt.

Happy Coding!

As with most complex web applications, osCommerce uses a style sheet to define much of the visual presentation of the pages within the system. Cascade style sheets (CSS) are the prefered manner for applying styles because all the style definitions are stored in a central location and therefore can be applied to multiple HTML files. Its also common to find what are know as inline styles, where the style is defined within the HTML tag:

<TD style="background:#FFFFFF">

They can also be found in the <HEAD> section of an HTML file between <style></style> tags. Although both of those methods require applying styles on a more individual basis. Hence, style sheets do save a lot of typing as well as helping to standardize the over all look and theme of a web site.

The style sheet for osCommerce is named stylesheet.css and found in the root folder of the osCommerce installation. For the purposes of osCommerce, style definitions come in three different flavors, Tag Styles, Class Styles, and Class Styles that are tied to a tag. These are three examples from the style sheet in respective order:

A {
color: #000000;
text-decoration: none;
}

.boxText { font-family: Verdana, Arial, sans-serif; font-size: 10px; }

TR.header {
background: #ffffff;
}

I purposely left the formatting of these examples the same as they are found in the style sheet to make it easier to follow along and identify, however it also serves to explain point. That is that line returns or any other sort of "white space" in style sheet code is ignored. So you can have all the styles on a single line or multiple lines, and even blank lines in between. The only important thing to remember is that the individual styles need to end with a semicolon.

Ok now back to the lesson at hand. The first example "A" is a Tag Style, meaning this style will apply to every "A" tag on the page.

The second example ".boxText" is a class style. We know its a class style because it begins with a "." (dot). Class styles can generally be applied to any tag within the page and the syntax looks like this"

<TD class="boxText">

This code tells the browser to display this particular TD with the styles found in ".boxText". Notice in the tag's "class=" part that there is no "." (dot) before the word "boxText".

The third example "TR.header" is a class style that is tied to a tag, in this case "TR" This means the style can only be used with "TR" tags, but it is still coded the same way as any class style:

<TR class="header">

Now when working with style sheets, that someone else has created, some times things can get a little confusing and frustrating, that can be especially true with osCommerce. When you find yourself wanting or needing to make a visual change, I've found a technique that works fairly well. That is to load the page in question into your browser and then do a view source. By doing so you are looking at the HTML code which has been rendered to your browser without the PHP code in the way. The view source will not always be formatted for easy reading, in fact it can still be somewhat difficult to read, so it takes a little patients to find what you are looking for. Lets use an example to more fully explain how the process works.

This is taken from the main default osCommerce page:

Lets assume that we want to change the text that says "What's New Here?", so that the text is black instead of that gray color. At this point we really don't know what it is that we need to change in the code. So with the page open in a browser, click on the "view" menu, and the "source". The HTML source code for the page opens up in Notepad. We could now scan the code looking for "What's new" but an easier way is to just do a search. Doing so we find this code:

<td class="pageHeading">What's New Here?</td>

We are concerned with the tags that surround the text, "What's New Here?", and there we see a TD tag which is using the class "pageHeading". So now we know that the formatting for the text is defined in a style class called "pageHeading". Now lets go back to the style sheet and see what we can find.

Doing a search on the file for the word "pageHeading" leads us to the following code:

TD.pageHeading, DIV.pageHeading {
font-family: Verdana, Arial, sans-serif;
font-size: 20px;
font-weight: bold;
color: #9a9a9a;
}

Something interesting about this particular style definition. We know from our previous discussion this is a class definition that is tied to a tag, but its a little different, it has two tags its tied to, TD and DIV. Any changes that we make here are going to effect all TD and DIV tags that have the pageHeading class. We could approach this two ways. One would be to separate this into two different definitions or we can leave them together. However its reasonable to assume that these tags were left together for a reason, so we'll go ahead and leave them that way.

The syntax for a style definition is: property:value; The properties themselves are fairly easy to understand. Here we are defining the font "Verdana", font size "20px", font weight "bold", and color "#9a9a9a". Color is the property we are interested in changing, so lets take a closer look there. In a style sheet colors can be defined two ways. The first is to use the English word, such are red, blue, black, etc. The second and more preferred way is to use the Hex value for the color. The Hex value is preferred because there are more options available. There is nothing that says you cannot mix the two, however the code is more uniform and follows a standard if you use one or the other.

In Hex color codes, #FFFFFF translates to white and #000000 translates to black. Every other color is something in between. I'm not going to get into how the Hex values work here, but there is plenty of information available on the web concerning the subject as well as color charts.

We want to change the color of the text to black, so we change that particular line of code to look like this:

color: #000000;

All that's left to do is safe the style sheet and upload it to your web server. Now if we go back and refresh the page we find that "What's New Here?" now appears in black, just that easy.

Obviously this was a fairly simple example, there are many others that would be more complex. However the principles all remain the same. The important thing is to take your time, and make small changes at a time. And as always be sure you make a backup of any files you are changing so you always have something to fall back on.

Happy coding.

Ok so you have osCommerce installed and you're starting to poke around the admin area, looking at all of the available features and controls, making some of your initial global configurations. And suddenly it hits you, "wait a minute, I didn't have to log in to get here?!".

That's right you didn't. While many if not most open source web applications will provide some sort of 'admin' account and the functionality to create an ID and password, fresh out of the box osCommerce does not. So you are probably asking yourself, "how can I leave my admin area wide open? That's a obvious security hole". You're not alone, that is one of the most frequently asked questions in the osCommerce support forums.

For whatever reason the core developers of osCommerce chose not to provide built in security for the admin area. It doesn't take a genius to figure out that some sort of security is required. Fortunately the solution is usually fairly simple to implement and reasonably secure, that is to use a .htaccess file. Now let me quickly note this applies to Linux/Unix Apache based systems. If you are using a Windows server, the security is configured through the folder properties etc. The majority of osCommerce implementations are on Linux hosts, so that's what I'm going to talk about here.

The .htaccess file is a plain text file that provides the ability to configure not only security but also things such as search friendly URL's. For those interested a more indepth discussion of .htaccess can be found here.

The .htaccess file uses a separate file which stores the password for an account in an encrypted format. There are some command line and other utilities for setting up folder protection using .htaccess, however for the most part you should generally not have to rely on those. Most web hosts will provide within the control panels some functionality to password protect folders. Behind the scenes this will set the .htaccess and the password files for you. If your host uses Cpanel, go to the applet titled "Password Protect Directories", drill down to the folder you wish to protect, add an account and password, and you are all set.

If you have trouble with this, your hosting package doesn't make password protecting directories readily available, contact them for help. I've seen far too often people having problems and posting questions that their web host would actually be the best equipped to help with. Your web hosting company should be your friend and should provide you with timely help. If they aren't, get another one I highly recommend Host Dime. I've used them for three years and they provide excellent service at a reasonable price.

Another important thing to know when you are password protecting a folder, you only have to set a password on the top level folder, i.e. catalog/admin. All the folders underneath are then protected, so you don't have to apply a password to each of the sub folders under admin.

In addition to going directly and setting up .htaccess on your web there are also some contributions available, Administration Access Level Accounts is one for example. I've never used any of those particular contributions myself, but if you want to go that route I suggest browsing the contributions area of the osCommerce site.

Happy Coding

Previously we talked about some files which are included in most pages of the osCommerce system, header.php, column_left.php, column_right.php, and footer.php. All four of these files deal directly with the visual appearance of osCommerce. There are some other files which are also included in each page with in the system. application_top.php and application_bottom.php are two of these files. application_top.php is basically the bootstrap include for each page. It contains calls to connect to the database, constant definitions, etc. And application_bottom.php serves as a clean up file for the page.

There is also another file included, the language file, and that's what I'm going to center this discussion on today. The architecture of osCommerce provides support provides for localization through the use of language files. Out of the box, the default installation of osCommerce provides support for three languages, English, German, and Spanish. It is through the use of these language files that the system is able to dynamically adjust to the chosen language of a visitor to your cart. For example if a user to your cart modifies their personal language setting to German the labels, buttons, and other text on the pages of your cart will appear in German. Same thing for a user choosing English or Spanish, through some available osCommerce contributions or simply by doing it yourself other languages can also be added by following the existing model.

If you look at the code for a visual page, somewhere near the top you'll find a line of code that looks similar to this:

require(DIR_WS_LANGUAGES . $language . '/' . FILENAME_CREATE_ACCOUNT);

Of course we can expect that DIR_WS_LANGUAGES is a defined constant for the 'languages' folder and that assumption would be correct, this folder can be found within the 'includes' folder. '$language' is a PHP variable, if you are new to PHP variables always begin with the '$' character, its value is the language chosen by visitor to your cart, i.e. English. FILENAME_CREATE_ACCOUNT is a defined constant, file name constants are defined in the filename.php file which is also found in the 'includes' folder. In this specific example FILENAME_CREATE_ACCOUNT is defined as create_account.php. So when your web server reads this file it sees:

require(languages/english/create_account.php);

So now lets go back and take a look at the languages folder. Inside we see three files english.php, german.php, and espanol.php. We also see three folders with similar names, English, German, and Espanol. What I am going to explain here applies equally to all three default languages, but for the sake of simplicity I'm going to refer to English.

The english.php file is a general purpose language file. Meaning that it contains language definitions which are applied across all pages. Let's take another look at some example code:

define('HEADER_TITLE_TOP', 'Top');

This is taken from the english.php file and defines the word 'Top' which appears at the far left of the breadcrumbs trail on the navigation bar. I specifically used this example because it appears on every page of an osCommerce cart and because it's frequently a piece of text that site owners want to change when they start customizing things. So lets say rather than 'Top' we wanted it to say 'Home', we would just simply modify the code to look like this:

define('HEADER_TITLE_TOP', 'Home');

Rather than 'Top' in the breadcrumbs trail, 'Home' would appear on every page of the cart. As developers we always want to be able to make changes in a single location and have the change appear everywhere it's used. english.php accomplishes this goal for words that are used in multiple pages within the cart.

Now an osCommerce shopping cart is made up with a few dozen visual pages, most with text and several labels. In theory we could include all of those definitions within the english.php file, after all it is available to every page in the cart. However if we were to do so the english.php file would grow rather large. Performance would be impacted not to mention it would become fairly difficult to manage. So to address that issue the architecture of osCommerce uses language files which are specific to the individual pages in the cart.

Lets take a look inside the 'languages/english' folder. Inside we find a list of files that basically mirror the file names from the root folder of the osCommerce cart. It makes it all fairly easy to follow because the language file has the same name as the visual file, it's just in a different location. Browsing the list of files we can find create_account.php from our example above. Inside this create_account.php file we will find the English translations of the labels and text that are specific to the 'Create Account' page.

So lets do a practical example. After you have done a default installation of osCommerce, you have this working shopping cart. But right in the middle of your home page is some text along the lines of 'Congratulations your installation of osCommerce was successful......" Obviously this is one of the first things we want to change for our new cart. Since the main page of our cart is index.php we are going to go looking for the language file at includes/language/english/index.php. Lucky for me and this example the file is there where I would expect to find it.

Before we open up the language file, lets take a look at the code for the main page, the index.php file which resides in the root folder. Inside this file there is a lot of code dealing with displaying new products, etc. But if we scroll down almost to the bottom of the page we find this section of code:

<td class="main"><?php echo tep_customer_greeting(); ?></td>
</tr>
<tr>
<td><?php echo tep_draw_separator('pixel_trans.gif', '100%', '10'); ?></td>
</tr>
<tr>
<td class="main"><?php echo TEXT_MAIN; ?></td>

Now the first line that says

'<?php echo tep_customer_greeting(); ?>'

That calls a function to display the customer greeting, 'Welcome Guest would you like to log yourself in?....' We're not going to cover that at this time, but I wanted to point that out to avoid confusion. What we are looking for here in the last line in the example:

<td class="main"><?php echo TEXT_MAIN; ?></td>

This is where the larger body of the main page text is coming from. Its saying to echo or print to the screen the value of the constant 'TEXT_MAIN'. Ok so now we know what to look for, we can go ahead and open up includes/language/english/index.php. The first define statement in the file looks something like this (It's rather long so I've shortened it for this example):

define('TEXT_MAIN', 'This is a default setup of the osCommerce project, products shown are for demonstrational purposes, <b>any products purchased will not be delivered nor will the customer be billed</b>. Any information seen on these products is to be treated as fictional.........');

You'll likely want to be more creative, but for the sake of example lets assume you want to change the text to read 'You have arrived at my new store'. You probably have the hang of it by now and you should as the change is simple:

define('TEXT_MAIN', 'You have arrived at my new store');

Save the file and upload and you're done, well almost. If your intentions are to keep your site multilingual, you also need to make the corresponding changes in the includes/languages/german/index.php and includes/languages/espanol/index.php files. with the proper translations for those languages.

Finally there is one other thing that falls outside the rule for language files and that is 'buttons'. If we go back to the 'includes/language/english' folder, we can see a sub folder there named 'images' inside the 'images' folder we can find a 'buttons' folder. The whole path goes like this, 'includes/languages/english/images/buttons'. This is where all of the button images are stored which are used for the osCommerce cart. Since the buttons display text, those too are displayed in the selected language. For example button_continue.gif in this folder is the button which displays 'Continue' in English. To make modifications here you'll need to open up Photoshop or another graphics editor, which is beyond the scope of this article but perhaps something we will tackle in the future.

Happy coding!