Jump to content
  • Checkout
  • Login
  • Get in touch

osCommerce

The e-commerce.

Quick customization guide


dirthawker

Recommended Posts

I wrote a 3-page document today describing the beginning customization details, getting started in the Admin portion, and a short description of where and what the files are. I have it in .rtf format and have pasted the text below. It looks bad here but much better in the .rtf. Give it a skim and if you find it helpful, tell me if there's a place I can put it where people can download it (contributions?) Also, if there's anything I missed, of course say so! I'm sure I've missed something!

cheers

-andrea-

 

A very short beginning guide to modifying osCommerce

 

These are the minimal changes to start customizing your site from the base installation. If you are using an editor that automatically wraps lines, either turn off the wrap, or get an editor that does. Ideally your editor should also number lines, especially if you intend to install any contributions, and believe me, you are very likely to do so. There are many fine editors out there that will do these things; I use AnyEdit.

Note on syntax: anything in braces {} should be entered without the braces.

 

You will need to edit or at least check the following files:

 

File Name What you'll be changing

admin/includes/configure.php, includes/configure.php

Ensure that all constants ? those things that say define('SOMETHING','Something else'); point to the correct names for your website, and that the DB_SERVER user name and password (near the bottom of the file) are correct

 

includes/header.php, and optionally admin/includes/header.php

If you have put your store logo in your images directory, reference it at that first TEP_IMAGE call, replacing oscommerce.gif. The 3 parameters in quotes following the logo name are a mouseover text, the image width, and height. Do correct the width and height to match the size or meet the proportions of your logo.

 

You may also want to change the background color behind your logo at the top of the screen. This is before the tep_image call but on the same line. Change the bgcolor = #{hex color number}.

 

includes/languages/english.php or appropriate language

