Getting Started with osCommerce

Looking to build an online store for yourself or for a client? Debating among various open source solutions? Thinking about cobbling together a customized solution with a database and an open source shopping cart? Don’t bother; look no further than osCommerce. osCommerce is an open source catalog and shopping cart system that comes loaded straight out of the box with a wide range of features. It is head and shoulders above the crowd in terms of functionality and options and is often lauded as not simply an excellent open source product, but an excellent e-commerce product by any standard. The system embodies a great deal of flexibility, but like any complex application, it also has its share of limitations and peculiarities. In the course of this article we’ll step through not only what it takes to get up and running with osCommerce but we’ll also take a peek under the hood for those who want to do more with this product. First Steps Getting started with osCommerce is a pretty straight forward matter. With little technical expertise you can get a site online in about 30 minutes. However, if you wish to customize or modify the default package extensively you will need (or need to know) someone with PHP skills. Be advised that osCommerce it is not the simplest system to customize, but the good news is that it can be done — and for a fraction of the cost of a proprietary solution. Before you begin you will need to address two preliminary matters. The first step is to create a mySQL database on the web host. For most people this will involve accessing phpMyAdmin to create and name a new database. Take note of the database name, and your username and password, as you will need them later in the installation process. The second step is to obtain the archive containing the osCommerce files, extract them and then move them to your server. To get the files, make a quick trip to SourceForge or to the osCommerce parent site where you can download the archive. (It’s free of charge.) The archive comes as a .Tar file and weighs in at a mere 871k. .tar files can be extracted by using WinZip or a similar file compression utility. Once extracted you will find the default structure of osCommerce looks like this: /oscommerce-2.2ms2 /catalog /extras Set up the directory structure you desire on your server and then move the entire set of files up to your server via FTP. If you have shell access at your server you can save some time by moving the archive file to the server and extracting the files on the server. While the end result is the same with either method, extracting the files on the server saves a bit of fussing about with FTP transfers and the chance that you may miss something if problems occur during the transfer. The simplest and probably most common configuration of the directory structure places the files inside the /oscommerce-2.2ms2 directory at your web host root. The extras directory is not necessary for your installation. The admin directory, located inside of the catalog directory contains the admin access to the catalog. Once you have the files on your server, direct your browser to http://yourroot/catalog. If the extraction was successful you will be greeted by the welcome screen of the installation utility. Click Install a New Online Store and you are off… The next screen to appear prompts you for the database information you wrote down earlier — the name of the database, your username, and your password. You’ll also need your host name or IP address. (In the vast majority of cases the correct answer to this question is localhost, though you should check with your web host if in doubt.) If all is correct, the system will confirm that the initial installation was successful and warn you prior to performing the installation of the SQL data. Once that is completed you are almost home. The next screen that appears shows you some important system data you should take note of, including the full URL of the catalog you have just installed, the web server root directory, the HTTP cookie domain, and the path where cookies are stored. You should not attempt to change any of this data unless you have a very good reason and you really know your way around a server. Note that this page also contains one other item of importance — a check box that allows you to enable SSL. I encourage you to select this option as it adds a modicum of security to your site. Be aware that support for this feature depends on whether your web host provides SSL as an option for your account. Once you’ve noted down the information for future reference and made a decision concerning the use of SSL, click Continue. The next screen repeats your database info for your reference (but you already wrote that down earlier, didn’t you?). Click Continue and move on. At this stage you may be prompted with a warning that the permissions for certain files are not set as osCommerce requires. Should that be the case you will need to use your FTP program to CHMOD the directories to their required state. Once the changes have been made click the Retry button. If all is in order, you will be shown a confirmation message that setup is complete (If not, check the information again and CHMOD the necessary files.) The osCommerce installation routine is a breeze to use and generally not problematic. There is one task that it omits to do, however, and to remedy that you will need to fire up your FTP program. Access the site via FTP and create a directory named backups inside of /catalog/admin. This directory is missing from the set up procedure and is needed for you to make backups of your database by way of the backup function in the admin system. Note that you will also need to set permissions on this directory to 777 for the osCommerce backup function to work properly. Hopefully the next release will fix this oversight in the Installer routine. That’s all there is to it. Check your new catalog and the admin section to verify that all is working properly.

Securing Your Site

