Copyright © 2003, 2004, 2005 Interchange Development Group
Copyright © 2002 Red Hat, Inc.
This documentation is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Abstract
The purpose of this document is to provide general notes for upgrading from Minivend 3 to Minivend 4, and from Minivend 4 to Interchange.
By saying "Interchange", we primarily mean the early releases, such as 4.6 or 4.8. To be sure you did not miss anything while upgrading to Interchange 5.0 and beyond, please review WHATSNEW entries.
This Guide will be slowly losing on relevance, and users running Interchange 5.0 or later should monitor WHATSNEW entries for upgrade information.
Table of Contents
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.
This section needs some serious work.
interchange.PL 308,313
if($path =~ s:/(.*)::) {
$cart = $1;
if($cart =~ s:/(.*)::) {
$page = $1;
}
}
interchange.PL 321,323
$CGI::values{mv_nextpage} = $CGI::values{mv_orderpage}
|| find_special_page('order')
if ! $CGI::values{mv_nextpage};
interchange.PL 493
HTML::Entities::decode($value) if $decode;
interchange.PL 854,855
$CGI::values{mv_nextpage} = $CGI::values{mv_orderpage}
if $CGI::values{mv_orderpage};
interchange.PL 1552,1579
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 }
);
}
lib/Vend/Interpolate.pm 2808
list_compat($opt->{prefix}, \$text);
lib/Vend/Interpolate.pm 3538
list_compat($opt->{prefix}, \$text);
lib/Vend/Interpolate.pm 3874
list_compat($opt->{prefix}, \$page);
lib/Vend/Interpolate.pm 3270,3271
$text =~ /^\s*\[sort\s+.*/si
and $opt->{sort} = find_sort(\$text);
lib/Vend/Order.pm 867,868
$body = readin($::Values->{mv_order_report})
if $::Values->{mv_order_report};
lib/Vend/Order.pm 1030
$::Values->{"mv_error_$var"} = $message;
if item-price suddenly starts returning 0,
check PriceField in the catalog.cfg
Remove references to MiniMate.
Add this line to minivend.cfg:
#include lib/UI/ui.cfg
Make sure the files catalog_before.cfg and
catalog_after.cfg are there, or
add their contents to
etc/
and your_cat_name.beforeetc/
only for some catalogs.
your_cat_name.after
You need to get the minimate.asc file renamed
to access.asc and add the following fields to
the first line:
groups last_login name password
Remove these catalog.cfg lines:
Variable MINIMATE_META mv_metadata Variable MINIMATE_TABLE minimate Database minimate minimate.asc TAB
Add this one:
Database affiliate affiliate.txt TAB
Authentication for admin users is now done from a separate table than customers, and passwords are encrypted.
Some things that are needed for the order manager:
Add these fields to transactions:
affiliate approx. char(32)
Add these fields to transactions:
affiliate approx. char(32)
Remove this field from userdb:
mv_credit_card_info
Add these fields to userdb:
inactive char(1)
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:
## Don't want people setting their credit_limit directly
Add a tab-delimited affiliate table:
affiliate name campaigns join_date url timeout active password
You can find a recommended database configuration in
standard/dbconf/*/affiliate.*.
Add the directories
templates/ and
backup/.
Copy the contents of the
Interchange simple/templates/ to
templates/.
Add a merchandising table with the following fields:
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
Index the fields with char(*) types. You can find the
recommended database configuration in
standard/dbconf/*/merchandising.*
Create the tab-delimited file variable.txt with
these fields:
code Variable pref_group
Add this as the first line of catalog.cfg:
VariableDatabase variable
Create the file route.txt with these fields:
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
Add this line in catalog.cfg:
RouteDatabase route
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.
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:
MV3 used a different scheme for creating nested loop lists:
[loop with="-a"* arg="item item item" search="se=whatever"]
which allowed you to refer to the nested values with a [loop-code-a] construct. In Minivend 4, the form is:
[loop prefix=size list="Small Medium Large"]
[loop prefix=color list="Red White Blue"]
[color-code]-[size-code]<BR>
[/loop]
<P>
[/loop]
Frames are now managed by the user in HTML.
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
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
Variable HEADER <pages/header Variable FOOTER <pages/footer Variable COPYRIGHT <pages/copyright
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 complete HTML
pages.
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.
rotate
Replace with [ad ...]. See [random] above.
help
No replacement. Use data functions or variables.
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.
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].
last_page
No replacement - this can be emulated by setting a scratch variable on one page, then using it to build the return URL.
item-link
No replacement, just use [page [item-code]].
loop-link
No replacement, just use [page [loop-code]].
sql-link
No replacement, just use [page [sql-code]].
accessories
Replace with normal data functions.
Compatibility routines
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).
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
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
Search tags must now be surrounded by search_region tag.
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:
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.:
[search-region]
[search-list]
your search iteration stuff, [item-code], etc.
[/search-list]
[more-list]
[more]
[/more-list]
[/search-region]
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.
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:
[set update_database] [set mv_data_enable]1[/set] [/set] <INPUT TYPE=hidden NAME=mv_click VALUE=update_database>
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:
[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]
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.
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:
[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)
You must always surround search-list with
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:
$Safe{values} --> $Values
$Safe{cgi} --> $CGI
$Safe{carts} --> $Carts
$Safe{items} --> $Items
$Safe{config} --> $Config
$Safe{scratch} --> $Scratch
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.
Accessing globalsubs from perl tags is done slightly differently.
Minivend 3 method:
[perl sub] myfunsub(); [/perl]
Minivend 4/Interchange method:
[perl subs=1] myfunsub(); [/perl]
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.