[MKDoc-dev] ECommmerce system description

[Bruno Postle]

MKDoc-1.6 has a fully functional E-Commerce system for building 
online shops, there is currently no documentation.  This is a basic 
description of the system for anyone who wants to pick it up.

Background
----------

The basic unit of MKDoc is the 'document', a document has a URL that 
ends in '/'.  Documents have 'content' which is a series of 
'components' such as 'text', 'link' etc..

Say I was selling an MKDoc T-shirt, I'd create a document for it 
containing a nice image and maybe some descriptive text.  The 
T-shirt might come in several colours each with their own stock 
reference and price, so for each of these variations I need to add a 
price component - Everything else is configuration of MKDoc 
itself...


Configuration for MKDoc-1.6
===========================

The various files referred-to in this document can be found here:

  http://download.mkdoc.com/misc/mkdoc-1.6-ecommerce-site.2004-10-21.tar.gz

Extra plugins
-------------

This is going to require some extra MKDoc ECommerce plugins for both 
the 'www' and 'users' interfaces, so create a directory to hold the 
new plugin-list configuration files, copy the defaults to start 
with:

  mkdir $SITE_DIR/conf
  cp $MKDOC_DIR/conf/www.conf $SITE_DIR/conf
  cp $MKDOC_DIR/conf/users.conf $SITE_DIR/conf

Then add some more plugins to each list, somewhere near the top 
after flo::plugin::URI_Normalize:

  MKDoc::Session
  flo::plugin::Shop::Order::WorldPay
  flo::plugin::Shop::Basket::View
  flo::plugin::Shop::Basket::Add
  flo::plugin::Shop::Basket::Modify
  flo::plugin::Shop::Basket::Help
  flo::plugin::Shop::Details

Notice that this configuration is for WorldPay, other payment 
gateways will require different 'Order::' plugins.

Configure MKDoc to use these new configuration files by changing the 
$MKD__PLUGIN_LIST setting for each of the 'www' and 'users' 
virtualhosts in $SITE_DIR/httpd.conf:

  SetEnv MKD__PLUGIN_LIST $SITE_DIR/conf/www.conf
  SetEnv MKD__PLUGIN_LIST $SITE_DIR/conf/users.conf

The shopping basket is stored as a cookie for anonymous visitors and 
in the session for logged-in users.  Add some cookie configuration 
to the 'www' virtualhost:

  PerlModule Apache::DBI
  PerlModule MKDoc::Session
  PerlModule MKDoc::ECommerce::Basket
  PerlModule MKDoc::ECommerce::Item
  <perl>
      $::cache_count = sub {
          return MKDoc::ECommerce::Basket::mkdoc_apache_cache_count();
      };

      $::cache_cookie_sent = sub {
          return MKDoc::Session->load();
      };
  </perl>

..and some simpler session configuration for the 'users' 
virtualhost:

  PerlModule Apache::DBI
  PerlModule MKDoc::Session


MKDoc::Apache::Cache
--------------------

MKDoc::Apache_Cache needs to be configured as usual except with 
these differences:

Two extra configuration settings are required in 
$SITE_DIR/httpd/httpd-mkdoc.conf:

  PerlSetEnv  MKDoc_Apache_Cache_NOEXPIRES        "1"
  PerlSetEnv  MKDoc_Apache_Cache_NOCOOKIES        "1"

The cache_policy.txt file needs to look something like this:

  CONDITION cookie_sent   defined $::cache_cookie_sent->()
  CONDITION is_user       $ENV{MKD__PLUGIN_LIST} =~ /users\.conf$/
  CONDITION is_document   $ENV{PATH_INFO} =~ /\/$/
  CONDITION is_sitemap    $ENV{PATH_INFO} =~ /\.sitemap.html/
  CONDITION always_true   "true"

  RET_VALUE zero          "0"
  RET_VALUE four_hours    4*3600
  RET_VALUE document_id   $::cache_count->() . ':' . $ENV{PATH_INFO}
  RET_VALUE no_query      $ENV{PATH_INFO} || '_'
  RET_VALUE noop          "noop"

  RULE zero noop                  WHEN is_user
  RULE four_hours document_id     WHEN is_document cookie_sent
  RULE four_hours no_query        WHEN is_sitemap
  RULE zero noop                  WHEN always_true

Make sure that the deprecated flo::plugin::Cache::Reader and 
flo::plugin::Cache::Writer are not enabled in the www.conf file.


Pricing and payment configuration
---------------------------------

Add these lines to $SITE_DIR/httpd/httpd-env.conf:

  SetEnv      ECOMMERCE_INSTID          "12345"
  SetEnv      ECOMMERCE_CURRENCY        "GBP"
  SetEnv      ECOMMERCE_SECRET          "mysecret"
  SetEnv      ECOMMERCE_BILLING_RULES   "$SITE_DIR/conf/ecommerce.list.conf"
  SetEnv      MKD__ECOMMERCE_STOCK_URI  "http://stock.example.com/cgi-bin/query.cgi"

The billing rules are expressed as an MKDoc::Control_List file, 
there is a basic one supplied in the tarball, copy that into place:

  cp example.com/conf/ecommerce.list.conf $SITE_DIR/conf

Notice that MKD__ECOMMERCE_STOCK_URI refers to a stock control cgi 
script which can be queried for stock status, an example server is 
included in the tarball.  Note that if you don't set up a stock 
server, all your items will appear to be out of stock.


Custom Templates
----------------

Custom templates are required, copy a set representing a basic shop 
unit:

 cp -a example.com/resources/templates/* $SITE_DIR/resources/templates/

Select appropriate templates for items, category pages etc..  
otherwise the default plain templates will be used which will not 
display price components or summaries.


Custom CSS
----------

Some custom skinning is required, copy the basic one supplied in the 
tarball:

  cp -a example.com/resources/skin/* $SITE_DIR/resources/skin/

..and change the matching Aliases for each of the virtualhosts in 
$SITE_DIR/httpd/httpd.conf to suit:

  Alias /.static/css    /var/www/mkdoc/example.com/resources/skin

That's it, don't forget to restart apache.  Any questions, 
corrections or updates should be directed to the mkdoc-dev mailing 
list.


Configuration for MKDoc-1.8
===========================

In the current development version of MKDOc, the shop functionality 
has been removed from the MKDoc CMS, and put into the 
MKDoc-ECommerce CVS module, this currently needs reintegration.

-- 
Bruno