define('PAGE_TITLE' - this is what will appear in the title bar of all screens, and on the last line: define('FOOTER_TEXT_BODY' you may want to include your own copyright information.

 

includes/languages/english/conditions.php

This contains your Terms of Use statement

 

includes/languages/english/privacy.php

This contains your website's Privacy Policy

 

includes/languages/english/shipping.php

This contains your Shipping and Returns policy

 

includes/languages/english/index.php

TEXT_MAIN defines the text on the first page your customers see. The default installation has a very long line starting with 'This is a default setup of the osCommerce... This line ends with '); and the next line begins with define('TABLE_HEADING_NEW_PRODUCTS. Remove everything starting from This is a default setup and ending before the '); and replace it with your own welcome text.

 

Includes/column_left.php and column_right.php

These define which boxes appear to the left and right of the main screen. Moving boxes from one file to the other will put the box on the other side. You may want to do this to balance out the left and right - play around with the shopping cart, the products, the reviews. Note which boxes are too big and, if you want them at all, how to fit them with other boxes so the screen looks good. To remove a box completely you can just comment it out by placing a // at the beginning of the line.

 

stylesheet.css

If you have a background image, copy it to the images directory, and reference it here at BODY { background #{hex_color number} url(images/{background_image_name})

 

Less crucial customizations:

includes/languages/english/create_account.php

Customize the text that gets emailed to your customers when they create an account.

 

Stylesheet.css

Change the font, font size, font colors, and colors of the horizontal bars.

 

includes/languages/english/create_account_success.php

Customize the text displayed when your customer creates an account

 

includes/languages/english/login.php

Customize the text displayed when your customer logs in

 

includes/languages/english/specials.php

Text for the screen showing products on sale

 

=================================================================

 

Basic store setup

Go into the Admin module and go to Configuration.

 

My Store comes up first. Here is where you would enter some basics about your store under Store Name, Store Owner, E-Mail Address, E-Mail From, Country, Zone, and Store Address and Phone.

Click on Customer Details. Here you will check what is or is not required information when a customer creates and account with your store.

Click Shipping/Packaging, enter your Postal Code. This will be used later if you hook up to UPS or USPS shipping.

Click Product Listing and check which qualities you want displayed in your product list.

 

Go to Modules in the left column. Payment comes up first. Here is where you choose your payment gateway(s) and other forms of payment you will accept.

Click Shipping. Here is where you define how much you charge for shipping and which carriers you will use.

Click Order Total. Here you define in what order totals are calculated.

 

Click Locations/Taxes in the left column and click Tax Zones. Here is where you tell osC where taxes should be applied. I don't know enough to make a long discussion of taxes in each country. However, if you are in the US, sell taxable items, and want to tax only customers in your state:

Add a tax zone called USA/{your state}

Double-click it.

Add here your country and state.

Now click Tax classes and add an entry which indicates you have Taxable items.

Now click Tax Rates. Select "Taxable" in Tax Class Title, select USA/{your state} for the zone, enter the tax rate you are charging e.g. 7.25 for 7.25%, and give it all a description.

 

Click Catalog in the left column. If you want your customers to be able to search for items by manufacturer, click Manufacturers first and add them.

Then click on Categories / Products. Here is where you organize all your different products and enter them. However ? I don't recommend entering them all until you have installed any osC contributions you might want to add. There are a bunch of products included with the base installation so you can play around with the system. Out of the box, osC, though feature-rich, is somewhat minimal on the customer end. Look for things customers might expect to see or abilities you think your customers would like to have, then search the osC forum and contributions website if you find something lacking. Some contributions will involve adding columns to the database, and if you have a long product listing, it may mean editing each product *yet again.*

 

Finally, click on Tools in the left column and the Database Backup will appear. Be sure to BACK UP your database REGULARLY!!! It's far more important than all-caps can imply! Also in Tools is something called Server Info. This lists your version numbers of osC, MySQL, and PHP, which may affect your choice of which contribution to install.

 

NOTE: the database backup only backs up your database. It does not back up any of your PHP files. Always back up your PHP files before you install any contributions or make modifications to the code.

 

=================================================================

 

osC's general structure for the beginning customization programmer:

The sheer morass of files with identical names can be overwhelming at first, and trying to figure out which files do what is challenging. After tweaking around with osC for several weeks I have some conclusions about the general structure:

 

Everything in /catalog are PHP files that your customers may execute at some point. They will not directly see the name of any other file in the URL box. The only other file here is stylesheet.css. Changes to files here are often layout changes: resizing table cells and text-entry boxes, moving things up and down. Most of these files have a chunk of PHP code at the top and html at the bottom.

 

Everything in /catalog/images are, predictably, image files: All the little icons, arrows, and your product images are here, but there are no language-specific buttons. In /catalog/images/infobox are the chips for the rounded corners you see on the boxes. If you change the color of the horizontal bars or the background color in stylesheet.css, you will want to edit the color of these chips to match

 

/catalog/includes: these are mostly, for lack of a better word, layout files for what your users see: where catalog/index.php defines the center of the screen, the files here define the top, left, right and bottom of the screen. Also in here are basic definitions about your fileserver and the names of your database tables.

 

/catalog/includes/boxes: these define the little boxes that go inside the left and right of your screen, such as the category list, the search box, the product review box, etc.

 

/catalog/includes/classes: these files, for the most part, define the structure of objects that get created during the course of the customer browsing your site and purchasing items. It is most often here that the most significant changes to the functionality of osC gets changed. These are the files that do the read and writes to your database. Most of these files are purely PHP code.

 

/catalog/includes/functions: these is osc's custom function library. Here they redefine many SQL and HTML functions, and build shopping-cart-specific functions.

 

/catalog/includes/languages: files here define text of the more global constants in the appropriate language.

 

/catalog/includes/languages/{language name]: files here define the text of constants used in specific screens in the /catalog directory.

 

/catalog/includes/languages/{language name]/images/buttons: these are buttons that have language-specific words in them.

 

/catalog/admin has a corresponding structure to /catalog, however, these files define the functioning of the administration portion of the application, rather than the shopping cart.

Link to comment
Share on other sites

Good job Andrea. :) I've thought about doing something similar myself. I think adding it as a contribution would be the best way to go. I thought to put it in an html document and make a basic manual of it, with clickable links. Then, anyone wanting to add their help ideas can update the contribution. The problem is that you, or someone,would need to monitor any changes made to be sure the information added is valid. I think this was the basic idea behind the wiki documents but they are not updated enough, especially for new users.

 

You might want to consider providing a pre-cursor to the above explaining how the shop is layed out. Many new users have no idea what you mean when you say includes/languages....

 

A section on using the forum might also be hepful. Be sure to put in a reminder that a search tool exists.

 

Jack

Support Links:

For Hire: Contact me for anything you need help with for your shop: upgrading, hosting, repairs, code written, etc.

Get the latest versions of my addons

Recommended SEO Addons

Link to comment
Share on other sites

The addition of a pointer to the forum is a great idea, Delicata and Jack. I haven't made the change, just posted it as is to contributions under "Other"

 

http://www.oscommerce.com/community/contributions,2565

 

Let's deal with it like any other contribution. Open to all adds changes improves.

 

I assumed that if a person chooses osCommerce I would expect that they already know files must be edited, or they're going to figure it out REAL fast... I know it may sound elitist, but if they don't understand that the application is composed of files and subdirectories containing files, and can't deal with that, they have no business dealing with an open source project like osC.... Maybe I shouldn't make that assumption...

 

Adding a few lines of explanation to say that the files are stored in different directories like categories/includes etc., would be easy and won't make it that much longer and intimidating. I'll mess with it a bit and upload version 0.2 B)

