- How do I add a new file to the osCommerce menu system?
- How do I change text labels??
- How do I translate my website into my language?
- What file do I modify to do X ?
- How do I add a new file to the osCommerce menu system?
osCommerce references its internal files and database tables indirectly. The system by which this is done is centralized around three files : filename.php, database_table.php, the top level language file. The system is used by both procedural and user interface files which are usually a "box" file, but may be a header, footer, navigation or page file. CRE Loaded and other Basic Template System (BTS) centric osCommerce derivatives complicate this by adding various "template" files to the structure. I'll comment more on those later, but for now will describe the basic osCommerce system.
Filename.php exists in two incarnations. One for the catalog tool, and one for the admin tool. Each is found in the includes directory for that tool. Fundamentally filename.php consists of a series of define(); statements which establish an internal name for each file added to the system. Each entry begins with the "FILENAME_" prefix, and follows the php guideline that all constants are entered in ALL CAPS. The next portion of the entry denotes the subsystem to which the file being named belongs. This is followed as necessary by additional tags that further define the file's function. Thus we know that FILENAME_ARTICLES is the top level file for the ARTICLES system. Common entries look like this :
// BOF: Lango Added for Order_edit MOD
define('FILENAME_CREATE_ACCOUNT', 'create_account.php');
define('FILENAME_CREATE_ACCOUNT_PROCESS', 'create_account_process.php');
define('FILENAME_CREATE_ACCOUNT_SUCCESS', 'create_account_success.php');
define('FILENAME_CREATE_ORDER_PROCESS', 'create_order_process.php');
define('FILENAME_CREATE_ORDER', 'create_order.php');
define('FILENAME_EDIT_ORDERS', 'edit_orders.php');
define('FILENAME_C_ORDERS', 'c_orders.php');
define('FILENAME_ORDERS_STATUS', 'orders_status.php');
define('FILENAME_CREATE_ORDERS_ADMIN', 'create_order_admin.php');
// EOF: Lango Added for Order_edit MOD
Note that the file definition includes the *.php tag, so that no concatenation is needed when the constant is used in system files. Also, you can see clearly in this snippet how the indivdual tags help make the constants usages clear. create_account.php is the file containing the top level functions for the account creation subsystem. The actual process is handled in create_account_process.php, and successful account creation is handled by the create_account_success.php file.
The top level language file contains the 2nd part of the file structure system. Each subsystem is entered at a top level file. The link to that file is formed using the entry in filename.php to set the file target. The label for that link comes from the top level language files BOX_* entries. The entries in admin/includes/language/english.php which correspond to the above filename.php snippet looks like this :
define('BOX_CREATE_ACCOUNT', 'Create New Account');
define('BOX_CREATE_ORDER', 'Create New Order');
define('BOX_CREATE_ORDERS_ADMIN', 'Create Orders Admin');
Notice that not all FILENAME_* entries have a corresponding BOX_* entry. The files which lack an entry here contain code which functions at a deeper level and should not be called directly by a site user. You can also see that the BOX entries follow a structure which is similar to that of the FILENAME entries. BOX tells you that this label is used in creating an infobox or menu box. CREATE tells you that the menu entry allows you to create a new database entry. The third tag tells you what it creates. A fourth tag (or even more) can further refine what the file does. BOX_CREATE_ORDERS_ADMIN labels a link to the file which will allow you to administrate the Order Creation system used to enter orders from the Admin Tool. These tags should be duplicated in the top level language file for every language present in the cart. This is how osCommerce allows the cart to be quickly and easily translated into multiple languages.
These two entries form the basis for all internal linking within the system. They must be in place before running any appropriately formed osCommerce module. The third entry which must be in place is the database_table.php entry. This allows indirect referencing of database tables, an important feature which can help maintain security of the cart, and allow use of alternative tables within a development situation. A segment of database_table.php looks like this :
define('TABLE_ORDERS', 'orders');
define('TABLE_ORDERS_PAY_METHODS', 'orders_pay_methods');
define('TABLE_ORDERS_SHIP_METHODS', 'orders_ship_methods');
define('TABLE_ORDERS_PRODUCTS', 'orders_products');
define('TABLE_ORDERS_PRODUCTS_ATTRIBUTES', 'orders_products_attributes');
define('TABLE_ORDERS_PRODUCTS_DOWNLOAD', 'orders_products_download');
define('TABLE_ORDERS_STATUS', 'orders_status');
define('TABLE_ORDERS_STATUS_HISTORY', 'orders_status_history');
define('TABLE_ORDERS_TOTAL', 'orders_total');
Again, the tag system tells you what it refers to in a top down manner. These are database TABLE definitions, for the ORDERS tables. Without these entries, you will see errors indicating that the table does not exist, even if it does.
The next critical point for integration of contribuitons is the box file. The box file contains the code for generating one menu box in a side column. A standard osCommerce box will look like this :
<?php
/*
$Id: customers.php,v 1.16 2003/07/09 01:18:53 hpdl Exp $
osCommerce, Open Source E-Commerce Solutions
http://www.oscommerce.com
Copyright (c) 2002 osCommerce
Released under the GNU General Public License
*/
?>
<!-- customers //-->
<tr>
<td>
<?php
$heading = array();
$contents = array();
$heading[] = array('text' => BOX_HEADING_CUSTOMERS,
'link' => tep_href_link(FILENAME_CUSTOMERS, 'selected_box=customers'));
if ($selected_box == 'customers') {
$contents[] = array('text' => '<a href="' . tep_href_link(FILENAME_CUSTOMERS, '', 'NONSSL') . '" class="menuBoxContentLink">' . BOX_CUSTOMERS_CUSTOMERS . '</a><br>' .
'<a href="' . tep_href_link(FILENAME_ORDERS, '', 'NONSSL') . '" class="menuBoxContentLink">' . BOX_CUSTOMERS_ORDERS . '</a>');
}
$box = new box;
echo $box->menuBox($heading, $contents);
?>
</td>
</tr>
<!-- customers_eof //-->
Notice the use of the FILENAME_* and BOX_* constants to form links using the tep_href_link function. This approach is used in the Catalog infobox structures on both standard osCommerce and the CRE Loaded Edition. The approach is different on the Admin infoboxes, as CRE Loaded includes the Admin Access with Levels contribution. The equivalent infobox looks like this :
<?php
/*
$Id: customers.php,v 1.1.1.1 2004/03/04 23:39:43 ccwjr Exp $
osCommerce, Open Source E-Commerce Solutions
http://www.oscommerce.com
Copyright (c) 2002 osCommerce
Released under the GNU General Public License
*/
?>
<!-- customers //-->
<tr>
<td>
<?php
$heading = array();
$contents = array();
$heading[] = array('text' => BOX_HEADING_CUSTOMERS,
'link' => tep_href_link(FILENAME_CUSTOMERS, 'selected_box=customers', 'SSL'));
// Eversun mod for sppc and qty price breaks
/* if ($selected_box == 'customers' || $menu_dhtml == true) {
$contents[] = array('text' =>
//Admin begin
tep_admin_files_boxes(FILENAME_CUSTOMERS, BOX_CUSTOMERS_CUSTOMERS, 'SSL') .
// tep_admin_files_boxes(FILENAME_MEMBERS, BOX_CUSTOMERS_APPROVAL) . // VJ member approval added
tep_admin_files_boxes(FILENAME_ORDERS_CHECK, BOX_CUSTOMERS_ORDERS_CHECK) .
tep_admin_files_boxes(FILENAME_ORDERS, BOX_CUSTOMERS_ORDERS) .
//begin PayPal_Shopping_Cart_IPN
tep_admin_files_boxes(FILENAME_PAYPAL, BOX_CUSTOMERS_PAYPAL) .
//end PayPal_Shopping_Cart_IPN
tep_admin_files_boxes(FILENAME_CREATE_ACCOUNT, BOX_MANUAL_ORDER_CREATE_ACCOUNT) .
tep_admin_files_boxes(FILENAME_CREATE_ORDER, BOX_MANUAL_ORDER_CREATE_ORDER) .
tep_admin_files_boxes(FILENAME_CREATE_ORDERS_ADMIN, BOX_CREATE_ORDERS_ADMIN));
//Admin end
} */
if ($selected_box == 'customers' || $menu_dhtml == true) {
$contents[] = array('text' => tep_admin_files_boxes(FILENAME_CUSTOMERS, BOX_CUSTOMERS_CUSTOMERS) .
tep_admin_files_boxes(FILENAME_ORDERS_CHECK, BOX_CUSTOMERS_ORDERS_CHECK) .
tep_admin_files_boxes(FILENAME_ORDERS, BOX_CUSTOMERS_ORDERS) .
//begin PayPal_Shopping_Cart_IPN
tep_admin_files_boxes(FILENAME_PAYPAL, BOX_CUSTOMERS_PAYPAL) .
//end PayPal_Shopping_Cart_IPN
tep_admin_files_boxes(FILENAME_CREATE_ACCOUNT, BOX_MANUAL_ORDER_CREATE_ACCOUNT) .
tep_admin_files_boxes(FILENAME_CREATE_ORDER, BOX_MANUAL_ORDER_CREATE_ORDER) .
tep_admin_files_boxes(FILENAME_CREATE_ORDERS_ADMIN, BOX_CREATE_ORDERS_ADMIN) .
tep_admin_files_boxes(FILENAME_CUSTOMERS_GROUPS, BOX_CUSTOMERS_GROUPS));
}
// Eversun mod end for sppc and qty price breaks
$box = new box;
echo $box->menuBox($heading, $contents);
?>
</td>
</tr>
<!-- customers_eof //-->
Notice that this box still uses the FILENAME_* and BOX_* constants. What makes the CRE Loaded version different are two things. Inclusion of the DHTML drop down menu system, and the use of the tep_admin_files_boxes(); function. This function allows access to each menu entry to be secured based on configuration settings created by the stores administrator. Conversion of link array entries into this format is an essential but simple part of porting any osCommerce contribution which adds administrative functionality.
[Back To Top]
- How do I change text labels??
The osCommerce 2.x language system is very simple.
Generally, for each file in the script which contains code, there is a file in the language tree with the same name that holds all of the text which is displayed by that module.
For example :
checkout_success.php which handles processing of successful orders, gets its text from includes/languages//checkout_success.php.
The language file contain simple definition statements that hold the text you would want to display in the a particular language. includes/languages/english/checkout_success.php holds the English text, includes/languages/french/checkout_success.php holds the French language, etc.
The definitions look like this :
define ('THIS_TEXT_LABEL','Some text to print');
in the example above, THIS_TEXT_LABEL is a php constant.
That is, once it is defined, it is not changed by the script during that session. The contents remain constant.
If a constant is not defined, the name of the constant is output by the script instead.
So, if on the checkout success page you see TABLE_HEADING_COMMENTS printed above the comments text area entry field, you will know that some error in the checkout _success.php language file has caused this constant not to be defined (perhaps you failed to terminate a line above this with a ; , or accidently commented it out).
To change the contents of these constants, it is merely necessary to change the text between the 2nd set of single quotes - taking care to use appropriate PHP character usage rules.
Those rules can be found at http://us3.php.net/types.string .
[Back To Top]
- How do I translate my website into my language?
First, you must create a new language. This is done via the Admin / Localization / Languages tool. Before using it, you should use FTP to create a new directory in includes/languages and admin/includes/languages. The name of this directory should be the same as the language you intend to use. If you were adding Esperanto for example, you might use esperanto as the directory name. You will be asked to provide an image (usually a small flag icon) for the language, and the directory to use for storage of language files. Following this you will have to create the language file set. The quickest way to create this is to copy the contents of the english directory into your new language directory, and create a copy of the english.php file renamed to match your new language - esperanto.php in this example. After that, you simply modify all the text tags or definitions as described below.
The osCommerce 2.x language system is very simple.
Generally, for each file in the script which contains code, there is a file in the language tree with the same name that holds all of the text which is displayed by that module.
For example :
checkout_success.php which handles processing of successful orders, gets its text from includes/languages//checkout_success.php.
The language file contain simple definition statements that hold the text you would want to display in the a particular language. includes/languages/english/checkout_success.php holds the English text, includes/languages/french/checkout_success.php holds the French language, etc.
The definitions look like this :
define ('THIS_TEXT_LABEL','Some text to print');
in the example above, THIS_TEXT_LABEL is a php constant.
That is, once it is defined, it is not changed by the script during that session. The contents remain constant.
If a constant is not defined, the name of the constant is output by the script instead.
So, if on the checkout success page you see TABLE_HEADING_COMMENTS printed above the comments text area entry field, you will know that some error in the checkout _success.php language file has caused this constant not to be defined (perhaps you failed to terminate a line above this with a ; , or accidently commented it out).
To change the contents of these constants, it is merely necessary to change the text between the 2nd set of single quotes - taking care to use appropriate PHP character usage rules.
Those rules can be found at http://us3.php.net/types.string .
[Back To Top]
- What file do I modify to do X ?
The secret to this lies in the URL and a little knowledge of the template layout. For template information see the BTS FAQ set.
osCommerce based URL's generally look like this :
http:///catalog/checkout_process.php? or
http:///index.php?cPath=22&osCsid=
Looking at this standard URL (not URL's modified for "search engine modification") will tell you just where to go.
Why? because the part of the URL to the right of the first single forward slash after the domain name is a file path relative to the carts root directory. So, modifications on a page with the first url should be made in checkout_process.php, templates/contents/checkout_process.tpl.php or includes/languages//checkout_process.php .
Modifications to the 2nd URL would be made in the index_*.php files. This is a bit tricker as the index file system is split up in order to generate different types of displays - but notice that it at least narrows down your search. 4 or 5 filenames to search for is a lot better than 2000 right?
Notice the includes/languages// filename above. Remember that for each file which contains PHP code, there is an equivalent file with the same name for each complete language in the cart. This is where you should be going to change the text generated on the page.
[Back To Top]
|
|
