OSCommerce3 Template Structure Implementation

Template Structure Implementation

The template structure implementation allows template design packs to change the design layout of the online store front-end without the need to edit core source code files. If multiple template design packs are installed and are active, customers can be given the choice which template design they would like to use or a specific template design can be used depending on the customers environment (e.g. a lite layout for mobile devices).

The template structure implementation is not a traditional template engine solution where specific keywords in a HTML file are replaced by values produced by PHP logic. A template engine is not needed with the template structure implementation due to the Object-Oriented design the core framework has been programmed in. As no traditional template engine functionality exists, any template engine solution can easily contemplate the template structure implementation if needed.

• How It Works
• Template Design Pack Structure
• How Pages Are Loaded

How It Works

The template structure implementation separates the main content from the whole page and allows the main content to be applied to different "outfits" to have a different overall look. Each template design pack ("outfit") is controlled through style-sheet definitions to allow the main content to fit in with the rest of the design. If more control is needed the main content can be copied to the template design pack where the file can be edited to match the design precisely.

The "outfit" is setup in one template file which controls where the header, footer, left and right columns, and main content are to be laid out on the page. Modifying the "outfit" reflects all pages shown through it. A page can further control if the header, footer, or left and right columns are to be displayed and is controlled mainly for pop-up windows.

Further layout changes can be performed on the Administration Tool to control which content boxes and which content modules are shown on a page and in what order they are shown. Although template design packs will install a specific layout for content boxes and content modules, the store administrator can extend on the design when add-ons that display a content box or content module are installed.

Template Design Pack Structure

Template design packs contain the following file and directory structure referenced by the template code name:

1. oscommerce/templates/default.php
2. oscommerce/templates/default/content/
3. oscommerce/templates/default/images/
4. oscommerce/templates/default/javascript/
5. oscommerce/templates/default/modules/
6. oscommerce/templates/default/stylesheet.css
7. oscommerce/admin/includes/templates/default.php

The file listed on line 1 is a simple PHP/HTML file defining how the page is to be laid out. It makes numerous calls to the osC_Template class to find out if certain elements are available (e.g. content modules) to display them.

The directory listed on line 2 contains the main content for each page in separate files. If a file for the main content of a page does not exist the file from the default assigned template is used. This allows template design packs to be easily created as the main content for all pages does not need to be worked on. If the design of a main content page needs to be adjusted to the design, the file from the default assigned template can be copied to the directory of the template design pack where it can be fine-tuned.

The default assigned template must contain all main content pages that other template design packs can use.

The directory listed on line 3 contains images used for that template design pack. All images found on the default assigned template must also exist in all template design packs.

The directory listed on line 4 contains javascript files that main content pages include or reference externally. All javascript files found on the default assigned template must also exist in all template design packs.

The directory listed on line 5 contains template files that define how the content of boxes and content modules are laid out. If a file for the box or content module does not exist the file from the default assigned template is used.

The default assigned template must contain all template files for boxes and content modules that other template design packs can use.

The file listed on line 6 is the stylesheet definition file for the template design pack.

The file listed on line 7 is the template class which installs and uninstalls the template design pack from the store front-end and is executed from the Administration Tool.

Please reference and copy from the existing templates when creating new template design packs.

How Pages Are Loaded

All pages are assigned a group to contain related pages in a directory. The main file that is requested in the URL is the group where the page to load is passed as a parameter. This allows a clean URL design when requesting pages.

For example:

http://www.example.com/oscommerce/products.php?new

products.php is a file that defines a group titled products and loads a content class with the code name of new to load a specific page.

The requested products.php file is defined as:

01. <?php
02.   $_SERVER['SCRIPT_FILENAME'] = __FILE__;
03. 
04.   require('includes/application_top.php');
05. 
06.   $osC_Language->load('products');
07. 
08.   $osC_Template = osC_Template::setup('products');
09. 
10.   require('templates/' . $osC_Template->getCode() . '.php');
11. 
12.   require('includes/application_bottom.php');
13. ?>

Line 8 setups the page and loads a default content class if one is not requested and passed as a parameter in the URL. The osC_Template::setup() class method automatically detects if a parameter is passed in the URL to load a specific content class.

Content classes inspect the environment to determine what page to load, and exist in the oscommerce/includes/content/<group>/ directory. For the above example, the oscommerce/includes/content/products/new.php content class would be loaded. This file is defined as:

<?php
  class osC_Products_New extends osC_Template {

/* Private variables */

    var $_module = 'new',
        $_group = 'products',
        $_page_title,
        $_page_contents = 'new.php',
        $_page_image = 'table_background_products_new.gif';

/* Class constructor */

    function osC_Products_New() {
      global $osC_Language;

      $this->_page_title = $osC_Language->get('new_products_heading');
    }
  }
?>

This loads the default page content of new.php which is found in the oscommerce/templates/<template>/content/<group>/ directory, specifically oscommerce/templates/<template>/content/products/new.php.

This allows logic to exist in the class constructor to inspect the environment and to overwrite the $_page_contents class variable to load another page in the oscommerce/templates/<template>/content/products/ directory.

If no parameter was passed to products.php then the default content class oscommerce/includes/content/products/products.php would be loaded instead (as defined on line 8 above).