--- name: "icupgrade" section: "8" platform: "linux" package: "interchange" version: "4.8.3.20020306-1.woody.2" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/icupgrade" --- # icupgrade(8) icupgrade - Interchange Upgrade Guide This document contains, in rough form, notes on upgrading from Minivend 3 to Minivend 4, and Minivend 4 to Interchange. 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.\ **Deprecated Features Previous to Interchange 4** 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}; ``` intechange.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; ``` **Interchange 4 Deprecated Features** The send\_mail routine has been replaced by the Vend::Mail::send routine. if \[item-price\] suddenly turns 0, check PriceField in the catalog.cfg\ **minivend.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/your\_cat\_name.before and etc/your\_cat\_name.after to it only for some catalogs.\ **Access Manager** 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.\ **Database Editing** Update the mv\_metadata.asc file as appropriate.\ **Order Manager** Some things that are needed for the order manager: Add these fields to transactions: ``` 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) ``` Add these fields to transactions: ``` affiliate approx. char(32) campaign approx. char(32) ``` Remove this field from userdb: mv\_credit\_card\_info Add these fields to userdb: inactive *char*(1) credit\_limit char(14) or decimal(12,2) dealer *char*(3) 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 UserDB default scratch "credit_limit dealer" ``` **Affiliates** Add a tab-delimited affiliate table: affiliate name campaigns join\_date url timeout active password You can find a recommended database configuration in foundation/dbconf/\*/affiliate.\*.\ **Page Editor** Add the directories 'templates' and 'backup'. Copy the contents of the Interchange simple/templates to templates.\ **Item Editor** 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 foundation/dbconf/\*/merchandising.\*\ **Preferences Editor (KNAR)** 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\ **Route Editor** 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\ **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'. 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:\ **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: ``` [loop prefix=size list="Small Medium Large"] [loop prefix=color list="Red White Blue"] [color-code]-[size-code]
[/loop]

