Brief developer summary

This article describes basic operating principles of WebAsyst Shop-Script application which will be useful for development of new modules or modification of the original source code.

General operational logic of Shop-Script

Entry points

Addressing file published/SC/html/scripts/index.php

1. Application initialization (general environment variables, database connection parameters).
2. Establishing connection to the database.
3. Check whether meta data update is required (this may be necessary if a software update has been installed using WebAsyst Installer but the database structure/contents have yet not been updated).
4. Initialization of user-related application settings (constants with CONF_*-like names that are stored in the SC_settings table); e.g., store name, connection credentials to payment gateways, etc.
5. Request URL parsing: class fUrl analyzes the address parameters ($_REQUEST) to determine which screen must be displayed to user or which action must be executed, etc.
6. Initialization of the Smarty template engine.
7. Retrieving the did identifier of the called division. The called division is determined by the request URL contents analyzed in step 5.
8. Access rights to the screen are checked (applicable only for the backend).
9. Retrieving the interface list of the called division (stored in table SC_division_interface). Interfaces are used as connectors between divisions and functional modules. They are used to establish connection between user actions and the application functions.
10. Retrieving the list of inheritable interfaces.
11. Calling retrieved interfaces one by one:
1. initialization of the module containing interface;
2. actual execution of code of that interface contained in module.
12. Initialization of the storefront design template.
13. Displaying the template to user using Smarty. During the template processing additional components are processed which are included in the template by means of the design editor (e.g., product lists, news titles, etc.). Output of the resulting HTML code.

Application structure

Divisions

Divisions represent the internal hierarchy ("skeleton") of the online store. The entire division structure (they can also be referred to as pages or sections) is stored in table SC_divisions in the form of a tree where their hierarchy is defined. Each division has a numeric identifier did. In the backend divisions are addressed by their did's. In the public storefront, divisions are addressed by a string-type ukey parameter which is determined based on the current page URL (e.g., category, home, cart, etc.).

Modules

This is the "functional kernel" of the store. All modules are stored in directory published/SC/html/scripts/modules/. Each module is represented by a separate subdirectory with a number of files inside it.

Each module always has an XML description file %module_name%.xml. Tag <File> contains the name of the main class file which implements the module's functionality.

<Connector>
    <Class>
        <Name>%ModuleClassName%</Name>
        <File>%module_file_name.php%</File>
        <Title>%module_title%</Title>
        <Description>%module_description%</Description>
        <SingleInstallation>true</SingleInstallation>
    </Class>
</Connector>

File %module_file_name.php% defined in XML tag <File> (we recommended that the file name without extension should match the module subdirectory name) must exist and contain declaration of a class extending basic class Module or AbstractModule. Information about installed modules is stored in tables SC_modules and SC_module_configs which are mutually connected by ModuleID field.

Interfaces

Interfaces contain programming code which is executed in the module-related context. This may be implemented in the form of methods of the module class or as external files located in the _methods/ subdirectory of the module's directory which are included when interfaces of those files are called. Descriptions of available module interfaces are stored in module parameter Interfaces or in XML files inside subdirectory _methods/; interfaces are initialized in module method initInterfaces.

Interface key matches the name of the interface file and the name of its description file (without extensions).

<interfaces>
    <interface>
        <name>Localization strings search</name>
        <key>find_local</key>
    </interface>
</interfaces>

$this->Interfaces = array(
  'bnews' => array(//b_news — interface key
    'name' => 'Manage news',
    'method' => 'methodBNews',//module class method is specified explicitly
    ),
  'b_subscribers' => array(
    'name' => 'Manage subscribers',
    'type' => INTDIVAVAILABLE,
    //no method is specified; therefore, code in file _methods/b_subscribers.php will be executed
    ),
);

Relationship between interfaces and divisions

The relationship  between a division and a modules' interfaces is defined in table SC_division_interface. Division identifier xDivisionID is used to create a xInterface string of the form "[number]_[string]" where number is the module identifier in table SC_modules_configs and string is the identifier (key) of the module interface. Each division can be connected with several interfaces which are called in the order defined by their xPriority values; an interface can also be inheritable (xInheritable) for child divisions.

Components

Components are informational blocks used in page templates. In the built-in design editor they are presented as the list of available page structure elements which can be freely moved across the template and can be assigned several additional properties. A component represents a separate type of module interfaces which contains a description of applicable settings and properties as well as a list of templates it can be used in.

Module collections

Module collections are modules incorporating a set of "submodules". For instance, the payment module is actually a set of integration submodules for various payment systems and gateways.

There are no strict naming rules for module PHP files, but it is recommended to use format class.%class_name%.php because information about the module is added at the beginning of the module file by means of special phpDoc tags.