Once you are happy that the site installation is correct, you will need to take a couple of simple steps to secure your installation from unwanted visitors. First, use your FTP program to re-name or delete the /installation directory; this is absolutely necessary to avoid someone from re-running the installation routine and thereby overwriting your site files or gaining access. Second, you will need to limit permissions on key directories. During construction and customization of the site I find it easiest to leave directory and file permissions set to 777, but don’t forget to use CHMOD to lock these files down prior to launch, as follows: /Directory/file Permission Level /admin/includes chmod 755 /catalog/includes chmod 755 /catalog/images chmod 777 /admin/includes/configure.php chmod 644 /catalog/includes/configure.php chmod 644 Third, to be on the safe side, I normally insert a blank index.html file in all directories that I don’t want browsed. The index.html file results in anyone who tries to access that directory being fed a dead-end (blank) file, rather than a listing of the directory contents. It’s a very simple way to keep prying eyes out of your directory structures. Finally, the default installation of osCommerce does not include password protection for the admin section. This is a major security hole that you will need to patch yourself.. Again, fingers crossed that this gets fixed in the next release, but until then you must take steps to address this problem. The most common solutions involve either using your web host control panel to password protect the admin directory, or modifying your .htaccess file to add password protection. There are also third party solutions that address this issue. It doesn’t really matter which option you choose, but you do need to put one of them into effect, else any slightly resourceful individual can gain access your admin control panel – and that is not a good thing.

A First Look at the Interface

When you first visit the front end of your virginal site you’ll find that a number of the site features have been activated and illustrated with sample products. You’ll also see some explanatory notes occupying the central position on the catalog home page. Take a minute to read through this as it contains useful information. You’ll note that one of the references goes to explaining the text at the top of your page with the pink background — this is the area where major warning messages appear from the system. Odds are the first time you look at your site you’ll see a warning at the top of the page: Warning: I am able to write to the configuration file: [your path]/includes/configure.php. This is a potential security risk – please set the right user permissions on this file. As noted above, you’ll probably want to hold off on fixing this issue until you finalize things and are ready to go live. Until then, you’ll have to live with this little reminder on all your pages. At first glance the initial screen may seem a bit of mess – lots of information, modules, products, etc. Don’t be daunted by it. The information can be hidden, the modules customized, the products deleted and replaced with your own categories and information. What you see initially is simply the developers’ attempt to give you some idea of what you can do with the system; in no way does it limit what you may choose to do as you go through the configuration and customization process.

Off the Rack

Before we get into what you can’t do, or what you might want to change or add to make the system do more, let’s take a look at what it will do straight out of the box, so to speak. For the Site Visitors A number of useful features are enabled by default. Site visitors are provided with a search function, the ability to sort by manufacturer, the ability to read product reviews or post some of their own. Useful product marketing features include a “what’s new?” function and “specials.” Users can also subscribe to product notifications by email and are provided with an option to email product information to their friends. The system can support a great deal of information about each product, including manufacturer, weight, net and gross prices, options (which can be tied to the pricing as a variable), thumbnail and large images, as well as generous space to input whatever text is needed to explain the product. At this stage it is probably a good idea to spend a little time clicking through your new installation to explore the default examples. Note that the default layout isn’t all that sexy, but fear not, we’ll look later at how that can be improved upon. The osCommerce shopping cart is a solid piece of work. It is easy to use, reliable, and supports temporary carts, that is, visitors to the site can add products to a shopping cart without having to be registered users. If later a visitor decides to proceed to checkout and execute the order, then the system prompts them for login (or registration). By default the system is set to calculate shipping at a flat rate and to accept payment via credit card or cash on delivery. These options, and most others mentioned above, can be changed easily via the admin console. Most common payment gateways and shipping methods are supported in the default installation and many others can be added to the system by installing various third party solutions. Registered users benefit from a variety of features including the ability to store multiple shipping addresses and maintain order histories.

For Managers