[/loop] ``` **All frame features removed** Frames are now managed by the user in HTML.\ **Tags removed** 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 \\ etc, tags. Thus the current practice is to use filenames with no extension or perhaps '.txt' to differentiate them from 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 durective 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 \ 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).\ **Directives removed** ``` Act 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 ``` onMap\ **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\ **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: 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** 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.\ **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: ``` [set update_database] [set mv_data_enable]1[/set] [/set] ``` 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] ``` **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.\ **\[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: ``` [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) ``` **\[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: ``` $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.\ **Global subs** Accessing globalsubs from \[perl\] tags is done slightly differently. Minivend 3 method: \[perl sub\] *myfunsub()*; \[/perl\] Minivend 4/IC 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. Minivend 3 compatibility usertags and globalsubs These files were originally distributed with Minivend 4 in the compat/ directory. They replace Minivend 3 functionality that was removed or greatly altered in Minivend 4. body ``` UserTag body PosNuUserTag body Order type extra UserTag body Routine <{Color}->{$var} = []; @{$C->{'Color'}->{$var}} = split /\s+/, $value; return $value; } ``` sub {\ my($scheme, `$extra`) = `@_`;\ my `$r` = '\' unless (int($scheme) \< 16 and int($scheme) \> 1); ``` my %color = qw( mv_bgcolor BGCOLOR mv_textcolor TEXT mv_linkcolor LINK mv_vlinkcolor VLINK mv_alinkcolor ALINK mv_background BACKGROUND ); if (defined $::Values->{mv_resetcolors} and $::Values->{mv_resetcolors}) { delete $::Values->{mv_customcolors}; undef $::Values->{mv_resetcolors}; } if (defined $::Values->{mv_customcolors}) { foreach $var (keys %color) { $r .= qq⎪ $color{$var}="⎪ . $::Values->{$var} . '"' if $::Values->{$var}; } } else { foreach $var (keys %color) { $r .= qq⎪ $color{$var}="⎪ . ${$Vend::Cfg->{Color}->{$var}}[$scheme] . '"' if defined ${$Vend::Cfg->{Color}->{$var}}[$scheme] && ${$Vend::Cfg->{Color}->{$var}}[$scheme] !~ /\bnone\b/; } } $r =~ s#(BACKGROUND="(?!http:))([^/])#$1$Vend::Cfg->{ImageDir}$2#; $r .= " $extra" if defined $extra; $r .= '>'; } EOR ``` AddDirective Mv\_Background color AddDirective Mv\_BgColor color AddDirective Mv\_TextColor color AddDirective Mv\_LinkColor color AddDirective Mv\_AlinkColor color AddDirective Mv\_VlinkColor color ber 2 buttonbar ``` # Returns a buttonbar by UserTag buttonbar Order type UserTag buttonbar PosNumber 1 UserTag buttonbar Interpolate 1 UserTag buttonbar Routine <{'ButtonBars'}-\>\[$buttonbar\]) {\ return `$Vend::Cfg`-\>{'ButtonBars'}-\>\[$buttonbar\];\ }\ else {\ return '';\ } } EOR AddDirective ButtonBars buttonbar umber form\_mail.cfg ``` GlobalSub <{'SendMailProgram'} -t") or last SEND; print Vend::MAIL "To: $to\n", $reply, "Subject: $subject\n", "Errors-To: $Vend::Cfg->{MailOrderTo}\n\n", $body or last SEND; close Vend::MAIL or last SEND; $ok = ($? == 0); } ``` ``` if (!$ok) { logError("Unable to send mail using $Vend::Cfg->{'SendMailProgram'}\n" . "To '$to'\n" . "With subject '$subject'\n" . "With reply-to '$reply'\n" . "And body:\n$body"); } $ok; } EndOfSub ``` OfSub help ``` UserTag help PosNuUserTag help Order name UserTag help Routine <{'Help'}; $var = lc $var; $C->{'Source'}->{'Help'} = $value; @files = get_files($C->{'PageDir'}, split /\s+/, $value); foreach $chunk (@files) { @items = split /\r?\n\r?\n/, $chunk; foreach $item (@items) { ($key,$help) = split /\s*\n/, $item, 2; if(defined $c->{$key}) { $c->{$key} .= $help; } else { $c->{$key} = $help; } ``` ``` } } return $c; } ``` sub {\ my($help) = shift;\ \# Move this to control section?\ if ($::Values-\>{mv\_helpon}) {\ delete `$::Values`-\>{mv\_helpoff};\ undef `$::Values`-\>{mv\_helpon};\ }\ return '' if defined `$::Values`-\>{'mv\_helpoff'};\ if (defined `$Vend::Cfg`-\>{'Help'}{$help}) {\ return `$Vend::Cfg`-\>{'Help'}{$help};\ }\ else {\ return '';\ } } EOR AddDirective Help help ber 1 random\_rotate ``` UserTag random PosNuUserTag random Interpolate 1 UserTag random Routine <{'Random'}}));\ if (defined `$Vend::Cfg`-\>{'Random'}-\>\[$random\]) {\ return `$Vend::Cfg`-\>{'Random'}-\>\[$random\];\ }\ else {\ return '';\ } } EOR UserTag rotate PosNumber 2 UserTag rotate Order ceiling floor UserTag rotate Interpolate 1 UserTag rotate Routine \<\{Rotate};\ my `$ceiling` = `$_`\[0\] ⎪⎪ @{$Vend::Cfg-\>{'Rotate'}} ⎪⎪ return '';\ my `$floor` = `$_`\[1\] ⎪⎪ 1; ``` $ceiling--; $floor--; ``` ``` my $marker = "rotate$floor$ceiling"; ``` ``` if($ceiling < 0 or $floor < 0) { $floor = 0; $ceiling = scalar @{$Vend::Cfg->{'Rotate'}} - 1; logError "Bad ceiling or floor for rotate"; } ``` ``` my $rotate; $rotate = $Vend::Session->{$marker} ⎪⎪ $floor; ``` ``` if($rotate > $ceiling or $rotate < $floor ) { $rotate = $floor; } ``` ``` $Vend::Session->{$marker} = $rotate + 1; return $Vend::Cfg->{'Rotate'}->[$rotate]; } EOR ``` AddDirective Random random AddDirective Rotate random ber 0 AsciiBackend ``` GlobalSubsub AsciiBackend { package Vend::Order; $Vend::Order::override_track_order = \&track_order; sub track_order_backend { my ($order_no,$order_report) = @_; my ($c,$i); my (@backend); ``` ``` @backend = split /\s*,\s*/, $Vend::Cfg->{BackendOrder}; ``` ``` if(@backend and $Vend::Cfg->{AsciiBackend}) { my(@ary); push @ary, $order_no; for(@backend) { push @ary, $::Values->{$_}; } foreach $i (0 .. $#$Vend::Items) { push @ary, $Vend::Items->[$i]{'code'}; push @ary, $Vend::Items->[$i]{'quantity'}; if ($Vend::Cfg->{UseModifier}) { foreach $j (@{$Vend::Cfg->{UseModifier}}) { push @ary, $Vend::Items->[$i]->{$j} } } } logData ($Vend::Cfg->{AsciiBackend}, @ary); } $Vend::Order::override_track_order->($order_no, $order_report); } *track_order = \&Vend::Order::override_track_order; } EOS ``` AddDirective BackendOrder AddDirective AsciiBackend \<\