icupgrade.sdf

!init OPT_LOOK="icdevgroup"; OPT_STYLE="manual"
# $Id: icupgrade.sdf,v 1.23 2004-05-05 15:22:31 jon Exp $

!define DOC_NAME "Interchange Upgrade Guide"
!define DOC_TYPE ""
!define DOC_CODE "icupgrade"
!define DOC_VERSION substr('$Revision: 1.23 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://www.icdevgroup.org/doc/icupgrade.html"
!define DOC_OWNER "2002-2004 Interchange Development Group, 1996-2002 Red Hat, Inc."
!build_title

H1:Introduction

This document contains, in rough form, notes on upgrading from Minivend 3 to Minivend 4, and Minivend 4 to Interchange.


H1:Interchange 4.8 Deprecated Features

This document describes features of Interchange 4.8 that have been deprecated. Any use of these features should be discontinued. In most cases we have provided an alternative mechanism to accomplish the same results. These deprecated features may be removed at some point in the future. You should change to the new mechanism to avoid breakage.

H2:Deprecated Features Previous to Interchange 4

N:This section needs some serious work.

=item cart/page from path

interchange.PL 308,313

>        if($path =~ s:/(.*)::) {
>                $cart = $1;
>                if($cart =~ s:/(.*)::) {
>                        $page = $1;
>                }
>        }

=item mv_orderpage

interchange.PL 321,323

>        $CGI::values{mv_nextpage} = $CGI::values{mv_orderpage}
>                                   || find_special_page('order')
>                if ! $CGI::values{mv_nextpage};

=item $decode

interchange.PL 493

>      HTML::Entities::decode($value) if $decode;

=item mv_orderpage

interchange.PL 854,855

!block example
      $CGI::values{mv_nextpage} = $CGI::values{mv_orderpage}
                                    if $CGI::values{mv_orderpage};
!endblock

=item ROUTINES and LANG

interchange.PL 1552,1579

!block example
   ROUTINES: {
       last ROUTINES
            unless index($Vend::FinalPath, '/process/') == 0;
       while (
           $Vend::FinalPath =~
              s{/process/(locale|language|currency)/([^/]*)/}
               {/process/}
          )
       {
               $::Scratch->{"mv_$1"} = $2;
       }
       $Vend::FinalPath =~ s:/process/page/:/:;
   }
   my $locale;
   if($locale = $::Scratch->{mv_language}) {
           $Global::Variable->{LANG}
                   = $::Variable->{LANG} = $locale;
   }

   if ($Vend::Cfg->{Locale}
   		and $locale = $::Scratch->{mv_locale}
		and defined $Vend::Cfg->{Locale_repository}->{$locale}
       )
   {
           $Global::Variable->{LANG}
                           = $::Variable->{LANG}
                           = $::Scratch->{mv_language}
                           = $locale
                    if ! $::Scratch->{mv_language};
           Vend::Util::setlocale(  $locale,
                                   ($::Scratch->{mv_currency} || undef),
                                   { persist => 1 }
								);
   }
!endblock

=item list_compat

lib/Vend/Interpolate.pm 2808

!block example
         list_compat($opt->{prefix}, \$text);
!endblock
  
lib/Vend/Interpolate.pm 3538

>        list_compat($opt->{prefix}, \$text);

lib/Vend/Interpolate.pm 3874

>        list_compat($opt->{prefix}, \$page);

=item find_sort

lib/Vend/Interpolate.pm 3270,3271

>        $text =~ /^\s*\[sort\s+.*/si
>                and $opt->{sort} = find_sort(\$text);

=item mv_order_report

lib/Vend/Order.pm 867,868

>    $body = readin($::Values->{mv_order_report})
>                if $::Values->{mv_order_report};

=item mv_error_$var

lib/Vend/Order.pm 1030

=back

>                        $::Values->{"mv_error_$var"} = $message;

H2:Interchange 4 Deprecated Features

=item Vend::Util::send_mail Vend::Order::send_mail send_mail

The send_mail routine has been replaced by the Vend::Mail::send routine.

=back



H1:Upgrading from Minivend 4.0 to Interchange 4.6

if [item-price] suddenly turns 0, check PriceField in the catalog.cfg



H2:minivend.cfg

*Remove references to MiniMate.

*Add this line to minivend.cfg:

.#include lib/UI/ui.cfg

N:Make sure the files catalog_before.cfg and catalog_after.cfg are there, or add their contents to etc/your_cat_name.before and etc/your_cat_name.after to it only for some catalogs.

H2:Access Manager

You need to get the minimate.asc file renamed to access.asc and add the following fields to the first line:

!block example
groups
last_login
name
password
!endblock

Remove these catalog.cfg lines:

!block example
        Variable            MINIMATE_META   mv_metadata
        Variable            MINIMATE_TABLE  minimate
        Database            minimate        minimate.asc      TAB
!endblock

Add this one:
!block example
        Database            affiliate    affiliate.txt     TAB
!endblock

Authentication for admin users is now done from a separate table than customers, and passwords are encrypted.

H2:Database Editing

Update the mv_metadata.asc file as appropriate.

H2:Order Manager

Some things that are needed for the order manager:

*Add these fields to transactions:
!block example
    affiliate  approx. char(32)
    archived   char(1)
    campaign   approx. char(32)
    comments   blob/text
    complete   char(1)
    deleted    char(1)
    order_wday char(10)
    order_ymd  char(8)
    po_number  approx. char(32)
!endblock

*Add these fields to transactions:
!block example
    affiliate  approx. char(32)
    campaign   approx. char(32)
!endblock

*Remove this field from userdb:
E:mv_credit_card_info

*Add these fields to userdb:
!block example
inactive     char(1)
credit_limit char(14) or decimal(12,2)
dealer       char(3)
!endblock

*Create the directory 'logs'.
*Create the directory 'orders' if it doesn't already exist.
*Update your order routes to those in the Interchange distribution. Note that the route log_entry is necessary if you want to enter orders from the Interchange UI.
*Update the etc/log_transaction file.
*Add the etc/log_entry file.
*Add this to catalog.cfg:
!block example
    ## Don't want people setting their credit_limit directly
    UserDB default scratch "credit_limit dealer"
!endblock

H2:Affiliates

Add a tab-delimited affiliate table:

E:affiliate name    campaigns   join_date   url timeout active  password

You can find a recommended database configuration in foundation/dbconf/*/affiliate.*.

H2:Page Editor

Add the directories 'templates' and 'backup'. Copy the contents of the Interchange simple/templates to templates.

H2:Item Editor

Add a merchandising table with the following fields:

!block example
Database  merchandising  merchandising.txt __SQLDSN__
Database  merchandising  DEFAULT_TYPE text

sku                 char(32)
featured            char(32)
banner_text
banner_image
blurb_begin
blurb_end
timed_promotion     char(16)
start_date          char(24)
finish_date         char(24)
upsell_to
cross_sell
cross_category      char(64)
others_bought
times_ordered
!endblock

Index the fields with char(*) types. You can find the recommended database configuration in foundation/dbconf/*/merchandising.*

H2:Preferences Editor (KNAR)

Create the tab-delimited file variable.txt with these fields:

E:code  Variable  pref_group

Add this as the *first* line of catalog.cfg:

E:VariableDatabase variable

H2:Route Editor

Create the file route.txt with these fields:

!block example
        code
        report
        receipt
        encrypt_program
        encrypt
        pgp_key
        pgp_cc_key
        cyber_mode
        credit_card
        profile
        inline_profile
        email
        attach
        counter
        increment
        continue
        partial
        supplant
        track
        errors_to
!endblock

Add this line in catalog.cfg:

E:RouteDatabase route

H2:Transactions database

The back office UI should work fine for editing database tables. Obviously the things which are specific to the order transaction setup will break unless you have the right fields, but even these can be controlled by configuring the UI.

Add a new field to transaction.txt called 'archived'.



H1:Upgrading from Minivend 3 to Minivend 4

There were big changes from Minivend 3 to Minivend 4, some of which were incompatible.

Many things were removed as redundant, deprecated, or just plain crufty:


H2:Nested [loop]s

MV3 used a different scheme for creating nested loop lists:

\[loop with="-a"* arg="item item item" search="se=whatever"]

allowed you to refer to the nested values with a [loop-code-a] construct. In Minivend 4, the form is:

!block example
    [loop prefix=size list="Small Medium Large"]
        [loop prefix=color list="Red White Blue"]
            [color-code]-[size-code]<BR>
        [/loop]
        <P>
    [/loop]
!endblock
          
H2:All frame features removed

Frames are now managed by the user in HTML.

H2:Tags removed

H3:buttonbar

Replace with Variable defined in catalog.cfg. buttonbar was previously used as an SSI-like command for catalog-wide standardized features like navigation bars. In the 3.x catalog.cfg the ButtonBars parameter defines a list of html snippets, like

E:ButtonBars header.html footer.html copyright.html

So [buttonbar 0] substitutes 'header.html', [buttonbar 1] substitutes 'footer.html', etc.

In 4.x catalog.cfg, define variables, like

!block example
Variable HEADER    <pages/header
Variable FOOTER    <pages/footer
Variable COPYRIGHT <pages/copyright
!endblock

Then replace all occurrences of [buttonbar 0] with __HEADER__, [buttonbar 1] with __FOOTER__, etc.

Note that the old header.html, footer.html, etc. contained html code, but were not actually html pages with <html><body> etc, tags. Thus the current practice is to use filenames with no extension or perhaps '.txt' to differentiate them from pages.

H3:random

Replace with [ad random=1] or custom code. See the [ad] tag docs. Random and rotate were used to place random or rotating regions on pages, such as banner ads.

The Random directive in catalog.cfg defines the numbered HTML snippet files, similar to buttonbars above.

H3:rotate

Replace with [ad ...]. See [random] above.

H3:help

No replacement. Use data functions or variables.

H3:body

Replace with templates. Again the body tag [body 1] etc. defines numbered body definitions that could be applied site-wide. However, in this case minivend actually built up the <body ....> substitution using the Mv_* directives in catalog.cfg.

H3:finish_order

\[finish_order] was a conditional tag; if the basket contained anything a 'checkout' graphic would be displayed. No replacement; use [if items]Message[/if].

H3:last_page

No replacement - this can be emulated by setting a scratch variable on one page, then using it to build the return URL.

H3:item-link

No replacement, just use [page [item-code]].

H3:loop-link

No replacement, just use [page [loop-code]].

H3:sql-link

No replacement, just use [page [sql-code]].

H3:accessories

Replace with normal data functions.

H3:Compatibility routines

N:Compatibility routines for many popular tags like [random], [rotate], etc. are provided in the appendix of this document. To use one, copy it to a file and put it in your usertag directory. (Tags in the usertag directory are read in by interchange.cfg by default).


H2:Directives removed

!block example
    ActionMap
    AdminDatabase
    AdminPage
    AsciiBackend
    BackendOrder
    ButtonBars
    CheckoutFrame
    CheckoutPage
    CollectData
    DataDir
    Delimiter
    DescriptionTrim
    FieldDelimiter
    FrameFlyPage
    FrameLinkDir
    FrameOrderPage
    FrameSearchPage
    ItemLinkDir
    ItemLinkValue
    MsqlDB
    MsqlProducts
    Mv_AlinkColor
    Mv_Background
    Mv_BgColor
    Mv_LinkColor
    Mv_TextColor
    Mv_VlinkColor
    NewReport
    NewTags
    OldShipping
    OrderFrame
    PageCache
    PriceDatabase
    Random
    ReceiptPage
    RecordDelimiter
    ReportIgnore
    Rotate
    SearchFrame
    SearchOverMsg
    SecureOrderMsg
    SpecialFile
    SubArgs
    Tracking
!endblock


H2:Minor operations removed

* auto-substitution of mp= on [loop search=profile], [search-region arg=profile]
* [tag scan]...
* [tag sql]...

Many of these are related to one of:

* Removal of frames logic
* Removed tags
* Obsolete methods
* Old routines for 2.0x compatibility

H2:Search lists

Search tags must now be surrounded by [search-region] [/search-region]. This is because multiple searches can be done in a page, with multiple [more-list] entries, multiple [no-match] areas, etc. It was not really possible to avoid this and add the feature.

To find all files containing the search list, do:

E:find pages -type f | xargs grep -l '\[search.list'

That will yield a set of files that need to be updated. You should surround all parts of the search area, i.e.:

!block example
    [search-region]

    [search-list]
        your search iteration stuff, [item-code], etc.
    [/search-list]

    [more-list]
        [more]
    [/more-list]

    [/search-region]
!endblock

H2:Search conditionals

Search conditionals should now say [if-item-field field] [/if-item-field] and [if-item-data table column] [/if-item-data]. This allows mixing and nesting of lists. You may find that the old works in some situations, but it will not work in all situations.

H2:Form data updates

Added Scratch variable mv_data_enable to gate the update_data function. You must set it before doing a form update. Prior to this it was possible to update a SQL database willy-nilly.

A quick fix like this will allow the update on a single page:

!block example
    [set update_database]
    [set mv_data_enable]1[/set]
    [/set]
    <INPUT TYPE=hidden NAME=mv_click VALUE=update_database>
!endblock

It will ensure at least that the user loads one form from you for each update. For best security, gate with a userdb entry like this:

!block example
    [set update_database]
    [if type=data term="userdb::trusted::[data session username]"]
        [set mv_data_enable]1[/set]
    [else]
        [set mv_data_enable]0[/set]
    [/else]
    [/if]
    [/set]
!endblock


H2:Checkout changes

Minivend 4 uses in-page error-flagging on the checkout page. Simplest way to convert is probably to use the checkout.html from the simple demo as a start, and move in any customization from the existing site's catalog.html (headers, footers, logos, etc.) A line-by-line comparison of the data fields in the checkout page should be performed, adding any custom fields as needed. Custom error checking in etc/order.profiles may have to be re-worked, or can be added into checkout.html using the in-page order profile capability. (Note that etc/order.profiles is called etc/profiles.order in newly-built Interchange catalogs.)

Remember to update receipt.html and report/report.html with any custom fields, as well.


H2:[if-field] etc.

The least-compatible things in the tag area are [if-field] (needs to be [if-PREFIX-field], where prefix might be item|loop by default depending on the tag. Likewise:

!block example
    [if-data table col]  --> [if-PREFIX-data table col]
    [on-change mark]     --> [PREFIX-change mark]
    [if-param param]     --> [if-PREFIX-param param]
    [PREFIX-param N]     --> [PREFIX-pos N] (where N is a digit)
!endblock

H2:[search-list]

You must always surround [search-list] with [search-region] [/search-region].

Embedded Perl changes quite a bit. While there are the $Safe{values} and other variable settings, they are automatically shared (no arg="values") and move to:

!block example
    $Safe{values}   -->  $Values
    $Safe{cgi}      -->  $CGI
    $Safe{carts}    -->  $Carts
    $Safe{items}    -->  $Items
    $Safe{config}   -->  $Config
    $Safe{scratch}  -->  $Scratch
!endblock

There are a number of other objects, see the docs.

Most other issues have more to do with the catalog skeleton (i.e. simple
or barry or basic or art) than they do the core. For instance, the
"basic" catalog produced for MV3 ran unchanged except for the issues
discussed above.

H2:Global subs

Accessing globalsubs from [perl] tags is done slightly differently.

Minivend 3 method:

!block example
[perl sub]
myfunsub();
[/perl]
!endblock

Minivend 4/IC method:

!block example
[perl subs=1]
myfunsub();
[/perl]
!endblock

If you do this wrong, you'll get an error that looks like this:

> 115.202.115.237 H8gbq6oK:115.202.115.237 - \
>  [28/February/2001:18:58:50 -0500] testcat /cgi-bin/testcat.cgi \
>  Safe: Undefined subroutine &MVSAFE::myfunsub called at (eval 283) line 2.

H1: History of Interchange

Interchange is a descendent of Vend, an e-commerce solution originally developed by Andrew Wilcox in early 1995. Mike Heins took the first publicly-released version, Vend 0.2, and added searching and DBM catalog storage to create MiniVend. Mike released MiniVend 0.2m7 on December 28, 1995. Subsequent versions of MiniVend took parts from Vend 0.3, especially the vlink and Server.pm modules, which were adapted to run with MiniVend. In the four years that followed, Mike Heins expanded and enhanced MiniVend, creating a powerful and versatile e-commerce development platform. MiniVend grew to support thousands of businesses and their e-commerce sites, and sites running on MiniVend versions 3 and 4 are still common today.

Separately, an experienced e-commerce development team founded Akopia. Their goal was to create a sophisticated open source e-commerce platform that was both feature-rich and easy to use. Their product, Tallyman, was intuitive, and had great content-management features, but lacked many of MiniVend's capabilities.

Akopia acquired MiniVend in June 2000. Mike Heins and the Tallyman developers combined MiniVend 4 with Tallyman's features to create Interchange. Interchange replaces both MiniVend and Tallyman. In order to preserve compatibility, the name "minivend" and prefixes like "mv_" and "MVC_" will still appear in source code and configuration files. Interchange's first stable release was version 4.6.

In January 2001, Red Hat acquired Akopia and created its new E-Business Solutions Division. Red Hat sponsored the development of Interchange 4.8 and the Red Hat E-Commerce Suite.

In mid-2002, Red Hat decided to stop supporting Interchange development, and a group of individuals formed the Interchange Development Group to coordinate Interchange development independent of any company or person. The first stable release by the new independent group of developers was Interchange 5.0.

Interchange continues to advance, the user community is growing, and new Interchange sites are frequently deployed.

Line:

N:Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002 Red Hat, Inc. Freely redistributable under terms of the GNU General Public License.