osCommerce includes a variety of useful management tools for administering the catalog and handling orders. This is one of the areas where this tool excels and one of the best reasons for choosing the system. Product listings carry all the information necessary for site visitors and for order processing, including product names, descriptions, weight, images, and model numbers. You can include pricing at both net and gross rates and select tax classes. Note in the example product show in the screen shot, I’ve included html tags inside the description text field. With just a little basic html formatting of the text field, you can achieve a much enhanced layout for your individual product details. One of the more advanced features supported by osCommerce is inventory tracking. The system allows you to input the number of units in stock, then as orders are placed the available total is automatically updated. You can set automatic re-stocking reminders that are triggered when user-defined inventory levels are reached. If you don’t need this feature, simply leave the number of units field blank. Orders run through the system can be tracked by the catalog managers via the admin interface. The system generates basic invoices and shipping slips and as orders progress through your system, you can log the orders’ status and send email updates to clients. Note the Order Admin screen (pictured in the screen shot) is set up as a work space for a catalog manager. Here you can update the order’s status, even add a note to the user to be sent out via email. Your customers are also able to log into the front end of the system to view the status of their orders. osCommerce also produces a variety of basic order history reports, allowing managers to identify the most valuable customers and the most popular products.

For System Administrators

System tools are somewhat limited. You can perform database backups and restore and you can control the caching, but that is about it. One the biggest complaints with osCommerce is the lack of content management tools for the non-catalog pages. Changing the copy on the content pages is arcane exercise involving visiting the Define Languages section under the Tools tab. Once there you find a list of file names. You then click on the name of the file you desire to change and edit the PHP code within the window. This approach is fraught with opportunities for non-technical staff to crater pages. So, whether you are a customer, a catalog manager, or a webmaster, osCommerce has virtually every feature one needs to produce and manage a professional ecommerce presence. Now, while all that is well and good, users who want something dramatically less, dramatically more, or simply something different may find the system frustrating. This is where we start to separate the dudes from the duds, the hackers from the slackers?

Controlling Front End Appearance

osCommerce comes with only one template. The default installation, while it does include all the features one needs to get going quickly, is frankly neither very attractive nor very flexible. It would appear the osCommerce team was more comfortable with the functionality aspects of the project than with the design aspects. When I speak of design I am referring to both the look and feel and the usability. Part of the problem is that the interface was designed years ago and is not aging very well — it just looks old school. The dated approach shows in the way the pages are built — layer upon layer of nested tables. The system is absolutely clogged up with tables. CSS is not implemented effectively and even basic pages have hundreds of lines of code. Hence, customizing the front end’s appearance makes for some long hours in front of a screen. But let’s step back a moment. Say, you’re not totally unhappy with the default installation. Say, instead of a complete facelift you only want to change the colors and upgrade the appearance with some improved graphics. If your ambitions are limited, you can do this easily by one of the oldest and simplest tricks in the book: overwrite the existing files with ones of your own. osCommerce images are stored in two primary locations. The images directory holds a number of the generic icons and product-related images. Note also that the subdirectory infobox contains the rounded corners you see on the boxes in the left and right column on the front end of the default site. You can overwrite these with your own versions easily. Replace the osCommerce logo with your company’s logo to re-brand the site. If you want to go further and re-do the graphical buttons on the site you have to look a bit harder. Buttons with text in them are kept in includes/languages/english/images/buttons. To access the buttons in the other two default languages, simply change the word english in the path to the desired language name. Again, overwriting these with buttons of your choice is an easy task and a fast and simple way to skin the site, assuming you like the default layout.

Digging Deeper

But now let’s reach further – say you don’t like the default layout. You want two columns, not three, or you want to move a box from one side of the page to the other (or elsewhere). The next level of hacking the presentation of osCommerce requires you to dig into the underlying .php files. You had best be comfortable with working at the code level as WYSIWYG editor functions are of little help with osCommerce. So, fire up your fave editor and let’s look at 4 key files. First, as a basic principle, osCommerce relies heavily on server side includes as a way of emphasizing reuse of blocks of code. As a result, knowing where to look for the key includes sets you on the right track. The header and footer are the easiest to deal with, being named respectively, header.php and footer.php and being located logically in the includes directory. Hacking either of those files is a pretty simple matter and does give you quite a bit of room to maneuver. The left and right columns are a bit more difficult. First, the columns themselves are the files column_left.php and column_right.php, which can be found in the includes directory. So far so good. However, it turns out that the contents of the columns are almost entirely located inside of units osCommerce calls ‘boxes’ and those are different files altogether. If you wish to remove a box from one of the columns, you can access the appropriate column file, find the line that refers to the box in issue, then comment out the ‘include’ line, or remove it totally. You can also move boxes from one column to another by cutting and pasting. If, on the other hand, you wish is to customize the appearance of any box, then you must visit the file that creates that particular box and modify it. All those files can be found in includes/boxes.

