osCommerce Documentation

Template Installation

Technical Requirements

osCommerce Online Merchant can be installed on any PHP enabled web server that can connect to a MySQL database. This includes shared servers, dedicated servers, and local installations running on Linux, Unix, BSD, Mac OS X, and Microsoft Windows operating systems.

Web Server

The web server must support PHP either as a module or allow execution of CGI scripts. For performance reasons FastCGI is recommended over CGI.

PHP

The following PHP options are recommended to be set in the php.ini configuration file:

When you've completed the preparations steps you can proceed to the osCommerce installation.

register_globals Off
magic_quotes_gpc Off
file_uploads On
session.auto_start Off
session.use_trans_sid Off

The following PHP extensions are mandatory:

MySQL Off

The following PHP extensions are recommended:

GD Image processing module.
cURL Network communication library.
OpenSSL Encryption library.
MySQL Database Server

The minimum MySQL version required is v3.23. It is recommended to use the latest MySQL 4 or MySQL 5 version on the database server. The following MySQL storage engines are supported:

MyISAM Default storage engine.

Pre-Installation Steps

osCommerce Online Merchant is a web based solution that needs its relevant files to exist on the web server. The files can be copied to the web server by extracting the download package on your computer and uploading its contents to the web server via FTP, or by copying the download package to the web server directly and extracting its contents there.

Copying the Files to the Web Server

The contents of the download package need to be copied to the public HTML directory the web server is serving from.

  • /home/shinyredapples/public_html/
  • /srv/www/htdocs/
  • /usr/local/htdocs/
  • /var/www/vhosts/yourwebsite.com/httpdocs/

The contents of the download package once extracted is:

  • catalog (directory)
  • CHANGELOG
  • community_docs.pdf
  • documentation.pdf
  • extras (directory)
  • LICENSE
  • STANDARD
  • upgrade.html

Using FTP to Copy the Download Package Contents to the Web Server

The download package of osCommerce Online Merchant should be saved and extracted on your computer to reveal its contents. The catalog directory must be copied to the public HTML directory on the web server.

This can be achieved on most FTP clients by dragging the catalog directory from your local file browser panel to the remote panel listing the files on the web server.

Feel free to check out the following tutorial on how to upload files to a server.

All PHP files must be uploaded in ASCII mode (not in Binary mode).
File Permissions

The following files need to be writable by the web server.

Files Web Server Writable
catalog/includes/configure.php
catalog/admin/includes/configure.php

Feel free to check out osCommerce. Uploading files and changing permissions tutorial.

The catalog/includes/configure.php and catalog/admin/includes/configure.php files must have their web server writable permission removed after the installation procedure has completed successfully. This is described in the Post-Installation Steps chapter.

Please consult with your hosting provider for the correct permission flag to allow the web server to write to those files. This is commonly defined with a permission flag of 755.

In some cases a world write permission flag of 777 can be used but may lead to an insecure installation of osCommerce Online Merchant.

Changing the file permissions can be performed by most FTP clients or directly on the web server.

Using FTP/cPanel file manager to Change File Permissions

Most FTP clients are capable of changing file permissions on the web server. This is commonly performed by right-clicking on the file and selecting "Properties" or "Attributes" on the context menu.

The file permissions can be changed by allowing all users to read, write, and execute the file, or by manually entering the world readable and world writable flag of 777.

Feel free to check out the following tutorial on how to manage file/folders permissions using FTP manager or cPanel filemanager.

Database

A MySQL database on the web server or database server is required for the installation procedure to successfully import the database table structure and required data settings.

Feel free to check out the following tutorials on creating a database using cPanel and creating a database with GoDaddy.

Web Server and Database Server Details

The following web server and database server details are required during the installation procedure. Please consult your hosting provider if these details are not known.

Web Server Details

Setting Description Possible Value
Server Address The web address to the online store. http://www.yourwebsite.com/catalog/
Root Directory The directory where the online store is installed on the web server. /home/yourwebsite/public_html/catalog/

Database Server Details

Setting Description Possible Value
Server Address The address of the database server in the form of a hostname or IP address. localhost
Username The username used to connect to the database server. oscommerce_user
Password The password that is used together with the username to connect to the database server. securepassword
Database Name The name of the database to hold the data in. oscommerce
Please review the Pre-Installation Steps chapter before continuing with the installation procedure.

Installation Procedure