-andrea-

Link to comment
Share on other sites

Nicely done.

 

I'd suggest adding a brief portion about the screwy decimal and rounding issues too - I've been searching for what are probably newbie answers about decimal places and rounding, but finding dozens of threads with only half-replies or threads with suggestions where the poster never came back to let us know if the solution worked.

 

Great doc though. I've printed it out.

Link to comment
Share on other sites

Nicely done.

 

Thanks! (I'll feel good all day!)

 

I'd suggest adding a brief portion about the screwy decimal and rounding issues too - I've been searching for what are probably newbie answers about decimal places and rounding

 

And I've been one of them. :'(

I want all the pieces of this document to be brief. Attention spans are short these days :D , and I don't want to get too deep into anything, but rather just get people started.

 

I want to add a section describing which mods are must-haves for a normal retail store (not resellers nor services sellers.) I've included the Header Tags and the Margin Report contributions, and will probably add the one about uploading your products.

 

The Margin Report brings me back to your point about rounding -- I will make a comment about my own problem with this report and likely add a bit about the general necessity of rounding to 2 dec places.

 

What was your issue with rounding? And do you have other must-haves?

-andrea-

Link to comment
Share on other sites

What was your issue with rounding?  And do you have other must-haves? 

-andrea-

 

If all these could be answered for once and for all in one area, that would be tremendously helpful:

 

What numbers within the cart and admin areas does OSC round?

Why does it do this?

What issues can this cause when calculating totals or taxes or exchange rates orwhatever?

How to fix rounding if it's causing significant discrepancies?

 

Decimal Places:

What does the "Tax Decimal Places" setting DO exactly?

Does it make sure that 7% for example is calculated as .07 or does it do something else?

If I set my currency's decimal places to 2, do I need to do the same with taxes? What happens if the currency decimal is set to 2 but the tax decimal is set to zero?

 

If I'm editing a product via Admin and suddenly the price I've entered changes from say $24.00 to $24.0000 is this just cosmetic within Admin or could it affect something else in the store?

 

If I've set my currency up to have two decimal places, how can the number suddenly become $24.0000? Can I fix this somewhere?

 

If it says $24.0000 in admin, but the storefront appears fine, should I just ignore it?

 

I think those are all the things that have been giving me personally fits for a few days. It's just the necessity of searching ALLLLLL the forums for individual answers that's annoying.

Link to comment
Share on other sites

Ooh, many questions. I'll answer best I can inline:

 

> What numbers within the cart and admin areas does OSC round?

 

Surprisingly, nearly none of them! I did a search on round( and find that there is a function defined, called tep_round, which accepts a number of decimal places as a parameter. It is called only in includes/classes/currencies.php. All other php files that call for a rounding function use the PHP round. THese files are: includes/classes/currencies.php, admin/categories.php, and admin/stats_monthly_sales.php. There may be some other function involved with the display of the number, but the number itself is stored with 4 decimal points.

 

Presumably these are limited to the number of decimal points you've set in admin. I didn't look at each and every file.

 

> Why does it do this?

 

Ask Harald???? Actually, a lot of products, especially in the wholesale arena, use 4 decimal places. When you're buying 10,000 whatevers, these fractions in the ppu make a difference.

 

> What issues can this cause when calculating totals or taxes or exchange rates orwhatever?

 

When you add .404 to .204, you get .608 which will round up to .61

When you add .40 to .20 (rounding to 2 digits initially) you get .60

 

So it can screw you up in terms of lots of pennies. I don't think it's something that will cause the Canadian version of the IRS to go after you, but it's a headache for trying to keep your books straight in the same way normal businesses do as a matter of course.

 

> How to fix rounding if it's causing significant discrepancies?

 

This is gonna sound really violent, but if you know you will never have a tax rate of greater than 2 decimal places, you can go into PHPmyadmin and cut the number of decimal places to 2. I'm not sure if doing so will cause you more code headaches, but it would be a quick-and-dirty way to fix it. So I'm not sure I'm recommending it, but speaking as a programmer, that would definitely do it.

 

Decimal Places: and other questions I cannot answer.

 

> If it says $24.0000 in admin, but the storefront appears fine, should I just ignore it?

 

Yeah

 

> days. It's just the necessity of searching ALLLLLL the forums for individual answers > that's annoying.

 

I find the lack of response on most threads annoying. I don't like to cross post and it's extremely bad manners to do so, but smetimes it seems the only way to get a response.

-andrea-

Link to comment
Share on other sites

I find the lack of response on most threads annoying.  I don't like to cross post and it's extremely bad manners to do so, but smetimes it seems the only way to get a response.

-andrea-

 

Thanks very much for your responses. I suspect that if we could make topics like this "sticky", then the number of repeated questions would be cut down and it would be easier to answer the specialized ones.

Link to comment
Share on other sites

Ooh, many questions.  I'll answer best I can inline:

 

> What numbers within the cart and admin areas does OSC round?

 

Surprisingly, nearly none of them!  I did a search on round( and find that there is a function defined, called tep_round, which accepts a number of decimal places as a parameter.  It is called only in includes/classes/currencies.php.  All other php files that call for a rounding function use the PHP round.  THese files are: includes/classes/currencies.php, admin/categories.php, and admin/stats_monthly_sales.php.  There may be some other function involved with the display of the number, but the number itself is stored with 4 decimal points.

 

Presumably these are limited to the number of decimal points you've set in admin.  I didn't look at each and every file.

 

Hi:

 

admin/includes/functions/general.php:

 

// Add tax to a products price
 function tep_add_tax($price, $tax) {
   global $currencies;

   if (DISPLAY_PRICE_WITH_TAX == 'true') {
     return tep_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']) + tep_calculate_tax($price, $tax);
   } else {
     return tep_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']);
   }
 }

// Calculates Tax rounding the result
 function tep_calculate_tax($price, $tax) {
   global $currencies;

   return tep_round($price * $tax / 100, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']);
 }

 

Also called in includes/functions/general.php.

 

I still wonder why osCommerce takes currencies to the eighth decimal, when it seems oanda only goes to four... But I can't confirm that other than this statement on their site:

 

"How accurate is the 164 Currency Converter?

 

The results you get by converting any amount of a currency to another is rounded to four decimal digits or four digits after the leading zeros with a few exceptions."

"Buy the ticket, take the ride..." -HST

Link to comment
Share on other sites

Thanks to Andrea for writing that document. I am VERY new to oscommerce as well as php, yet I am eager and open to information. Finding something along the lines of a "getting started" in one area where I can use as a reference is so perfect.

 

Also thanks to those who had additional questions and added more input. Very useful!

 

-Kidd- :D

Link to comment
Share on other sites

I think what would help more with this type of thing is for a new forum to be added and placed at the top of the list of forums. Title it something like Getting Started or Read First and pin this article to the top of it. Whenever I join a new forum I always visit such a section if it is available. Having a list of answers so readily available would have to help someone just starting out. Any team members around that can answer whether or not this is possible?

 

Jack

Support Links:

For Hire: Contact me for anything you need help with for your shop: upgrading, hosting, repairs, code written, etc.

Get the latest versions of my addons

Recommended SEO Addons

Link to comment
Share on other sites

 

Hi Dirthawker

jsut got one thing to say here folks

HOOOOOOOOOOOOOOOOOOOOOOOOOOOOoooooooooooowl

awesome post Dirthawker.

I was starting to think i was in over my head (witch probally am)

but i can see a twinkle of light at the end of the tunnel.

 

I can go to bed now, well soon anyway.

Thanks

It's all about the Double U's

Link to comment
Share on other sites

  • 2 weeks later...
WOW.

 

I only wish I found this 2 days ago when I started, but there was still stuff in there that was very helpful now!

 

This should really be made more easily accessible to the noobs here!

 

Christina

 

Thanks for the WOW :thumbsup: Someone suggested "pinning" it, whatever that means. I think as long as people read it and occasionally bump it by posting, that will help.

Link to comment
Share on other sites

"Pinning it" means make it appear at the top of the forum so it is the first message you see when entering that forum. Of course, without a "Start Here" forum, that would mean it would have to be pinned to everyone to make it work. Bumping it works somewhat but seems to increase the unneccessary messages that it was partially aimed at preventing (my assumption on this part, obviously).

 

Jack

Support Links:

For Hire: Contact me for anything you need help with for your shop: upgrading, hosting, repairs, code written, etc.

Get the latest versions of my addons

Recommended SEO Addons

Link to comment
Share on other sites

:D I just wanted to say THANK YOU for posting all of this info.

 

I installed OSC a couple of days ago and, being a total novice with PHP script, this tutorial you've provided has been PRICELESS.

 

Everything from wiping out the default home-page text and creating my own to the insertion of my own logo....I swear....THANK YOU!

 

I've posted several times on this board...all asking for help...and I'm amazed at the sheer lack of common sense, THIS-IS-WHAT-YOU-DO answers. Most of what I get is.....look for this, search for that.

 

Well....I've BEEN searching, trust me. I wouldn't post a message without driving myself nuts combing these boards first.

 

THANK YOU AGAIN!

Link to comment
Share on other sites

Me, again. LOL.

 

I just installed this software only a few days ago and I keep coming back to your post for help.

 

I really hope someone at OS Commerce 'bookmarks' this tutorial in some way, as I fear it will get lost in the other posts eventually, and I'll have to resort to driving the other posters insane with the same questions, over and over and over.

 

Not to mention, me having to sit tight and pray for a response that I can understand. No PHP expert in this house.

 

I'm using it again tonight....Lord only knows how many times I've referenced it just today alone....so, Thanks again for providing it. :D

Link to comment
Share on other sites

  • 2 months later...

THANK YOU THANK YOU THANK YOU!!!

With all due respect to OSC, these forums are almost less than usable. I've been here for two months before I found this, and it is exactly what I needed two months ago! In fact I had to find this by looking at another thread that pointed here!

 

In any case..

Anyone who has written, or knows of a "sequel", so to speak, please also post it here.

 

I love this document, and would love to see someone write an intermediate customization document. For example, how to write simple php that works with the main oSc elements, or how to start creating a "theme" or template for your site. Just more detail in customizing techniques for people who have a running site, but want to make it their own.

 

Any takers??? I have seen some super-cool oSc sites out there, and would love one of those designers to pass some knowledge on, in exactly the same way Andrea did, in an easy to read, simple document with examples.

 

or does it exist already????

 

Happy Coding!

:-j.

Link to comment
Share on other sites

THANK YOU THANK YOU THANK YOU!!!

With all due respect to OSC, these forums are almost less than usable. I've been here for two months before I found this, and it is exactly what I needed two months ago! In fact I had to find this by looking at another thread that pointed here!

 

In any case..

Anyone who has written, or knows of a "sequel", so to speak, please also post it here.

 

I love this document, and would love to see someone write an intermediate customization document. For example, how to write simple php that works with the main oSc elements, or how to start creating a "theme" or template for your site. Just more detail in customizing techniques for people who have a running site, but want to make it their own.

 

Any takers??? I have seen some super-cool oSc sites out there, and would love one of those designers to pass some knowledge on, in exactly the same way Andrea did, in an easy to read, simple document with examples.

 

or does it exist already????

 

Happy Coding!

:-j.

 

 

You're welcome, Justin, I'm a sucker for gratitude. I agree the search facilities on this board are, well, less than ideal. It took me a while to discover this link, but have a look at:

http://www.oscdox.com/phpWiki.html

It has a lot of the customization stuff that I wrote about in the original document and much more. I believe this is what people are talking about when the mention the Wiki.

As for template customization you're best off either downloading a template modification or (as I learned later, also, to my consternation) download a

loaded" version of OsCommerce called CRELoaded - http://creloaded.com. It is the base OSC package with many additional contributions included, and does have a selection of interesting templates.

-andrea-

Link to comment
Share on other sites

  • 7 months later...

This is great! Very helpful.

I asked in the forms just yesterday if there was an explanation of where all the certain files are for editing purposes.

Even did a search in the forums and came up with nothing like this.

This is perfect.

Thanks

I'm a victim of circumstance

Link to comment
Share on other sites

  • 4 weeks later...

Archived

This topic is now archived and is closed to further replies.

×
×
  • Create New...