TomatoCart

Introduction

This is a tutorial on how to make a module for the web desktop admin panel of TomatoCart. There are two parts in this tutorial; the first part contains a short description of the admin panels architecture and the second part is a step-by-step walkthrough on creating products categories grid window in the admin panel.

TomatoCart is still in alpha release and its architecture will change in future, therefore this tutorial is only for TomatoCart Alpha release 1 and 2. It will be change later according to the change in the TomatoCart architecture.

TomatoCart Admin Panel's Architecture

TomatoCart is a fork project of osCommerce 3, therefore it derives most of the business logic and the architecture from osCommerce 3. The admin panel of osCommerce 3 is designed base on Model-View-Controller (MVC) architecture; while the TomatoCart’s web desktop is based on RIA framework. Comparing to web-based MVC architecture, RIA architecture have several differences:

1. RIA’s user interface is created by Javascript not plain HTML page
2. The interactions between client and server is through Ajax instead of page submissions
3. In MVC the controller handles the input event from the user interface and forwards the page to different view according to the action process result; while in RIA the GUI code update the user interface according to the Ajax result.

To make the TomatoCart Admin Panel’s architecture clear, Figure 1 gives the screenshot of TomatoCart's admin file structure and the following is the short description of the core files and directories:

Figure 1 TomatoCart Admin Panel Directory Architecture

1. index.php
   index.php is the entry point of the administration panel. It includes the css and javascript code to make the user interface.
2. json.php
   json.php is used to handles the Ajax requests from the client user interface. It invoke the action handler according to the module and action parameter submitted from client; and return the result of the action handler back to client.
3. load.php
   load.php is used to load application modules’ javascript code at runtime. During the application start-up, TomatoCart does not load all the application modules, but only the code that makes the web desktop. The module code is loaded when user click on the module in the start menu. This helps minimize the application startup loading time and make the startup loading consistent.
4. tocdesktop.php
   tocdesktop.php contains the javascript code to construct the TomatoCart desktop. The code retrieves the desktop settings from database including start menu items, desktop shortcut items, application modules and desktop themes etc.
5. includes/classes
   The classes in the “includes/classes” folder are the model classes that are used access database. There are some utility classes in this folder such as the currencies, shipping module and payment module etc.
6. includes/extmodules
   The javascript classes in the “includes/extmodules” folder are GUI codes that construct the user interface. Each sub-directory in this folder contains the GUI codes for this module.
7. includes/jsons
   The PHP classes in the “includes/jsons” folder are action handlers that process the ajax requests from client user interface. Each class contains all the action process methods for the specific module.
8. includes/languages
   The “includes/languages” folder contains translations for user interfaces. The language files are windows INI style files, every entry has a name and a value, delimited by an equals sign (=).
9. includes/modules
   The module classes in the “includes/modules” folder represents the plug-in module for TomatoCart such as shipping modules, payment modules, order total modules etc.

Module Architecture

The TomatoCart admin panel framework is based on a module-oriented architecture. Each module is composed of several components: module menu path, translations, user interface component, ajax action processing component and data access component. These files are scattered in different location, we will use the product categories module as an example to illustrate the file structure. Figure 2 is the screenshot of categories module’s file structure, we will go through the component one by one:

Figure 2 categories module’s file structure

1. modules/access/categories.php
   The categories.php file in the access folder contains the menu path setting for the categories module. These settings are including menu group、menu title、menu sort order and submenus. Menu group is the first level menu in the TomatoCart start menu as illustrated in Figure 3, as modules are separated into several menu groups. The second level is the categories module itself. Each module can have submenus, for example the products module have two submenus, one is products list and the other is new product.
   
   Figure 3 TomatoCart Start Menu
2. languages/en_US/modules/categories.php
   The categories.php file here contains the translations for the title of menus defined in module access class.
