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!