Into the Woods

Now if all this so far has seemed pretty non-threatening, well, you are right. You want to change the colors and the graphics – no problem. You want to move around or delete some boxes and have a custom header and footer – really no problem there either. But now let’s say you don’t like the way the page layouts themselves are done. Step into my parlor said the spider to the fly? This is where osCommerce becomes real fun and developers earn their money (as they guzzle liters of caffeine and rip out their hair). Turns out the default osCommerce file structure means that, despite numerous includes and database calls, the system basically uses different files for every single page and that making changes means going through every single page and making the changes over and over again (all the while testing and double checking to make sure you don’t introduce your own crafty little errors). The good news is that at least you can use all the comment tags to help you. No, wait a sec, that’s the bad news. osCommerce comment tags are essentially limited to “header”, “footer”, “main body”, “left nav” and “right nav”. Hate to be negative, but thanks for nothing guys! You give us hundred of lines of nested tables and you can’t be bothered to add a few meaningful context-sensitive comment tags?? OK, that said, we live with what we get, so while you are in there hacking away you might want to go ahead and clean up that horrible nest of unnecessary tables and spacer gifs. You can knock out 20% of the page weight pretty consistently by simply killing off redundancy and shifting to a more aggressive CSS approach to positioning items. Why not go all the way and dump these pages in favor of a pure, or at least mostly, CSS approach? This is one area where you should beware the sirens’ call. While it may initially seem tempting to just toss the whole structure, I urge you to think carefully and take the word of one who has gone down that path before: osCommerce is a complex system and you will likely find that the slash and burn approach winds up having unforeseen negative effects. So, while you may be tempted, I urge you to resist. Look for other less destructive approaches to achieving your goals. That brings us to our next topic…

Extending Functionality Through Contributions

The large and resourceful osCommerce community has responded to the lack of certain features by providing their own solutions. osCommerce calls the third party solutions “Contributions” and they are invaluable resources that allow you to extend and customize the feature set without having to re-invent the wheel (oh the joys of Open Source!). Implementing a Contribution typically involves downloading the archive, unpacking it, then overwriting some of the default osCommerce files with new ones from the Contribution. More advanced Contributions require you to execute SQL queries to modify your database. (Do I need to say this? Back up your site and archive the original files before you install any Contribution. It isn’t simply a precaution against a Contribution being buggy, but rather more often you find the Contribution either doesn’t perform like you want it to or that it isn’t quite what you had hoped for and you wish to uninstall it.) One of the most powerful and popular Contributions is called STS – Simple Template System. It allows you to build HTML page designs and then drop placeholders that call different osCommerce functions into your design. STS really opens up the front end of osCommerce and makes it possible to do heavily customized interfaces without delving deeply into the PHP pages of the default site. Another personal favorite of mine is called Easy Populate. I love it because it lets me move large catalogs of products in and out of the system in a few clicks, thereby bypassing tedious key punching. Use this Contribution, save somebody’s life. There are also legion of Contributions to enable support of a wide variety of languages, pricing and discount structures, shipping and payment methods and additional catalog features. To get some idea of what is out there, go to the osCommerce site and explore: http://www.oscommerce.com/community/contributions The page lists more than 2000 Contributions, ranging from mundane to marvelous.

A Word of Caution

Contributions are a godsend and will make your life much easier but never forget that they were not developed by the core osCommerce Team and as a result they often employ non-standard solutions to the problems at hand. As a result, while any particular Contribution may work with the core, it may not work with another Contribution. Your best bet to avoid problems is to plan very well and to use a dev server. Figure out exactly what features you will need, match Contributions to your wish list, then set it all up on a dev server and test it heavily before you deploy. Trust me on this: Retrofitting Contributions to an existing site is simply asking for punishment. Get it right before you let it loose in the wild (or make sure you have a support and maintenance contract in place!). So there you have it – an osCommerce jump start. Don’t be put off by my whingeing about the difficulty of hacking the tool; osCommerce is powerful and reliable and gets the job done. Now, at the end of the day which would you prefer: An easy to modify but unreliable system, or one that you may have to tussle with a bit, but always gets the job done? I’ll take the latter. (Besides, if it was too easy, clients wouldn’t need us!) Originally published in Linux Magazine, July 2005.

Leave a Reply

Your email address will not be published. Required fields are marked *