3. extmodules/categories/
   As mentioned in previous section the extmodules folder contains the view components of each module. As we seen from figure 4, there are four php files in the categories directory. The main.php is the entry point for each module, it contains the meta information of the module and factory method to create dialogs in this module. The other three files are javascript classes construct the GUI window.
   
   Figure 4 categories module's user interface component
4. jsons/categories.php
   The categories.php is responsible for processing the Ajax requests and return the database back to client GUI component such as list existing categories, save new category, update category and delete category. Each static method in this class stands for one action.
5. classes/categories.php
   This class contains methods to create, update or delete product category in database.
6. languages/en_US/categories.php
   This file stores translations for field labels in the user interface and the notification message translations.

Step by step to create a categories list window

After examining the admin panel’s architecture, we are going to crate a categories list window in the admin panel. Figure 5 is the screenshot of the categories list window, this window lists categories in a ExtJS grid panel.

Figure 5 categories list window

1. Creating an access class
   The first step is to create an access class in the access folder, the class name should be started with “osC_Acess_” and ended with the module name “Categories”. The member attributes ($_module, $_group, $_sort_order) has to be specified to define the module、menu group and order of this module in the menu group. The $_icon member variable is derived from osCommerce, it will be deprecated in the next release. The $_title variable is the title of the module menu, it is initialized in the constructor because the translation of the title has to be retrieve at runtime.
   
2. Creating a translation for categories menu title
   The second step is to create a categories.php file in the “languages/en_US/modules/” folder and specify the translation of the “access_categories_title” in this file.
   
3. Displaying categories with grid
   The categories grid panel displays products categories like a spreadsheet. Displaying data in a grid requires two steps:

   Setting up a data store

   The javascript code below sets up a data store and specify the source of the store. The data source is an remote url, the Toc.CONF.CONN_URL constant stands for the json.php file and the module and action is specified in the baseParams.

   

   Creating the GridPanel

   The second step is to create a GridPanel class and display the data in the GridPanel. We create a new class Toc.categories.CategoriesGrid and use the Ext.extend method to inherit it from Ext.grid.GridPanel. Following javascript code is the code to create the class:
   
   First a constructor function object is declared and assigned to Toc.categories.CategoriesGrid. Within this constructor a config object is created and initialized. At the end of the constructor, the superclass constructor is explicitly called namely the constructor of the Ext.grid.GridPanel class. The Ext.extend statement is used to extend the Toc.categories.CategoriesGrid from Ext.grid.GridPanel and define extra attributes and methods to base class namely the Ext.grid.GridPanel class.
4. Setting up ajax request handler
   As mentioned in previous section the data store source is a remote URL. In this step we are going to setup an action handler to process the request and return the data to data store. A “categories.php” file has to be created in the “includes/json” folder and there is a name convention for this class. The json class has to be started with “toC_Json” and end with the module name, in this case “Categories”. In this json class a static method has to be created for each ajax request to process data. As we seen from the code below, the static method listCategories is create to process the “list_categories” ajax request. The action processing functions should be named using the " camel caps " style. Within this method, the categories data is retrieved from database and store in a temporary array. Finally this array is encoded in json string and send back to client.
   
5. Creating translations for user interface
   A new catgories.php file has to be created in “languages/en_US/” folder and the translations for column tile etc has to be specified in this file.
6. Displaying the categories grid window
   The final step is to display the grid window in the desktop. Every module has a factory method “createWindow” in the main.php file, this method is invoked when user click on the module at start menu. In the “createWindow” method, a new instance of the Toc.categories.CategoriesGrid class is created and the desktop instance is retrieved from application object. Then the desktop.createWindow function is used to create a new window with the grid centered in the window. The reason why we put the creation of the window in the main.php and separate the window with the CategoriesGrid is because we want to keep the possibility to create different layout for the admin panel. We put each GUI class in a separated file to make the structure more clear. When a developer want to create different layout for the admin panel, he only have to change the architecture code instead of all GUI code.