The presence of tag connect_module_class_name in the module file is a requirement as it contains the module class name. In some modules additional tags are also used. An example of module description:

<?php
/**
 * @connect_module_class_name PPExpressCheckout
 * @package DynamicModules
 * @subpackage Payment
 */
class PPExpressCheckout extends PaymentModule {
...

In method _initVars module properties are declared: title, description, Settings.
In method _initSettingFields description of module settings is defined in the form of an associative array.

Settings are saved in table SC_settings which utilizes the following format:

module_id is a numeric identifier of the module instance,
module_type is the numeric designation of the module type (e.g., shipping, payment, print forms, etc.),
module_name is the module name,
ModuleClassName is the module class name.

For adding and removing of module instances, methods install() and uninstall() are used; modules may have several instances within the application if parameter SingleInstall is set to value false. Installing and uninstalling methods save module settings in the database.

Shipping modules

These modules reside in directory published/SC/html/scripts/modules/shipping/ and are used for determination of current applicability and the calculation of the shipping rates until an order has been finalized.

Method allow_shipping_to_address() checks whether delivery is possible to the address specified by customer.
Method calculate_shipping_rate() calculates the shipping rate for delivery to the specified address.

Payments modules

These modules reside in directory published/SC/html/scripts/modules/payment/.

There are several types of payment modules:

PAYMTD_TYPE_CC: credit card payments;
PAYMTD_TYPE_ONLINE: payments via online payment systems;
PAYMTD_TYPE_MANUAL: manual payments processing;
PAYMTD_TYPE_REPLACE: alternative checkout option (Google Checkout/Paypal) when customer enters his/her payment credentials on a third-party web page outside of the Shop-Script storefront.

Method payment_form_html() is used to generate the HTML code of the payment form.
Method after_processing_php() is called after order details have been saved in the database.
Method payment_process() performs verification and transmission of order details to the payment gateway server; in the base class it is implemented as a "stub" which always returns 1.
Method after_processing_html() is called after order details have been saved in the database, it returns HTML code of the button which must be clicked by the customer to redirect a customer to the gateway's payment page.

Print form modules

These modules reside in directory published/SC/html/scripts/modules/printforms/; templates and graphical resources used by the modules are located in directory published/SC/html/scripts/templates/forms/. These modules are used to generate various order-related print forms; e.g., invoices.

Method display() is used to display the particular print form.

File storage

Files uploaded trough the store backend are saved in one of the following directories:

• data/

  Here are stored protected files which either should not be directly available (HTTP access is restricted on the server level; e.g., by means of file .htaccess) or may be made available for downloading only after successful authorization (e.g., digital products which may only be downloaded after an order has been successfully paid for).

• published/publicdata/

  Here are stored files directly available over HTTP: CSS files, images files used in the storefront design, product image files.

Localization

Shop-Script supports localization both for text strings used in its web interfaces and those saved in the database as part of user-generated content such as product names, descriptions, etc. The list of available localization languages and the localization-editing tool are available in backend section "Design -> Languages & Translation".

Every time when a new language is added, a number of SQL queries are automatically executed to add new fields to the database tables where the basic entities data are stored that can be translated into the newly added language. The list of such tables (which may contain localized data) is stored in file published/SC/html/scripts/cfg/database_structure.xml. For example, when the German language with identifier "de" is added, the following fields are automatically added to the products data table: product_name_de, brief_description_de, description_de.

Interface localization strings are editable by means of the localization tool in the store backend and are saved in database table SC_locals where field id designates the particular localization string, lang_id is the language identifier, value contains the localized value, group contains the identifier of the group to which the particular localization string belongs (publicly available strings are stored in groups hidden, front, general, and those used in the backend belong to groups back and general), subgroup contains the localization string subgroup identifier (see file published/SC/html/scripts/cfg/localgroup.xml).

Localized string constants of the installed modules (e.g., payment modules) reside in subdirectory languages/ of the corresponding module's directory in the form of PHP files named according to format %iso2%.%class_name%.php. Strings for the current user language are retrieved from one these files when it is necessary to display information related to the particular module. This part of the user interface localization is not stored in the database.

Cache

The current Shop-Script version stores its cache in the following locations:

Database connection settings: temp/scdb/.settings.%dbkey%
Localization: data/%dbkey%/attachments/SC/temp/loc_cache/serlang***
List of divisions and division interfaces, custom HTML blocks added in the built-in design editor: data/%dbkey%/attachments/SC/temp/.cache.***
Compressed JS file of the WYSIWYG text editor: temp/.cache.tiny_mce_***.gz