====== CS-Cart ======

===== Directory Structure =====

Most of the info on the CS-Cart website and forums about where certain files are located is wrong, because they have been changing the directory structure in every version.

This information is for version 4.1.2.

Themes repository. Originals are kept here. (I think.) When an addon is installed, its template files are copied from the repository area into the design area. When it is uninstalled, they are deleted from the design area.

  * var
     * themes_reopository
        * basic

Design directory. These are the templates that are actually used.

  * design
     * themes
        * basic

===== Execution Path =====

index
init
config setup

fn_dispatch (fn.control.php)
  * determines all controllers that need to run, including addons and pre- and post-hooks
  * calls fn_run_controller() for each
  * calls $view->display(Registry::get('runtime.root_template')) (where root_templates=index.tpl)
    * since all the controllers have run at this time, all smarty variable assignments should be ready

==== Form Submission ====

Javascript event ce.formpost_[form_name] is triggered after validation and before form is posted. Returning false will cancel the submission.

===== User Interface =====

==== Cache ====

Clear the cache in v4 by appending ?ctpl&cc to the admin.php URI.

==== Template Hooks ====

Occasionally the templates contain hooks where one can prepend, append, or replace templates.

==== Template Override ====

The hooks are generally only found where the developers needed to put them to develop their built-in addons. More often, you'll find you need to replace an entire template. You won't easily discover this method by looking at the built-in addons, because the developers have added hooks so that they don't need to override template files.

==== Template Engine ====

'view' entry in the registry (Registry::get('view')) is an instance of SmartyCore (setup in fn.init.php).

==== Template Javascript ====

For templates that are added to the page via ajax calls, embedded scripts are not executed. However, a 'ce.commoninit' event is triggered, which scripts can subscribe to.

<code>
$.ceEvent('on', 'ce.commoninit', function(context) {
  // code here
});
</code>

===== Code / Addons =====

==== Database ====

table cscart_payment_processors
<code>
  processor_id        int
  processor           string
  processor_script    string
  processor_template  string
  admin_template      string
  callback            char default 'N' -- not used
  type                char default 'P'
</code>

==== Codes ====

<code>
Areas:
  'C' client
  'A' admin

notifications:
  'C' customer
  'A' department
  'V' vendor
</code>

==== Front End / Javascript ====

<code>
var/themes_repository/basic/templates/common/scripts.tpl
  includes the core javascript libraries
  executes $.runCart('C'), defined in js/tygh/core.js

js/tygh/core.js
  defines the Tygh object
  Tygh is generally passed as _
  assigns document to _.doc
  extends jquery
  $.runCart():
    attaches click, mousedown, keyup, keydown, and change events to $(_.doc)
</code>

==== Addon Development Notes ====

For each parameter in the callback url, verify that it is correct for the stored order.

<code>
// paypal.php
$account_type = fn_validate_email($processor_data['processor_params']['account']) ? 'receiver_email' : 'receiver_id';
if ($_REQUEST[$account_type] != $processor_data['processor_params']['account']) {
    $pp_response['order_status'] = $paypal_statuses['denied'];
    $pp_response['reason_text'] = __('paypal_security_error');
    fn_finish_payment($_REQUEST['order_id'], $pp_response);
    exit;
}
</code>

==== Payment Processing Integration Notes ====

payment_processors table is queried from functions (incomplete list):
<code>
  app/functions/fn.cart.php fn_get_payment_methods
  app/functions/fn.cart.php fn_get_checkout_payment_buttons
    creates empty array $checkout_buttons
    "include"s each payment processor's processor_script
    returns $checkout_buttons
    amazon and google payment methods populate $checkout_buttons
</code>

=== definitions ===

BOOTSTRAP

PAYMENT_NOTIFICATION

=== variables ===

$_payment_id

$processor_data['processor_params']

$cart

$checkout_buttons[$_payment_id]

=== main payment functions ===

fn_cart_is_empty(cart)

fn_finish_payment(order_id, pp_response)

pp_response - dictionary
pp_response['order_status'] - 'P' for placed, 'F' for failed (?)
pp_response['reason_text'] - reason for failure

fn_order_placement_routines

=== other payment functions ===

fn_check_payment_script

fn_change_order_status
  'N' canceled?
  'O' open
  'I' canceled?
  'F'

fn_get_order_info

fn_get_processor_data

fn_get_payment_method_data

=== other functions ===

fn_flush()

fn_set_notification()

fn_url()

fn_format_price()

===== Resources =====

http://www.hungryweb.net/cs-cart-tutorials/how-to-modify-cs-cart-checkout-step-1-for-a-better-user-experience.html

http://forum.cs-cart.com/topic/34038-trying-to-override-a-tpl-file-using-my-changes-add-on/page__view__findpost__p__173233