MIVA, Inc., a leading independent Performance Marketing Network, today announced that its Small Business Division has launched MIVA Merchant Fast Track specifically designed for smaller, web-based businesses to create and manage their entire online store design. With this announcement, MIVA Small Business expands its product portfolio to two distinct lines: MIVA Merchant 5 for small-to-medium size businesses, and now MIVA Merchant Fast Track for smaller and start-up businesses.

After a year of discussion and study, and in anticipation of the AgoraCart version 5.0.0 release, the manuals and documentation for AgoraCart, a ecommerce shopping solution, has been moved to a wiki format at AgoraCart.com . The new wiki format will allow users of AgoraCart to contribute to and improve, in meaningful ways, the much needed documentation.

Powered by MediaWiki, the existing manual pages and guides were converted to wiki format earlier this month. The new wiki format will allow users of AgoraCart to contribute to and improve, in meaningful ways, the much needed documentation for the Open Source software project.

The new location of the manual and guides is located at:
http://www.agoracart.com/agorawiki/

Experienced users of AgoraCart are encouraged to contribute to the manuals and/or make a request to become a moderator of the documentation to maintain it's integrity. Editors are standing by, so all skill levels of the written word are welcome if any person wanting to contribute needs assistance.

In the end, the new documentation format will be a giant step forward in making AgoraCart easier to use for those that are newer to online marketing.

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!