The web based installation procedure configures the online store and imports the configuration data into the database. This is necessary to create a fully functional online store and to create an administrator that administrates the online store through the Administration Tool.

The configuration values provided by default are safe to use but may need to be changed depending on the environment of the web server.

  • Installing a New Online Store
  • Step 1: Welcome Page
  • Step 2: Database Server
  • Step 3: Web Server
  • Step 4: Online Store Settings
  • Step 5: Finished!
Installing a New Online Store

The web based installation procedure is automatically started when accessing the online store through a web browser. This can be achieved by entering the WWW address of osCommerce Online Merchant installation in your browser.

For example:

http://www.yourwebsite.com/catalog/

osCommerce Online Merchant automatically detects if the installation has already been completed and redirects to the installation procedure if it has not yet been performed.

Feel free to check out the tutorial on final steps of installation.

Installation step 1. Welcome Page

The first step is the welcome page which displays the current recommended configuration settings for PHP:

Welcome Page

It is recommended to update a PHP configuration value, or to install and activate a PHP extension, if it is marked against the recommended setting.

When making PHP configuration changes or when installing and activating a PHP extension, the web server service needs to be restarted for the changes to take effect. Once restarted, refreshing the welcome installation page and viewing the Server Capabilities listing can confirm if the PHP configuration changes have taken place and if it meets the recommended settings.

Installation step 2. Database Server

The second step sets the database connection parameters to successfully connect to the database server, to import the database table structure, and to import required data:

Database Server

The installation procedure verifies the values entered before proceeding to the next step. If there is a problem connecting to the database server, an error message is shown similar to the message shown in the screenshot below:

Database Server
Make sure the correct username, password, and database name are listed.

Step 3: Web Server

The third step sets the web server parameters to successfully serve the online store to users:

Web Server

Step 4: Online Store Settings

The fourth step sets the store owner and administrator settings for the online store:

Online Store Settings

It is important to keep note of the administrator username and password as these are used to login and to access the Administration Tool.

Additional administrators can be created in the Administration Tool after the installation procedure has been successfully completed.

Step 5: Finished!

The last step in the installation procedure stores the database server and web server parameters to the configuration file on the web server. On successfully saving the configuration file, the installation procedure is finalized and the online store is ready to be used.

Finished

It is important to keep note of the administrator username and password as these are used to login and to access the Administration Tool.

Please review the Post-Installation Steps chapter after the installation procedure has been successfully completed to secure the online store.

Post-Installation Steps

Upon successful installation of osCommerce Online Merchant, the following steps need to be performed to secure the installation of the online store.

Remove Installation Files

The catalog/install directory must be removed from the web server otherwise a user could use the installation procedure and reconfigure the online store to use another database server.

Reset File and Directory Permissions

Configuration Files

The file permissions on catalog/includes/configure.php and catalog/admin/includes/configure.php must be set to deny write access by the web server service. This is commonly performed by setting the permission flag to a read only value of 644 or 444 depending on your server.

Writable Directories

The following directories must be set to allow the web server service to write to for the Administration Tool to function properly. This is commonly performed by setting the permission flags to a world-writable value of 777.

Directories Web Server Writable
catalog/images
catalog/cache (create this folder)
catalog/admin/backups
catalog/admin/images/graphs
Extra Protection for the Administration Tool

The Administration Tool is secured by its own login routine but is still publicly accessible. It is recommended to further protect the Administration Tool by setting a htaccess password on the catalog/admin directory.

If no extra protection is set for the Administration Tool, it is recommended to move the catalog/admin/backups directory outside the public html directory otherwise public access to the backup files would be possible. The location of the backup directory must be correctly defined in catalog/includes/configure.php.

Feel free to check out the following tutorial on how to secure your osCommerce store.

Template Features

In the process of development our templates have been customized and improved. New tools to improve functionality, convenience and appearance have been added. Among them there are the following: SEO URLs, Related products, Product tags, Nivo Slider, etc. You can check the details below.

This feature allows to select store products that will show up on the website as recommended products.

You can navigate to Catalog->Featured Products to add featured products:

Featured Products

You can see the list of Featured Products there.

In "Status" field you can show/hide the product in Featured Products section (it will stay in the list of featured products but it will not show up on the site).

In "Actions" field you can check, change or delete product details.

To modify the product details, you can click "Edit" button:

Featured Products

After filling in the required parameters, you can click "Update" button.

To add a new product to the Featured Products list, click "New product" button:

Featured Products

In the drop down list select the product you want to add and set the expiry date when it should be removed from the Featured products section, then click "Insert" button.

You can also use "Search" button:

Featured Products

You can search by product name and model.

These products can be displayed in the sidebar block:

Featured Products

On home page or category page that has subcategories:

Featured Products

Configuring the Featured Products Display

To configure the display of Featured Products, navigate to Configuration -> Featured and add the required settings:

Featured Products

This feature allows to add relations between products.

You can add relations under Catalog->Related Products section:

Related Products

You will see the list of related products (if they exist) and tools to manage them.

The drop down list at the top will help you to filter relations for specific product or for all products, by default it is set to Show All Products.

Under the drop down list there is a pages navigation (required if the list has more than 10 items).

The list below has the following fields:

  1. Product to which another product relates.
  2. Product that relates.
  3. Sort order.
  4. Edit and Delete buttons.

You can add new relations using the drop down lists below. You should fill in the following fields:

  1. Product to which another product relates.
  2. Product that relates.
  3. Sort order.

After adding relations use the following buttons to save the changes:

Insert - will add new relation to the list.

Reciprocate - will add new relation to the list (for both products).

Inherit - will add new relation to the list (only for one product).

Configuring the Related Products Display

To configure the display of Featured Products, navigate to Configuration -> Related Products and add the required settings:

Related Products

Related products will show up in the carousel on product page.

Tags

This feature allows to add tags to the products and search products by these tags.

You can navigate to Catalog->Tags in order to add tags:

Tags Products

You will see the list of all products there.

To add or modify tags, select the required product and click "Edit" button.

Tags Products

In Tags field, add tags separated with commas and click "Save".

If you want to remove all tags from the product, you can click "Delete" button.

In your store tags will show up in the sidebar block:

Tags Products

In the block on product page:

Tags Products

If you click the tag, you will see the list of products that have it:

Tags Products

Nivo Slider

This feature allows to add frontend banners with captions.

You can navigate to Configuration -> Nivo Slider to configure the slider:

Nivo

You can add all the required slider effects and select the group of banners that will show up in your slider.

We will describe how to add banners in the section Creating Banners.

To display the slider on your frontend, you can navigate to Modules -> Boxes -> Nivo Slider and select one of two positions (Under Header Block/Home Content Block) for your slider and its sort order.

Banner Box & Content Banner Box

Banner Box & Content Banner Box are two similar modules that allow to display groups of modules in different positions dynamically.

To configure the modules, navigate to Modules -> Boxes and find the required module. Click "Edit" button and set position and group of banners.

We will describe how to add banners in the section Creating Banners.

SEO Url

This feature was added to improve the search engines indexing and, as a result, to have a higher position of your website in search engine results.

You can navigate to Configuration -> SEO Urls to add all the settings:

Seo

It is multilingual and works with products and categories.

Live Chat Olark

The template includes Live Chat Olark.

You can navigate to Configuration -> My Store -> Live Chat Olark to enable/disable it.

By default, it has sample data details. To get your data, you can register on Olark website and do all the required steps to get your code.

Then, open includes/template_bottom.php file and insert the received code between the lines begin olark code and end olark code and save the file.

Modules -> Boxes

16 modules were added to the template to extend functionality of the website. They are located under Modules -> Boxes.

To set the module, select the module and click "Edit" button:

boxes

You will see the screen where you can add all the block settings (Module Header Hopping Cart is used as an example).

For example:

  1. Enable or disable on the frontend.
  2. Module position (positions in other modules may differ from positions described in the example) Header Top/Header.
  3. Sort order in the position where the module will show up.
  4. Enable/disable the hopping cart (only for the described module, other modules will have other options).
  5. Pages where the module will show up.

Click "Save" button to save the settings.

Addendum

We did our best to make this documentation as clear as possible. However, if you have any difficulties with osCommerce template or any suggestions on improving the template or documentation, feel free to contact our support team through the:

Additional Links
Loading data from Google servers

Some countries have issues connecting to Google servers. This can cause issues loading Google Fonts and Java Script libraries from Google CDN. To resolve these issues please do the following:

Can't load Google Fonts:
  1. Open \includes\template_top.php file
  2. Locate the line:
    href='//fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'
  3. Replace it with the following:
    href='//fonts.useso.com/css?family=Open+Sans' rel='stylesheet' type='text/css'