Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

This commit was manufactured by cvs2svn to create tag 'REL_4_7_2'.

  • Loading branch information...
commit ad13c7780e63194edc80d2f350e74fc7f398f525 3 parents d8a0553 + 62dbb92 + 8baec5d
cvs2svn authored
View
22 MANIFEST
@@ -353,6 +353,7 @@ dist/foundation/templates/components/best_vertical
dist/foundation/templates/components/cart
dist/foundation/templates/components/cart_display
dist/foundation/templates/components/cart_tiny
+dist/foundation/templates/components/category_horizontal
dist/foundation/templates/components/category_vertical
dist/foundation/templates/components/cross_horizontal
dist/foundation/templates/components/cross_vertical
@@ -416,10 +417,17 @@ dist/foundation/templates/sampledata/reports/download/66548ch.pdf
dist/foundation/templates/sampledata/reports/download/73358ee.pdf
dist/foundation/templates/sampledata/reports/download/83491vp.pdf
dist/foundation/templates/sampledata/reports/download/90773sh.pdf
+dist/foundation/templates/sampledata/reports/products/affiliate.txt
dist/foundation/templates/sampledata/reports/products/area.txt
dist/foundation/templates/sampledata/reports/products/cat.txt
+dist/foundation/templates/sampledata/reports/products/inventory.txt
+dist/foundation/templates/sampledata/reports/products/merchandising.txt
dist/foundation/templates/sampledata/reports/products/mv_metadata.asc
+dist/foundation/templates/sampledata/reports/products/options.txt
+dist/foundation/templates/sampledata/reports/products/orderline.txt
+dist/foundation/templates/sampledata/reports/products/pricing.txt
dist/foundation/templates/sampledata/reports/products/products.txt
+dist/foundation/templates/sampledata/reports/products/transactions.txt
dist/foundation/templates/sampledata/reports/products/userdb.txt
dist/foundation/templates/sampledata/tools/etc/after.cfg
dist/foundation/templates/sampledata/tools/etc/before.cfg
@@ -862,22 +870,12 @@ lib/Vend/TextSearch.pm
lib/Vend/Track.pm
lib/Vend/UserDB.pm
lib/Vend/Util.pm
-pdf/icbackoffice.pdf
-pdf/iccattut.pdf
-pdf/icconfig.pdf
-pdf/icdatabase.pdf
-pdf/icinstall.pdf
-pdf/icintro.pdf
-pdf/ictags.pdf
-pdf/ictemplates.pdf
-pdf/icupgrade.pdf
perl/Interchange.pm
-pod/icbackoffice.pod
+pod/icadvanced.pod
pod/iccattut.pod
pod/icconfig.pod
pod/icdatabase.pod
-pod/icinstall.pod
-pod/icintro.pod
+pod/icfoundation.pod
pod/ictags.pod
pod/ictemplates.pod
pod/icupgrade.pod
View
5 Makefile.PL
@@ -736,12 +736,11 @@ GetOptions(\%optctl, @options)
WriteMakefile(
NAME => "Interchange",
MAN3PODS => {
- 'pod/icbackoffice.pod' => 'blib/man3/icbackoffice.8',
+ 'pod/icadvanced.pod' => 'blib/man3/icadvanced.8',
'pod/iccattut.pod' => 'blib/man3/iccattut.8',
'pod/icconfig.pod' => 'blib/man3/icconfig.8',
'pod/icdatabase.pod' => 'blib/man3/icdatabase.8',
- 'pod/icinstall.pod' => 'blib/man3/icinstall.8',
- 'pod/icintro.pod' => 'blib/man3/icintro.8',
+ 'pod/icfoundation.pod' => 'blib/man3/icfoundation.8',
'pod/ictags.pod' => 'blib/man3/ictags.8',
'pod/ictemplates.pod' => 'blib/man3/ictemplates.8',
'pod/icupgrade.pod' => 'blib/man3/icupgrade.8',
View
45 README
@@ -11,12 +11,12 @@ Copyright 1995-96 by Andrew M. Wilcox
See the file LICENSE for redistribution terms.
-This program is completely unsupported, without warranty of any kind. We
-are interested in problems, suggestions, or comments, but do not have
-time to offer free individual support in most cases. Our professional
-services group offers paid consulting services, which are detailed at:
+This program is offered without warranty of any kind. We are interested
+in problems, suggestions, or comments, but do not offer free individual
+support in most cases. Our professional services group offers paid
+consulting services, which are detailed at:
-http://www.akopia.com/
+http://www.redhat.com/ecommerce
-----------------------------------------------------------------------------
@@ -28,31 +28,28 @@ dynamic content presentation; content management; internationalization
and localization support; real-time tax and shipping hooks; reporting;
and web-based administration.
-Interchange absolutely REQUIRES Perl 5.005 or Perl 5.6 on a Unix-like
-operating system.
+Interchange absolutely REQUIRES Perl 5.005 or Perl 5.6 or later on a
+Unix-like operating system.
-----------------------------------------------------------------------------
More information is in the following files and directories:
-pdf/ Documentation viewable with xpdf, gv, or Adobe Acrobat Reader.
-
-pod/ Documentation viewable with perldoc.
-
-README.cvs How to access the CVS repository to track the development of
- Interchange as it happens.
+doc/ Documentation.
README.rpm Notes on using Interchange when installed from RPM packages.
README.debian Notes on using Interchange when installed from Debian packages.
-WHATSNEW Change information for all versions in this version family.
+README.cvs How to access the CVS repository to track ongoing development.
+
+WHATSNEW Changes per version for this version family.
-----------------------------------------------------------------------------
Major files/directories in the distribution:
-Makefile.PL The installation script.
+Makefile.PL Script to create a Makefile, used for installation.
dist/ The distribution files, exclusive of executable
files and modules. Includes:
@@ -101,7 +98,7 @@ To install the demo, go to the directory where you installed Interchange
for root installations, or /usr/lib/interchange for RPM installations)
and run:
- bin/makecat
+bin/makecat
Follow the prompts and after restarting the Interchange server you
should be able to access the demo catalog.
@@ -116,12 +113,12 @@ Visit http://demo.akopia.com/ to see a live demo on our servers.
D O C U M E N T A T I O N
-The included documentation is in man, POD, and PDF formats. Extended
+The included documentation is in man(1), POD, and HTML formats. Extended
documentation is available at:
http://developer.akopia.com/
-which includes user-annotated documentation, HTML versions of the manual,
+which includes user-annotated documentation, the manual in other formats,
and a user-contributed code library.
-----------------------------------------------------------------------------
@@ -130,19 +127,9 @@ and a user-contributed code library.
Interchange is regularly tested on Linux, FreeBSD, and Solaris. It
has also been used on OpenBSD, Digital UNIX/Tru64, SCO, AIX, and other
-Unix ports. It should work on any Unix with Perl 5.005 or higher and
+Unix variants. It should work on any Unix with Perl 5.005 or higher and
the necessary Perl modules.
-----------------------------------------------------------------------------
- K N O W N P R O B L E M S
-
-Apache with suEXEC:
-
-vlink/UNIX socket mode will not work well unless you do the install as
-a normal user. If you are going to support multiple users, you must use
-tlink/INET mode.
-
------------------------------------------------------------------------------
-
(end)
View
11 SPECS/interchange.spec
@@ -21,7 +21,7 @@ Vendor: Red Hat, Inc.
Copyright: GPL
URL: http://ic.redhat.com/
Packager: Interchange Development Team <info@akopia.com>
-Source: http://ic.redhat.com/pub/interchange/interchange-%{ic_version}.tar.gz
+Source: http://developer.akopia.com/pub/interchange/interchange-%{ic_version}.tar.gz
Group: Applications/Internet
Provides: %ic_package_basename
Obsoletes: %ic_package_basename
@@ -256,15 +256,6 @@ fi
%doc README.rpm
%doc README.cvs
%doc WHATSNEW
-%doc pdf/icbackoffice.pdf
-%doc pdf/iccattut.pdf
-%doc pdf/icconfig.pdf
-%doc pdf/icdatabase.pdf
-%doc pdf/icinstall.pdf
-%doc pdf/icintro.pdf
-%doc pdf/ictags.pdf
-%doc pdf/ictemplates.pdf
-%doc pdf/icupgrade.pdf
%{_mandir}/man1
%{_mandir}/man8
View
85 WHATSNEW
@@ -1,8 +1,13 @@
-#####################################
-Interchange 4.7.2 released 2001-??-??
+------------------------------------------------------------------------------
+
+ What's new in each version of Interchange
+
+------------------------------------------------------------------------------
+
+Interchange 4.7.2 released 2001-05-10
Server
---------
+------
* There is a pre-forked server mode enabled in interchange.cfg with:
PreFork Yes
@@ -22,7 +27,7 @@ Server
mode, can probably be ported to Windows if anyone cares.
Database
--------------
+--------
* Transactions now fully supported. Can open a transaction-capable
database in transactions mode [flag type=transactions table="table"]
and it will commit all changes not done in transaction mode and reopen
@@ -35,7 +40,7 @@ Database
That does the roughly equivalent to:
- SELECT bar from foo where baz = 'buz' LIMIT 1
+ SELECT bar from foo where baz = 'buz' LIMIT 1
* Improve autonumbering support to automatically use sequences or
autonumber field types. So now you can do:
@@ -66,11 +71,10 @@ Database
* Change all chained cost levels limit check to use new Limit directive
Orders/Pricing/Shipping
-------------------------
-* Significant changes to Order.pm in the area of order routing,
- while still maintaining backward compatibility. (Able to submit
- and monitor order on old construct, simple, and basic with no
- changes.)
+-----------------------
+* Significant changes to Order.pm in the area of order routing, while
+ still maintaining backward compatibility. (Able to submit and monitor
+ order on old construct, simple, and basic with no changes.)
* Added "cascade" route capability, that allows you to specify
one master order route that calls the rest of the routes.
@@ -93,9 +97,8 @@ Orders/Pricing/Shipping
the demo now has "FormIgnore mv_order_route".
* Extended field allows you to stringify a hash and set many, many
- parameters. We were running out of column space, and payment
- routes add many settings. This concept will soon be used in
- mv_metadata.
+ parameters. We were running out of column space, and payment routes
+ add many settings. This concept will soon be used in mv_metadata.
* Add new tag "assign". It allows you to assign to four things,
@@ -129,12 +132,16 @@ Orders/Pricing/Shipping
It is persistent in the user's session and effects only that user,
and should be used only when you know exactly what you are doing. Ha.
+* Add support for new CVV2 credit card security field in
+ mv_credit_card_cvv2, treated with same care as mv_credit_card_number.
+
+* Add recognition for a few more credit card types based on number.
+
Parser
--------------
+------
* Solve the great [if ] [othertag][else][/else][/othertag] [else]
[/else] [/if] problem. The behavior should be much improved in [if ...]
- tags. Will not now snarf the [else] from another tag that uses
- that.
+ tags. Will not now snarf the [else] from another tag that uses that.
* Make the default a secure submit if we are on a secure page and
have the user set secure=0 to disable.
@@ -146,14 +153,13 @@ Parser
* Fix the long-untouched tag_column routine to handle preformatted
text with align=none.
-* Add "yesno" display filter so that you can [filter
- yesno]1[/filter] and get "Yes" back -- also translates for
- Locale.
+* Add "yesno" display filter so that you can [filter yesno]1[/filter]
+ and get "Yes" back -- also translates for Locale.
Payment
----------
-* Extensively rework Payment routines. Decided to keep something like current
- framework, but you now can do:
+-------
+* Extensively rework Payment routines. Decided to keep something like
+ current framework, but you now can do:
&charge=route
@@ -202,24 +208,21 @@ Payment
* Parameters can be completely Route resident, no MV_PAYMENT_*
variables needed.
-* Changed mv_credit_card_info to delete all but
- mv_credit_card_reference digits when not encrypted. This is
- overdue....
+* Changed mv_credit_card_info to delete all but mv_credit_card_reference
+ digits when not encrypted. This is overdue....
-* All options are pulled from the option call first, the Route
- matching the name second, then finally the global MV_PAYMENT_*
- variables.
+* All options are pulled from the option call first, the Route matching
+ the name second, then finally the global MV_PAYMENT_* variables.
* All routes should be transparent if the mode exists. For instance,
you can define a route called "purchase_order" which will handle
POs, "internet_check" which handles checks, etc.
-* Add CCVS support via globalsub. Will do auth, sale at this
- point. Will soon add AVS support. Has extended information
- support.
+* Add CCVS support via globalsub. Will do auth, sale at this point. Will
+ soon add AVS support. Has extended information support.
Miscellaneous
---------------
+-------------
* Message directive now accepts -n (no trailing newline or whitespace) and
-i (screen info only, not logged) options before message.
@@ -240,14 +243,18 @@ Miscellaneous
or UI_STD_HEAD to ensure this works
(supplied by Stefan Hornburg <racke@linuxia.de>).
+* Added catalog configuration wizard, to move non-essential config from
+ makecat and simplify it a bit.
+
Bug fixes
-----------
+---------
* Fix bug in IMPORT_ONCE reported by vasile_abo@wexim.com.
* Fix no-zero-display bug in [cgi ...] tag, found by Mark Johnson.
* Fix a couple of bugs with AlwaysSecure not working in an order link.
* Fix rounding problem with Shipping.
* Fix failure to test record_exists in tag_data($table,undef,$key,{hash=>1})
-* Quite a few unreachable code sections removed, largely thanks to Bill Dawkins.
+* Quite a few unreachable code sections removed, largely thanks to Bill
+ Dawkins.
* Fix textarea build to call routine, remove unused call to
build_accessory_textarea, add proper call in /^text/ branch.
* Make sure tax is rounded to the proper number of frac_digits in
@@ -256,8 +263,11 @@ Bug fixes
twice (could happen if update values called)
* Remove for good unsightly extra attributes qw/true false undef/ in every
tag option hash.
+* Fix some item options bugs.
+* Many other small things.
+
+------------------------------------------------------------------------------
-#####################################
Interchange 4.7.1 released 2001-03-28.
* Added ability to cascade mv_click statements, e.g.:
@@ -678,5 +688,10 @@ Interchange 4.7.1 released 2001-03-28.
* Add ability to read files from a database instead of the filesystem.
+------------------------------------------------------------------------------
Interchange 4.7.0 not publicly released.
+
+------------------------------------------------------------------------------
+
+(end)
View
2  dist/foundation/pages/flypage.html
@@ -105,7 +105,7 @@
<td align="left">
<b>Out Of Stock<b>
<br>
- <a href="[area stock-alert [loop-code]]">In-Stock Notification</a>
+ <a href="[area stock-alert [item-code]]">In-Stock Notification</a>
</td>
[else]
<td align="left">
View
22 dist/foundation/pages/ord/checkout.html
@@ -264,7 +264,7 @@
<table border="0" cellspacing="0" cellpadding="0" width="50%">
<TR>
<td align="left">
- <INPUT TYPE=image VALUE="Refresh" src="__THEME_IMG_DIR__recalculate_button.gif">
+ <INPUT TYPE=image VALUE="Refresh" src="__THEME_IMG_DIR__recalculate_button.gif" border=0>
</td>
<td align="right">
<table align="center" cellspacing="0" border="0">
@@ -883,15 +883,21 @@
<tr><td>
<br>
<table align="center" cellpadding="10" cellspacing="10"><tr>
- <td>
- <INPUT TYPE=image VALUE="Refresh" src="__THEME_IMG_DIR__recalculate_button.gif">
- </td>
<td class="contentbar1">
- [button
- name="mv_todo.submit.x"
- src="__THEME__/placeorder.gif"
+[comment]
+ [button
+ name="mv_click"
+ src="__THEME__/placeorder.gif"
+ text="Place Order"
+ hidetext=1
]
- [/button]
+ mv_todo=submit
+ [/button]
+[/comment]
+ <input type=image src="__THEME_IMG_DIR__checkout_button.gif" VALUE="Place Order" name="mv_todo.submit" border=0>
+ </td>
+ <td>
+ <INPUT TYPE=image VALUE="Refresh" src="__THEME_IMG_DIR__recalculate_button.gif" border=0>
</td>
</tr></table>
View
4 pdf/README
@@ -1,4 +0,0 @@
-PLEASE NOTE
-
-These documents are automatically generated from SDF source files.
-Please do not modify them, as any changes will be overwritten.
View
BIN  pdf/icbackoffice.pdf
Binary file not shown
View
BIN  pdf/iccattut.pdf
Binary file not shown
View
BIN  pdf/icconfig.pdf
Binary file not shown
View
BIN  pdf/icdatabase.pdf
Binary file not shown
View
BIN  pdf/icinstall.pdf
Binary file not shown
View
BIN  pdf/icintro.pdf
Binary file not shown
View
BIN  pdf/ictags.pdf
Binary file not shown
View
BIN  pdf/ictemplates.pdf
Binary file not shown
View
BIN  pdf/icupgrade.pdf
Binary file not shown
View
1,360 pod/icadvanced.pod
@@ -0,0 +1,1360 @@
+=head1 NAME
+
+icadvanced - Advanced Interchange Topics
+
+=head1 DESCRIPTION
+
+=head1 Advanced Interchange Topics
+
+=over 4
+
+=item *
+
+Maintaining production Interchange servers
+
+=item *
+
+Interchange Administration Tool Development
+
+=item *
+
+Making catalog skeletons for use with makecat
+
+=item *
+
+Building custom link programs
+
+=back
+
+=head1 Maintaining Interchange
+
+Some utilities are supplied in the VendRoot/bin directory:
+
+ compile_link Compiles an Interchange vlink or tlink CGI link
+ configdump Dumps the configuration directives for a particular catalog
+ dump Dumps the session file for a particular catalog
+ expire Expires sessions for a particular catalog
+ expireall Expires all catalogs
+ makecat Make catalog
+
+Some example scripts for other functions are in the eg/ directory
+of the software distribution.
+
+Some thought should be given to where the databases, error logs, and
+session files should be located, especially on an ISP that might have
+multiple users sharing an Interchange server. In particular, put all
+of the session files and logs in a directory that is not writable by
+the user. This eliminates the possibility that the catalog may crash
+if the directory or file is corrupted.
+
+To test the format of user catalog configuration files before
+restarting the server, set (from VendRoot):
+
+ bin/interchange -test
+
+This will check all configuration files for syntax errors, which might
+otherwise prevent a catalog from booting. Once a catalog configures
+properly, user reconfiguration will not crash it. It will just cause
+an error. But, it must come up when the server is started.
+
+=head2 Starting, Stopping, and Re-starting the Servers
+
+The following commands need to have VENDROOT changed to the main
+directory where Interchange is installed. If the Interchange base
+directory is /home/interchange/, the start command would be
+/home/interchange/bin/interchange.
+
+Do a perldoc VENDROOT/bin/interchange for full documentation.
+
+To start the server with default settings:
+
+ VENDROOT/bin/interchange
+
+Assuming the server starts correctly, the names of catalogs as they
+are configured will be displayed, along with a message stating the
+process ID it is running under.
+
+It is usually best to issue a restart instead. It doesn't hurt to do a
+restart if you're actually starting the first time. And, if a server
+is already running (from this VENDROOT), a new start attempt will
+fail. To restart the server:
+
+ VENDROOT/bin/interchange -restart
+
+The -r option is the same as -restart.
+
+This is typically done to force Interchange to re-read its
+configuration. A message will be displayed stating that a TERM signal
+has been sent to the process ID the servers are running under. This
+information is also sent to VENDROOT/error.log. Check the error.log
+file for confirmation that the server has restarted properly.
+
+To stop the server:
+
+ VENDROOT/bin/interchange -stop
+
+A message will be displayed stating that a TERM signal has been sent
+to the process ID the server is running under. This information is
+also sent to VENDROOT/error.log.
+
+Because processes waiting for selection on some operating systems
+block signals, they may have to wait for HouseKeeping seconds to stop.
+The default is 60.
+
+To terminate the Interchange server with prejudice, in the event it
+will not stop:
+
+ VENDROOT/bin/interchange -kill
+
+=head2 UNIX and INET modes
+
+Both UNIX-domain and INET-domain sockets can be used for
+communication. INET domain sockets are useful when more than one web
+server, connected via a local-area network (LAN), is used for
+accessing an Interchange server.
+
+B<Important note:> When sending sensitive information like credit card
+numbers over a network, always ensure that the data is secured by a
+firewall, or that the Interchange server runs on the same machine as
+any SSL-based server used for encryption.
+
+Use the -i and -u flags if you only want to use one
+communication method:
+
+ # Start only in UNIX mode
+ VENDROOT/bin/interchange -r -u
+
+ # Start only in INET mode
+ VENDROOT/bin/interchange -r -i
+
+=head2 User Reconfiguration
+
+The individual catalogs can be reconfigured by the user by running the
+[reconfig] support tag. This should be protected by one of the several
+forms of Interchange authentication, preferably by HTTP basic
+authorization. See RemoteUser.
+
+The command line can be reconfigured (as the Interchange user) with:
+
+ VENDROOT/bin/interchange -reconfig <catalog>
+
+It is easy for the administrator to manually reconfigure a catalog.
+Interchange simply looks for a file etc/reconfig (based in the
+Interchange software directory) at HouseKeeping time. If it finds a
+script name that matches one of the catalogs, it will reconfigure that
+catalog.
+
+=head2 Expiring Sessions
+
+If Interchange is using DBM capability to store the sessions,
+periodically expire old sessions to keep the session database file
+from growing too large.
+
+ expire -c catalog
+
+There is also an expireall script which reads all catalog entries
+in interchange.cfg and runs expire on them. The expire script
+accepts a -r option which tells it to recover lost disk space.
+
+On a UNIX server, add a crontab entry such as the following:
+
+ # once a day at 4:40 am
+ 40 4 * * * perl /home/interchange/bin/expireall -r
+
+Interchange will wait until the current transaction is finished before
+expiring, so this can be done at any time without disabling web
+access. Any search paging files for the affected session (kept in
+ScratchDir) will be removed as well.
+
+If not running DBM sessions, use a Perl script to delete all files not
+modified in the last one or two days. The following will work if given
+an argument of a session directory or session files:
+
+ #!perl
+ # expire_sessions.pl -- delete files 2 days old or older
+
+ my @files;
+ my $dir;
+ foreach $dir (@ARGV) {
+ # just push files on the list
+ if (-f $dir) { push @files, $_; next; }
+
+ next unless -d $dir;
+
+ # get all the file names in the directory
+ opendir DIR, $dir or die "opendir $dir: $!\n";
+ push @files, ( map { "$dir/$_" } grep(! /^\.\.?$/, readdir DIR) ) ;
+ }
+
+ for (@files) {
+ unless (-f $_) {
+ warn "skipping $_, not a file.\n";
+ next;
+ }
+ next unless -M $_ >= 2;
+ unlink $_ or die "unlink $_: $!\n";
+ }
+
+It would be run with a command invocation like:
+
+ perl expire_sessions.pl /home/you/catalogs/simple/session
+
+Multiple directory names are acceptable, if there is more than one
+catalog.
+
+This script can be adjusted as necessary. Refinements might include
+reading the file to "eval" the session reference and expire only
+customers who are not members.
+
+=head2 My session files change to owner root every day!
+
+You have the expireall -r entry in the root crontab, and it should
+either be in the Interchange user crontab or run as:
+
+ 44 4 * * * su -c "/INTERCHANGE_ROOT/bin/expireall -r" INTERCHANGE_USERNAME
+
+=head1 Interchange Components
+
+Interchange components are merely portions of HTML/ITL that are
+included into pages within the site depending on options set in the
+Admin UI. The default component set includes the following:
+
+ best_horizontal
+best_vertical
+cart
+cart_display
+cart_tiny
+category_vertical
+cross_horizontal
+cross_vertical
+promo_horizontal
+promo_vertical
+random_horizontal
+random_vertical
+upsell_horizontal
+upsell_vertical
+
+=head2 Content -> Page Edit
+
+The Interchange Admin UI offers a page editor function that allows
+component definitions and options to be modified for each page within
+the catalog.
+
+Template
+
+The choices for the Template drop-down are read from template
+definition files located in the CATROOT/template directory. These
+files store the name and description of the template, as well as
+components and options for the particular template.
+
+To create a new template for use in the admin, it is best to copy an
+existing template definition to a new file name and edit it's contents
+to suit. Once the catalog is reconfigured, the new choice will be
+visible within the Content Page Editor admin function.
+
+Each template option is looped through and a scratch is set using its
+same name and value.
+
+ITL is used near the bottom of this file to set each option to default
+values before the page is displayed.
+
+ [set page_title][set]
+[set page_banner][set]
+[set members_only][set]
+[set component_before][set]
+[set component_after][set]
+[set bgcolor]#FFFFFF[/set]
+
+Page Title
+
+Sets the title of the page which is synonymous with the html
+<title></title> code.
+
+The following code within the template definition file is used to
+display this option within in the content editor:
+
+page_title: description: Page title
+
+This code dynamically adds the title to the page:
+
+<title>[scratch page_title]</title>
+
+Page Banner
+
+Sets a textual title for each page which is called by [either][scratch
+page_banner][or][scratch page_title][/either] This results in the Page
+Banner being displayed if defined. Otherwise, the Page Title is used.
+
+Members Only
+
+The members only function is handled by the following code within each
+template file:
+
+ [if scratch members_only]
+ [set members_only][/set]
+ [if !session logged_in]
+ [set mv_successpage]@@MV_PAGE@@[/set]
+ [bounce page=login]
+ [/if]
+[/if]
+
+This code says if members only is set to yes and the visitor is logged
+in, display the page. Otherwise, redirect the visitor to the login
+page.
+
+Break 1
+
+This code causes a separation in the Content Editor between the next
+set of options. (A blue line)
+
+Horizontal Before Component
+
+This allows the inclusion of a defined component to be displayed
+before, or above, the page's content. It is called with the following
+code within the LEFTRIGHT_TOP template:
+
+ [if scratch component_before]
+[include file="templates/components/[scratch component_before]"]
+[set component_before][/set]
+[/if]
+
+Horizontal After Component
+
+This function allows the inclusion of a defined component to be
+displayed after or below the pages's content. It's called with the
+following code within the LEFTRIGHT_BOTTOM template:
+
+ [if scratch component_after]
+[include file="templates/components/[scratch component_after]"]
+[set component_after][/set]
+[/if]
+
+Horizontal Item Width
+
+This setting allows you to choose how many items the horizontal
+components display. For example, the horizontal best sellers component
+uses this setting to randomly select the best sellers. Notice the
+default to 2 if nothing is defined.
+
+ random="[either][scratch component_hsize][or]2[/either]"
+
+Special Tag
+
+This setting is only viable when a promotion is used for a horizontal
+component. It tells the promotional component which rows to evaluate
+in the merchandising table for display within the component. This
+setting normally corelates to the featured column of the merchandising
+table as follows:
+
+ [query arrayref=main
+ sql="
+ SELECT sku,timed_promotion,start_date,finish_date
+ FROM merchandising
+ WHERE featured = '[scratch hpromo_type]'
+ "][/query]
+
+Before/After Banner
+
+Allows a title for the horizontal components to be defined to
+displayed in a header above the component's items. It is called with
+the [scratch hbanner] tag.
+
+Break 2
+
+This code causes a separation in the Content Editor between the next
+set of options. (A blue line)
+
+Vertical Component
+
+Defines a component to be displayed along the right side of the
+LEFTRIGHT_BOTTOM template. It is called from the template with the
+following code:
+
+ [include file="templates/components/[scratch component_right]"]
+
+Vertical Items Height
+
+Sets the number of items to display within the vertical component.
+Called with the following code:
+
+ random="[either][scratch component_vsize][or]3[/either]"
+
+Right Banner
+
+Allows a title to be set for a vertical component which is displayed
+as a header above the items in the vertical component. It's called
+with the [scratch vbanner] tag.
+
+Special Tag
+
+Essentially the same as the Special Tag setting described in item
+number 9 above.
+
+Background Color
+
+Allows the background color of the page to be selected. The choices
+are stored within the page or template definition as in:
+
+ bgcolor:
+ options: #FFFFFF=White,pink=Pink
+ widget: select
+ description: Background color
+
+Content
+
+Allows the page code to be downloaded, uploaded and viewed/edited.
+Only the code between <!-- BEGIN CONTENT --> and <!-- END CONTENT -->
+is displayed or can be edited here.
+
+Preview, Save, and Cancel buttons
+
+Allows the changes to the edited page to be previewed in a pop-up
+browser window, or saved. Cancel returns you to the page editor
+selection page.
+
+Save template in page
+
+Template settings are stored in the template definitions by default.
+This allows a common set of choices for template settings for all
+pages. If specific setting options are desired for a page, the
+template can be saved within the page so that it may have individual
+options.
+
+The in-page template definition must be surrounded by [comment]
+[/comment].
+
+=head2 Custom Admin UI Options
+
+Other options may be added to the template by defining them in the
+default definition file, or using in-page definitions.
+
+When the following lines are added to the template definition, the new
+option is added to the Admin UI.
+
+ option_name:
+options: 1,2*,3
+widget: select
+description: Option Description
+help: Other Details
+
+Each time the template is used, an option_name scratch variable is
+created. (Called with: [scratch option_name].) This scratch value will
+be equal to what's selected here in the admin tool.
+
+The possible widgets include:
+
+ break - produces the blue line separator.
+radio - produces radio button type selections.
+select - standard drop-down selector.
+move_combo - select drop down with options and text input for new option.
+
+=head1 Administrative Pages
+
+With Interchange's GlobalSub capability, very complex add-on
+schemes can be implemented with Perl subroutines. And with the new
+writable database, pages that modify the catalog data can be made. See
+MasterHost, RemoteUser, and Password.
+
+In addition, any Interchange page subdirectory can be protected from
+access by anyone except the administrator if a file called '.access'
+is present and non-zero in size.
+
+=head2 Controlling Access to Certain Pages
+
+If the directory containing the page has a file .access and that
+file's size is zero bytes, access can be gated in one of several ways.
+
+=over 4
+
+=item 1.
+
+If the file .access_gate is present, it will be read and scanned
+for page-based access. The file has the form:
+
+ page: condition
+
+=back
+ *: condition
+
+=over 4
+
+=item
+
+The page is the file name of the file to be controlled (the .html
+extension is optional). The condition is either a literal Yes/No
+or Interchange tags which would produce a Yes or No (1/0 work
+just fine, as do true/false).
+
+The entry for * sets the default action if the page name is not
+found. If pages will be allowed by default, set it to 1 or Yes.
+If pages are to be denied by default in this directory, leave blank or
+set to No. Here is an example, for the directory controlled,
+having the following files:
+
+ -rw-rw-r-- 1 mike mike 0 Jan 8 14:19 .access
+
+=back
+ -rw-rw-r-- 1 mike mike 185 Jan 8 16:00 .access_gate
+ -rw-rw-r-- 1 mike mike 121 Jan 8 14:59 any.html
+ -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 bar.html
+ -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 baz.html
+ -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 foo.html
+
+=over 4
+
+=item
+
+The contents of .access_gate:
+
+ foo.html: [if session username eq 'flycat']
+
+=back
+ Yes
+ [/if]
+ bar: [if session username eq 'flycat']
+ [or scratch allow_bar]
+ Yes
+ [/if]
+ baz: yes
+ *: [data session logged_in]
+
+=over 4
+
+=item
+
+The page controlled/foo is only allowed for the logged-in user
+B<flycat>.
+
+The page controlled/bar is allowed for the logged-in user
+B<flycat>, or if the scratch variable allow_bar is set to a
+non-blank, non-zero value.
+
+The page controlled/baz is always allowed for display.
+
+The page controlled/any (or any other page in the directory not
+named in .access_gate) will be allowed for any user logged in via
+I<UserDB>. NOTE: The .access_gate scheme is available for database
+access checking if the database is defined as an AdminDatabase. The
+.access_gate file is located in ProductDir.
+
+=back
+
+=over 4
+
+=item 2.
+
+If the Variable MV_USERDB_REMOTE_USER is set (non-zero and
+non-blank), any user logged in via the UserDB feature will receive
+access to all pages in the directory. NOTE: If there is a
+.access_gate file, it overrides this.
+
+=item 3.
+
+If the variables MV_USERDB_ACL_TABLE is set to a valid database
+identifier, the UserDB module can control access with simple ACL
+logic. See USER DATABASE. NOTE: If there is a .access_gate file, it
+overrides this. Also, if MV_USERDB_REMOTE_USER is set, this
+capability is not available.
+
+=back
+
+=head2 [display] tag and mv_metadata
+
+Interchange can store meta information for selected columns of tables
+in a site's database. This meta information is used when the user
+interacts with the database. For example, the meta informaton for a
+Hide Item field might specify that a checkbox be displayed when the
+user edits that field, since the only reasonable values are on and
+off. Or, the meta information might specify a filter on data
+entered for a Filename field which makes sure that the characters
+entered are safe for use in a filename.
+
+Widget type specifies the HTML INPUT tag type to use when
+displaying the field in, say, the item editor.
+
+Width and Height only apply to some of the Widget type
+options, for instance the Textarea widget.
+
+Label is displayed instead of the internal column name. For
+example, the category column of the products table might have a
+label of Product Category.
+
+Help is displayed below the column label, and helps describe the
+purpose of the field to the user.
+
+Help url can be used to link to a page giving more information on
+the field.
+
+Lookup can be used when a field is acting like a foreign key into
+another table. In that case, use some sort of select box as the widget
+type, and if referencing multiple rows in the destination table, use a
+multi select box, with colons_to_null as the pre_filter, and
+:: as the lookup_exclude.
+
+Filter and pre_filter can be used to filter data destined for
+that field or data read from that field, respectively.
+
+Repeat?: The Interchange back office UI uses the mv_metadata table to
+discover formatting information for field, table, and view display.
+The information is kept in fields in the mv_metadata table, and is
+used to select the display, the HTML input type, the size (height and
+width where appropriate), label, help text, additional help URL, and
+default value display.
+
+It works in conjunction with the [display ...] usertag defined in the
+Interchange UI as well as in specific pages in the UI. The [display]
+tag has this syntax:
+
+[display table=tablename column=fieldname key=key arbitrary=tag
+filter=op ...]
+
+In the simplest use, the formatting information for a table form field
+is called with:
+
+=over 4
+
+=item
+
+[display table=products column=category key="os28007"]
+
+=back
+
+The mv_metadata table is scanned for the following keys:
+
+=over 4
+
+=item
+
+products::category::os28007
+
+products::category
+
+=back
+
+If a row is found with one of those keys, then the information in the
+row is used to set the display widget. If no row is found, an INPUT
+TYPE=TEXT widget is displayed. If the data is all digits, a size of 8
+is used, otherwise the size is 60.
+
+If the following row were found (not all fields shown, would be
+tab-separated in the actual data):
+
+ code type width height label options
+ products::category text 20 Category
+
+Then this would be output:
+
+ <INPUT TYPE=text SIZE=20 VALUE="*category*">
+
+If the following row were found:
+
+ code type width height label options
+ products::category select Category =none, product=Hardware
+
+Then the following would be output:
+
+ <SELECT NAME=category>
+ <OPTION VALUE="">none
+ <OPTION VALUE="product">Hardware
+ </SELECT>
+
+The standard widget types are:
+
+=over 4
+
+=item text
+
+The default. Uses the fields:
+
+ width size of input box
+
+=back
+
+=over 4
+
+=item textarea
+
+Format a <TEXTAREA> </TEXTAREA> pair. Uses the fields:
+
+ width COLS for textarea
+
+=back
+ height ROWS for textarea
+
+=over 4
+
+=item select
+
+Format a <SELECT> </SELECT> pair with appropriate options. Uses the
+fields:
+
+ height SIZE for select
+
+=back
+ default Default for SELECTED
+ options Options for a fixed list (or prepended to a lookup)
+ lookup signals a lookup (used as field name if "field" empty)
+ field field to look up possible values in
+ db table to look up in if not current table
+ lookup_exclude regular expression to exclude certain values from lookup
+
+=head1 Usertag Reference
+
+Admin Tool-specific usertags.
+
+=head1 Admin Tool Database Tables
+
+=head2 icmenu.txt
+
+Used for back-office administration UI menus and wizards.
+
+ code
+ Arbitrary primary key
+ mgroup
+ Menu group (for grouping searches)
+ msort
+ Sort order within the group
+ next_line
+ Set to 1 if submenu
+ indicator
+ exclude_on
+ depends_on
+ page
+ form
+ name
+ super
+ inactive
+ special
+ help_name
+ img_dn
+ img_up
+ img_sel
+ img_icon
+ url
+
+=head2 mv_metadata.asc
+
+ code
+ Table::Column to be operated on.
+ Database table
+ type
+ Widget type (Select the basic display type for the field)
+ textarea = Textarea
+ text = Text Entry (default)
+ select = Select Box
+ yesno = Yes/No (Yes=1)
+ noyes = No/Yes (No=1)
+ multiple = Multiple Select
+ combo = Combo Select
+ reverse_combo = Reverse Combo
+ move_combo = Combo move
+ display = Text of option
+ hidden_text = Hidden(show text)
+ radio = Radio box
+ radio_nbsp = Radio (nbsp)
+ checkbox = Checkbox
+ check_nbsp = Checkbox (nbsp)
+ imagedir = Image listing
+ imagehelper = Image upload
+ date = Date selector
+ value = Value
+ option_format = Option formatter
+ show = Show all options
+ width
+ Width (SIZE for TEXT, COLS for TEXTAREA, Label limit for SELECT)
+ height
+ Height (SIZE for SELECT, ROWS for TEXTAREA)
+ field
+ Field for lookup (can be two comma separated fields, in which case
+ second is used as the label text. Both must be in the same table.)
+ db
+ name
+ Variable name (normally left empty, changes variable name to send in
+ form)
+ outboard
+ Select directory for image listing widget
+ options
+ options in the format <blockquote>value=label*</blockquote>
+ attribute
+ Column name (Do not set this.)
+ label
+ help
+ Help (displays at top of page)
+ lookup
+ Lookup select (Whether lookup is performed to get options for a select
+ type. If nothing is in the field, then used as the name of the field
+ to lookup in. Use lookup table if you want to look up in a different
+ table.
+ filter
+ Filters (Filters which can transform or constrain your data. Some
+ widgets require filters.)
+ help_url
+ Help URL (links below help text)
+ A URL which will provide more help
+ pre_filter
+ lookup_exclude
+ ADVANCED: regular expression that excludes certain keys from the lookup
+ prepend
+ append
+ Append HTML (HTML to be appended to the widget. Will substitute in the
+ macros _UI_TABLE_, _UI_COLUMN_, _UI_KEY_, and _UI_VALUE_, and will
+ resolve relative links with absolute links.)
+ display_filter
+
+=head1 makecat - Set Up a Catalog from a Template
+
+After Interchange is installed, you need to set up at least one
+catalog. Interchange will not function properly until a catalog is
+created.
+
+The supplied makecat script, which is in the Interchange program
+directory bin, is designed to set up a catalog based on the user's
+server configuration. It interrogates the user for parameters like
+which directories to use, a URL to base the catalog in, HTTP server
+definitions, and file ownership. It gives relevant examples of the
+entries it expects to receive.
+
+B<Note: >A catalog can only be created once. All further configuration
+is done by editing the files within the catalog directory.
+
+The makecat script requires a catalog skeleton to work from. The
+Foundation demo is distributed with Interchange. See the icfoundation
+document for information on building the Foundation demo store. Other
+demo catalogs are available at http://developer.akopia.com/.
+
+It is not normally necessary for you to understand how to build
+catalog skeletons for use with makecat, but the following information
+will help you if you should ever need to.
+
+=head2 Catalog Skeletons
+
+A catalog skeleton contains an image of a configured catalog. The best
+way to see what the makecat program does is to configure the simple
+demo and then run a recursive diff on the template and configured
+catalog directories:
+
+ cd /usr/local/interchange
+ diff -r construct catalogs/construct
+
+The files are mostly identical, except that certain macro strings have
+been replaced with the answers given to the script. For example, if
+www.mydomain.com was answered at the prompt for a server name, this
+difference would appear in the catalog.cfg file:
+
+ # template
+ Variable SERVER_NAME __MVC_SERVERNAME__
+
+ # configured catalog
+ Variable SERVER_NAME www.mydomain.com
+
+The macro string __MVC_SERVERNAME__ was substituted with the answer to
+the question about server name. In the same way, other variables are
+substituted, and include:
+
+ MVC_BASEDIR MVC_IMAGEDIR
+MVC_CATROOT MVC_IMAGEURL
+MVC_CATUSER MVC_MAILORDERTO
+MVC_CGIBASE MVC_MINIVENDGROUP
+MVC_CGIDIR MVC_MINIVENDUSER
+MVC_CGIURL MVC_SAMPLEHTML
+MVC_DEMOTYPE MVC_SAMPLEURL
+MVC_DOCUMENTROOT MVC_VENDROOT
+MVC_ENCRYPTOR
+
+B<Note: >Not all of these variables are present in the "construct"
+template, and more may be defined. In fact, any environment variable
+that is set and begins with MVC_ will be substituted for by the
+makecat script. For example, to set up a configurable parameter to
+customize the COMPANY variable in catalog.cfg, run a pre-qualifying
+script that set the environment variable MVC_COMPANY and then place in
+the catalog.cfg file:
+
+Variable COMPANY __MVC_COMPANY__
+
+All files within a template directory are substituted for macros, not
+just the catalog.cfg file. There are two special directories named
+html and images. These will be recursively copied to the
+directories defined as SampleHTML and ImageDir.
+
+B<Note: >The template directory is located in the Interchange software
+directory, i.e., where interchange.cfg resides. Avoid editing files
+in the template directory. To create a new template, it is recommended
+that it should be named something besides 'construct' and a copy of
+the construct demo directory be used as a starting point. Templates
+are normally placed in the Interchange base directory, but can be
+located anywhere. The script will prompt for the location if it cannot
+find a template.
+
+In addition to the standard parameters prompted for by Interchange,
+and the standard catalog creation procedure, four other files in the
+config directory of the template may be defined:
+
+ additional_fields -- file with more parameters for macro substitution
+additional_help -- extended description for the additional_fields
+precopy_commands -- commands passed to the system prior to catalog copy
+postcopy_commands -- commands passed to the system after catalog copy
+
+All files are paragraph-based. In other words, a blank line (with no
+spaces) terminates the individual setting.
+
+The additional_fields file contains:
+
+ PARAM
+The prompt. Set PARAM to?
+The default value of PARAM
+
+This would cause a question during makecat:
+
+ The prompt. Set PARAM to?.....[The default value of PARAM]
+
+If the additional_help file is present, additional instructions for
+PARAM may be provided.
+
+ PARAM
+
+These are additional instructions for PARAM, and they
+may span multiple lines up to the first blank line.
+
+The prompt would now be:
+
+ These are additional instructions for PARAM, and they
+may span multiple lines up to the first blank line.
+
+The prompt. Set PARAM to?.....[The default value of PARAM]
+
+If the file config/precopy_commands exists, it will be read as a
+command followed by the prompt/help value.
+
+ mysqladmin create __MVC_CATALOGNAME__
+We need to create an SQL database for your Interchange
+database tables.
+
+This will cause the prompt:
+
+ We need to create an SQL database for your Interchange
+database tables.
+
+Run command "mysqladmin create simple"?
+
+If the response is "y" or "yes," the command will be run by passing it
+through the Perl system() function. As with any of the additional
+configuration files, MVC_PARAM macro substitution is performed on the
+command and help. Proper permissions for the command are required.
+
+The file config/postcopy_commands is exactly the same as
+<precopy_commands>, except the prompt occurs after the catalog files
+are copied and macro substitution is performed on all files.
+
+There may also be SubCatalog directives:
+
+ SubCatalog easy simple /home/catalogs/simple /cgi-bin/easy
+
+easy
+
+=over 4
+
+=item
+
+The name of the subcatalog, which also controls the name of the
+subcatalog configuration file. In this case, it is easy.cfg.
+
+=back
+
+simple
+
+=over 4
+
+=item
+
+The name of the base configuration that will be the basis for the
+catalog. Parameters in the easy.cfg file that are different will
+override those in the catalog.cfg file for the base configuration.
+
+=back
+
+The remaining parameters are similar to the Catalog directive.
+
+Additional interchange.cfg parameters set up administrative parameters
+that are catalog wide. See the server configuration file for details
+on each of these.
+
+Each catalog can be completely independent with different databases,
+or catalogs can share pages, databases, and session files. This means
+that several catalogs can share the same information, allowing
+"virtual malls."
+
+=head2 Manual Installation of Catalogs
+
+An Interchange installation is complex, and requires quite a few
+distinct steps. Normally you will want to use the interactive catalog
+builder, makecat, described above. It makes the process much
+easier. Please see the iccattut document for a full tutorial on
+building a catalog by hand.
+
+=head1 Link Programs
+
+Interchange requires a web server that is already installed on a
+system. It does have an internal server which can be used for
+administration, testing, and maintenance, but this will not be useful
+or desireable in a production environment.
+
+As detailed previously, Interchange is always running in the
+background as a daemon, or resident program. It monitors either a
+UNIX-domain file-based socket or a series of INET-domain sockets. The
+small CGI link program, called in the demo simple, is run to
+connect to one of those sockets and provide the link to a browser.
+
+B<Note: >Since Apache is the most popular web server, these
+instructions will focus on it. If using another type of web server,
+some translation of terms may be necessary.
+
+A ScriptAlias or other CGI execution capability is needed to use
+the link program. (The default ScriptAlias for many web servers is
+/cgi-bin.) If ExecCGI is set for all directories, then any
+program ending in a particular file suffix (usually .cgi) will be
+seen as a CGI program.
+
+Interchange, by convention, names the link program the same name as
+the catalog ID, though this is not required. In the distribution demo,
+this would yield a program name or SCRIPT_PATH of /cgi-bin/simple
+or /simple.cgi. This SCRIPT_PATH can be used to determine which
+Interchange catalog will be used when the link program is accessed.
+
+=head2 UNIX-Domain Sockets
+
+This is a socket which is not reachable from the Internet directly,
+but which must come from a request on the server. The link program
+vlink is the provided facility for such communication with
+Interchange. This is the most secure way to run a catalog, for there
+is no way for systems on the Internet to interact with Interchange
+except through its link program.
+
+The most important issue with UNIX-domain sockets on Interchange is
+the permissions with which the CGI program and the Interchange server
+run. To improve security, Interchange normally runs with the socket
+file having 0600 permissions (rw-------), which mandates that the CGI
+program and the server run as the same user ID. This means that the
+vlink program must be SUID to the same user ID as the server
+executes under. (Or that CGIWRAP is used on a single catalog system).
+
+With Interchange's multiple catalog capability, the permissions
+situation gets a bit tricky. Interchange comes with a program,
+makecat, which configures catalogs for a multiple catalog system.
+It should properly set up ownership and permissions for multiple users
+if run as the superuser.
+
+=head2 INET-Domain Sockets
+
+These are sockets which are reachable from the Internet directly. The
+link program tlink is the provided facility for such communication
+with Interchange. Other browsers can talk to the socket directly if
+mapped to a catalog with the global TcpMap directive. To improve
+security, Interchange usually checks that the request comes from one
+of a limited number of systems, defined in the global TcpHost
+directive. (This check is not made for the internal HTTP server.)
+
+=head2 Internal HTTP Server
+
+If the socket is contacted directly (only for INET-domain sockets),
+Interchange will perform the HTTP server function itself, talking
+directly to the browser. It can monitor any number of ports and map
+them to a particular catalog. By default, it only maps the special
+catalog mv_admin, which performs administrative functions. The default
+port is 7786, which is the default compiled into the distribution
+tlink program. This port can be changed via the TcpMap directive.
+
+To prevent catalogs that do not wish access to be made in this way
+from being served from the internal server, Interchange has a fixed
+SCRIPT_PATH of /catalogname (/simple for the distribution demo)
+which needs to be placed as an alias in the Catalog directive to
+enable access. See TcpMap for more details.
+
+=head2 Setting Up VLINK and TLINK
+
+The vlink and tlink programs, compiled from vlink.c and
+tlink.c, are small C programs which contact and interface to a
+running Interchange daemon. The VLINK executable is normally made
+setuid to the user account which runs Interchange, so that the
+UNIX-domain socket file can be set to secure permissions (user
+read-write only). It is normally not necessary for the user to do
+anything. They will be compiled by the configuration program. If the
+Interchange daemon is not running, either of the programs will display
+a message indicating that the server is not available. The following
+defines in the produced config.h should be set:
+
+=over 4
+
+=item LINK_FILE
+
+Set this to the name of the socket file that will be used for
+configuration, usually "/usr/local/lib/interchange/etc/socket" or the
+"etc/socket" under the directory chosen for the VendRoot.
+
+=item LINK_HOST
+
+Set this to the IP number of the host which should be contacted. The
+default of 127.0.0.1 (the local machine) is probably best for many
+installations.
+
+=item LINK_PORT
+
+Set this to the TCP port number that the Interchange server will
+monitor. The default is 7786 (the decimal ASCII codes for 'M' and 'V')
+and does not normally need to be changed.
+
+=item LINK_TIMEOUT
+
+Set this to the number of seconds vlink or tlink should wait
+before announcing that the Interchange server is not running. The
+default of 45 is probably a reasonable value.
+
+=back
+
+=head2 Compiling VLINK and TLINK
+
+There is a compile_link program which will assist with this. Do:
+
+ perldoc VENDROOT/bin/compile_link
+
+for its documentation.
+
+=head2 Manually Compiling VLINK and TLINK
+
+Change directories to the src directory, then run the GNU configure
+script:
+
+ cd src
+ ./configure
+
+There will be some output displayed as the configure script checks the
+system. Then, compile the programs:
+
+ perl compile.pl
+
+To compile manually:
+
+ cc vlink.c -o vlink
+ cc tlink.c -o tlink
+
+On manual compiles, ensure that the C compiler will be invoked
+properly with this little ditty:
+
+ perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS -o tlink tlink.c");'
+ perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS -o vlink vlink.c");'
+
+On some systems, the executable can be made smaller with the strip
+program, if available. It is not required.
+
+ strip vlink
+ strip tlink
+
+If Interchange is to run under a different user account than the
+individual configuring the program, make that user the owner of
+vlink. Do not make vlink owned by root, because making vlink
+SETUID root is an huge and unnecessary security risk. It should also
+not normally run as the default Web user (often nobody or
+http)).
+
+ chown interchange vlink
+
+Move the vlink executable to the cgi-bin directory:
+
+ mv vlink /the/cgi-bin/directory
+
+Make vlink SETUID:
+
+ chmod u+s /the/cgi-bin/directory/vlink
+
+Most systems unset the SUID bit when moving the file, so change it
+after moving.
+
+The SCRIPT_NAME, as produced by the HTTP server, must match the name
+of the program. (As usual, let the makecat program do the work.)
+
+=head2 VLINK or TLINK Compile Problems
+
+The latest version of vlink.c and tlink.c have been compiled on
+the following systems:
+
+ AIX 4.1
+ BSD2.0 (Pentium/x86)
+ Debian GNU/Linux
+ Digital Unix (OSF/Alpha)
+ FreeBSD 2.x, 3.x, 4.x
+ IRIX 5.3, IRIX 6.1
+ OpenBSD 2.7
+ Red Hat Linux 6.2, 7.0, 7.1
+ SCO OpenServer 5.x
+ Solaris 2.x (Sun compiler and GCC)
+ Solaris 7 (Sun compiler and GCC)
+ SunOS 4.1.4
+
+Some problems may occur. In general, ignore warnings about pointers.
+
+Make sure that you have run the configure program in the src
+directory. If you use Interchange's makecat program, it will try to
+compile an appropriate link at that time, and will substitute tlink.pl
+if that doesn't work.
+
+You can compile manually with the proper settings with this series of
+commands:
+
+ cd src
+ ./configure
+ perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o tlink tlink.c")'
+ perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o vlink vlink.c")'
+
+There is also a compile_link program which has docmentation
+embedded and which will compile an approprate link. If you cannot
+compile, try using the tlink.pl script, written in Perl instead of
+C, which should work on most any system. Since vlink needs to have
+values set before compilation, a pre-compiled version will not work
+unless it has the exact values you need on your system. If you can use
+the defaults of 'localhost' and port 7786, you may be in luck.
+
+=head1 Installing Perl Modules without Root Access
+
+Installing Interchange without root access is no problem. However,
+installing Perl modules without root access is a little trickier.
+
+You must build your makefile to work in your home dir. Something like:
+
+ PREFIX=~/usr/local \
+INSTALLPRIVLIB=~/usr/local/lib/perl5 \
+INSTALLSCRIPT=~/usr/local/bin \
+INSTALLSITELIB=~/usr/local/lib/perl5/site_perl \
+INSTALLBIN=~/usr/local/bin \
+INSTALLMAN1DIR=~/usr/local/lib/perl5/man \
+INSTALLMAN3DIR=~/usr/local/lib/perl5/man/man3
+
+Put this in a file, say 'installopts', and use it for the Makefile.PL.
+
+ perl Makefile.PL `cat installopts`
+
+Then, forget ./config. Just do:
+
+ make
+make test
+make install
+
+Some of the tests may fail, but that's probably ok.
+
+Also make sure to install Bundle::Interchange, which will need the
+same config data as you put into 'installopts'.
+
+=head1 Installation Troubleshooting
+
+Interchange uses the services of other complex programs, such as Perl,
+Web servers, and relational databases, to work. Therefore, when there
+is a problem, check these programs before checking Interchange. Many
+more basic installation problems have to do with those than with
+Interchange itself.
+
+If an error message is received about not being able to find
+libraries, or a core dump has occurred, or a segment fault message, it
+is always an improperly built or configured Perl. Contact the system
+administrator or install a new Perl.
+
+The makecat program is intended to be used to create the starting
+point for the catalog. If the demo does not work the first time, keep
+trying. If it still does not work, try running in INET mode.
+
+Check the two error log files: error.log in the Interchange home
+directory (where interchange.cfg resides) and error.log in the
+catalog directory (where catalog.cfg resides; there can be many of
+these). Many problems can be diagnosed quickly if these error logs are
+consulted.
+
+Check the README file, the FAQ, and mail list archive at the official
+Interchange web site for information:
+
+ http://developer.akopia.com/
+
+Double check the following items:
+
+=over 4
+
+=item 1.
+
+Using UNIX sockets?
+
+=over 8
+
+=item *
+
+Check that the vlink program is SUID, or the appropriate changes
+have been made in the SocketPerms directive. Unless the files are
+world-writable, the vlink program and the Interchange server must run
+as the same user ID! If running CGI-WRAP or SUEXEC, the vlink
+program must not be SUID.
+
+=item *
+
+If having trouble with the vlink program (named construct in the
+demo configuration), try re-running makecat and using INET mode
+instead. (Or copy the tlink INET mode link program over vlink).
+This should work unchanged for many systems.
+
+=item *
+
+If using an ISP or have a non-standard network configuration, some
+changes to interchange.cfg are necessary. For tlink to work, the
+proper host name(s) must be configured into the TcpHost directive in
+interchange.cfg. The program selects port 7786 by default (the ASCII
+codes for "M" and "V"). If another port is used, it must be set to the
+same number in both the tlink program (by running compile_link) and
+the minivend.cfg file. The tlink program does not need to be
+SUID.
+
+=back
+
+=item 2.
+
+Proper file permissions?
+
+=over 8
+
+=item *
+
+The Interchange server should not run as the user nobody! The
+program files can be owned by anyone, but any databases, ASCII
+database source files, error logs, and the directory that holds them
+must be writable by the proper user ID, that is the one that is
+executing the MiniVend program.
+
+=item *
+
+The best way to operate in multi-user, multiple catalog setups is to
+create a special interch user, then put that user in the group that
+contains each catalog user. If a group is defined for each individual
+user, this provides the best security. All associated files can be in
+660 or 770 mode. There should be no problems with permissions and no
+problems with security.
+
+=back
+
+=item 3.
+
+Is the vlink program being executed on a machine that has the
+socket file etc/socket on a directly attached disk?
+
+=over 8
+
+=item *
+
+UNIX-domain sockets will not work on NFS-mounted file systems! This
+means that the server minivend and the CGI program vlink must be
+executing on the same machine.
+
+=item *
+
+The tlink program does not have this problem, but it must have the
+proper host name(s) and TCP ports set in the TcpHost and TcpPort
+directives in interchange.cfg. Also, be careful of security if
+sensitive information, like customer credit card numbers, is being
+placed on a network wire.
+
+=back
+
+=back
+
View
937 pod/icbackoffice.pod
@@ -1,937 +0,0 @@
-=head1 NAME
-
-Interchange Back Office
-
-=head1 Interchange Back Office
-
-Interchange is the industry's most widely distributed and implemented
-open source e-commerce platform. This document describes how to
-administer a commerce site with Interchange's back-office
-functionality, and discusses site management and security.
-
-=head1 Tracking and Back-End Order Entry
-
-Interchange allows the entry of orders into a system through one of
-several methods. The C<AsciiBackend> capability allows submission of
-parameters to an external order entry script. Support for SQL allows
-the entry of orders directly into an SQL database. Orders can be
-written to an ASCII file. They can be formatted precisely for
-e-mail-based systems. The orders can be placed in a DBM file. Finally,
-embedded Perl allows completely flexible order entry, including
-real-time credit card verification and settlement.
-
-=head2 ASCII Backup Order Tracking
-
-If C<AsciiTrack> is set to a legal file name (based in VendRoot unless
-it has a leading "/"). A copy of the order is saved and sent in an
-e-mail.
-
-If the file name string begins with a pipe "|," a program will be run
-and the output "piped" to that program. This allows easy back-end
-entry of orders with an external program.
-
-=head2 Database Tracking
-
-Once the order report is processed, the order is complete. Therefore,
-it is the ideal place to put Interchange tags that make order entries
-in database tables.
-
-A good model is to place a single record in a database summarizing the
-order and a series of lines that correspond to each line item in the
-order. This can be in the same database table. If the order number
-itself is the key for the summary, a line number can be appended to
-the order number to show each line of the order.
-
-The following would summarize a sample order number S00001 for part
-number 00-0011 and 99-102:
-
- code order_number part_number quantity price shipping tax
- S00001 S00001 3 2010 12.72 100.50
- S00001-1 S00001 00-0011 2 1000 UPS yes
- S00001-2 S00001 99-102 1 10 UPS yes
-
-Fields can be added where needed, perhaps with order status, shipping
-tracking number, address, customer number, or other information.
-
-The above is accomplished with Interchange's C<[import ....]> tag
-using the convenient C<NOTES> format:
-
- [set import_status]
- [import table=orders type=LINE continue=NOTES]
-
- code: [value mv_order_number]
- order_number: [value mv_order_number]
- quantity: [nitems]
- price: [subtotal noformat=1]
- shipping: [shipping noformat=1]
- tax: [salestax noformat=1]
-
- [/import]
-
- [item-list]
- [import table=orders type=LINE continue=NOTES]
-
- code: [value mv_order_number]-[item-increment]
- order_number: [value mv_order_number]
- quantity: [item-quantity]
- price: [item-price noformat=1]
- shipping: [shipping-description]
- tax: [if-item-field nontaxable]No[else]Yes[/else][/if]
-
- [/import][/item-list]
-
-=head2 Custom Order Routing
-
-Interchange can send order emails and perform custom credit card
-charges and/or logging for each item. The Route directive is used to
-control this behavior, along with the C<mv_order_route> item attribute
-and C<mv_order_route> form variable.
-
-Routes are established with the C<Route> directive, which is similar
-to the C<Locale> directive. Each route is like a locale, so that
-key-value pairs can be set. Here is an example setting:
-
- Route VEN pgp_key 0x67798115
- Route VEN email orders@akopia.com
- Route VEN reply service@akopia.com
- Route VEN encrypt 1
- Route VEN encrypt_program "/usr/bin/pgpe -fat -q -r %s"
- Route VEN report etc/report_mail
-
-This route would be used whenever the value C<VEN> was contained in
-the form variable C<mv_order_route>.
-
-The last route that is defined provides the defaults for all other
-routes. For example, if C<encrypt_program> is set there, then the same
-value will be the default for all routes.
-
-The attributes that can be set are:
-
-=over 4
-
-=item attach
-
-Determines whether the order report should be attached to the main
-order report e-mail. This is useful if certain items must be printed
-separately from others, perhaps for FAX to a fulfillment house.
-
-=item counter
-
-The location of a counter file which should be used instead of
-C<OrderCounter> for this route. It will generate a different value for
-C<mv_order_number> for the route.
-
-=item credit_card
-
-Determines whether credit card encryption should be done for this
-order. Either this or C<encrypt> should always be set.
-
-=item cybermode
-
-If this is set, enables I<CyberCash> for the route. Variables can also
-be set for C<CYBER_CONFIGFILE>, C<CYBER_SECRET>, and all other normal
-CYBERCASH variables. For example:
-
- Route VEN cybermode mau Route VEN CYBER_CONFIGFILE config/vendor1_cfg
- Route VEN CYBER_VERSION 3.2
-
-honly
-
-=item email
-
-The email address(es) where the order should be sent. Set just like
-the C<MailOrderTo> directive, which is also the default.
-
-=item encrypt
-
-Whether the entire order should be encrypted with the
-B<encrypt_program>. If C<credit_card> is set, the credit card will
-first be encrypted, then the entire order encrypted.
-
-=item encrypt_program
-
-The encryption program incantaton which should be used. Set
-identically to the C<EncryptProgram> directive, except that %s will be
-replaced with the C<pgp_key>. Default is C<pgpe -fat -r %s>.
-
-=item errors_to
-
-Sets the C<Errors-To:> e-mail header so that bounced orders will go to
-the proper address. Default is the same as C<MailOrderTo>.
-
-=item increment
-
-Whether the order number should be incremented as a result of this
-result. Default is not to increment, as the order number should
-usually be the same for different routes within the same customer
-order.
-
-=item individual_track
-
-A directory where individual order tracking files will be placed. The
-file name will correspond to the value of C<mv_order_number>. This can
-be useful for batching orders via download.
-
-=item individual_track_ext
-
-The extension that will be added to the file name for
-C<individual_track>. Must contain a period (C<.>), if that is desired.
-
- individual_track_ext .pgp
-
-=back
-
-=over 4
-
-=item pgp_cc_key
-
-The PGP key selector that is used to determine which public key is
-used for encryption of credit cards only. With PGP 5 and 6, see
-appropriate values by using the command C<pgpk -l>.
-
-=item pgp_key
-
-The PGP key selector that is used to determine which public key is
-used for encryption. If C<pgp_cc_key> is set, that key will be used
-for credit card encryption instead of C<pgp_key>. With PGP 5 and 6,
-see appropriate values by using the command C<pgpk -l>.
-
-=item profile
-
-The custom order profile which should be performed to check the order.
-If it fails, the route will not be performed. See C<OrderProfile> and
-C<mv_order_profile>.
-
-=item receipt
-
-The receipt page that should be used for this routing. This only
-applies if supplant is set for the route.
-
-=item report
-
-The report page that should be used for this routing. If C<attach> is
-defined, the contents of the report will be placed in a MIME
-attachment in the main order report.
-
-=item reply
-
-The C<Reply-To> header that should be set. Default is the same as
-C<email>.
-
-If there are only word characters (A-Za-z0-9 and underscore), it
-describes an Interchange variable name where the address can be found.
-
-=item supplant
-
-Whether this route should supplant the main order report. If set, the
-C<AsciiTrack> operation will use this route and the normal Interchange
-order e-mail sequence will not be performed.
-
-=item track
-
-The name of a file which should be used for tracking. If the
-C<supplant> attribute is set, the normal order tracking will be used
-as well.
-
-=item track_mode
-
-A number representing the mode to change either C<track> or
-C<individual_track> files.
-
-=back
-
-An individual item routing causes all items labeled with that route to
-be placed in a special sub-cart that will be used for the order
-report. This means that the C<[item-list] LIST [/item-list]> will only
-contain those items, allowing operations to be performed on subsets of
-the complete order.
-
-Here is an example of an order routing:
-
- Route HARD pgp_key 0x67798115
- Route HARD email hardgoods@akopia.com
- Route HARD reply service@akopia.com
- Route HARD encrypt 1
- Route HARD encrypt_program "/usr/bin/pgpe -fat -q -r %s"
- Route HARD report etc/report_mail
-
- Route SOFT email ""
- Route SOFT profile create_download_link
- Route SOFT empty 1
-
- Route main cybermode mauthonly
- Route main CYBER_VERSION 3.2
- Route main CYBER_CONFIGFILE etc/cybercash.cfg
- Route main pgp_key 0x67798115
- Route main email orders@akopia.com
- Route main reply service@akopia.com
- Route main encrypt 1
- Route main encrypt_program "/usr/bin/pgpe -fat -q -r %s"
- Route main report etc/report_all
-
-To tell Interchange that order routing is in effect, the variable
-C<mv_order_route> is set on the final order submission form:
-
- <INPUT TYPE="hidden" NAME="mv_order_route" VALUE="main">
-
-To set the order routing for individual items, some method of
-determining their status must be made and the C<mv_order_route>
-attribute must be set. This could be set at the time of the item being
-placed in the basket, or have a database field called C<goods_type>
-set to the appropriate value. The following example uses a Perl
-routine on the final order form:
-
- [perl arg=carts interpolate=1]
- my $string = <<'EOF';
-[item-list][item-code] [item-field goods_type]
-[/item-list]
-EOF
- my @items;
- my %route;
- @items = grep /\S/, split /\n+/, $string;
- for(@items) {
- my ($code, $keycode) = split /\t/, $_;
- $route{$code} = $keycode;
- }
- my $cart = $Carts->{'main'};
- my $item;
- foreach $item ( @{ $Carts->{'main'} } ) {
- $item->{mv_order_route} = $route{$item->{'code'}} || undef;
- }
- return '';
-[/perl]
-
-Now the individual items are labeled with a C<mv_order_route> value
-which causes their inclusion in the appropriate order routing.
-
-Upon submission of the order form, any item labeled C<HARD> will be
-accumulated and sent to the e-mail address C<hardgoods@akopia.com>,
-where the item will be pulled from inventory and shipped.
-
-Any item labeled C<SOFT> will be passed to the order profile
-C<create_download_link>, which will place it in a staging area for
-customer download. (This would be supported by a link on the receipt,
-possibly by reading a value set in the profile).
-
-The C<main> order routing will use CyberCash to charge the order, and
-will be completely encrypted for e-mailing.
-
-=head1 Administering Interchange
-
-Some utilities are supplied with Interchange and are located in the
-VendRoot/bin directory:
-
- compile_link Compiles an Interchange vlink or tlink CGI link
- dump Dumps the session file for a particular catalog
- expire Expires sessions for a particular catalog
- expireall Expires all catalogs
- offline Does offline build of the database(s)
- update Does in-place update of the database(s)
- makecat Make catalog
-
-Some example scripts for other functions are in the C<eg/> directory
-of the software distribution.
-
-Some thought should be given to where the databases, error logs, and
-session files should be located, especially on an Internet Service
-Provider (ISP) that might have multiple users sharing an Interchange
-server. In particular, it is recommended that all of the session files
-and logs be put in a directory that is not writable by the user. If
-the directory or file is corrupted, the catalog may crash.
-
-To test the format of user catalog configuration files before
-restarting the server, perform the following test (from VendRoot):
-
- bin/interchange -test
-
-This will check all configuration files for syntax errors, which might
-otherwise prevent a catalog from loading. Once a catalog configures
-properly, user reconfiguration will not crash it, but cause an error.
-It must be loaded when the server is started.
-
-=head2 Starting, Stopping, and Re-starting the Servers
-
-The following commands need to have VENDROOT replaced with the main
-directory where Interchange is installed. If /usr/local/interchange is
-the site's Interchange base directory, the start command would be:
-
-C</usr/local/interchange/bin/interchange>.
-
-Do a C<perldoc VENDROOT/bin/interchange> for full documentation.
-
-To start the server with default settings:
-
- VENDROOT/bin/interchange
-
-It is recommended to issue a restart, otherwise the server will not
-run anew if a server is already running.
-
- VENDROOT/bin/interchange -restart
-
-Assuming the server starts correctly, the names of catalogs as they
-are configured will be displayed, along with a message stating the
-process ID it is running under.
-
-To re-start the server:
-
- VENDROOT/bin/interchange -restart
-
-C<-r> is the same as C<-restart>.
-
-This is typically done to force Interchange to re-read its
-configuration. A message will be displayed stating that a C<TERM>
-signal has been sent to the process ID the server is running under.
-This information is also sent to /usr/local/interchange/error.log.
-Check the error.log file for confirmation that the server has
-restarted properly.
-
-To stop the server:
-
- VENDROOT/bin/interchange -stop
-
-A message will be displayed stating that a C<TERM> signal has been
-sent to the process ID the server is running under. This information
-is also sent to /usr/local/interchange/error.log.
-
-Because processes waiting for selection on some operating systems
-block signals, they may have to wait for HouseKeeping seconds to stop.
-The default is 60.
-
-To terminate the Interchange server with prejudice, in case it will
-not stop, set:
-
- VENDROOT/bin/interchange -kill
-
-=head2 UNIX and INET Modes
-
-Both UNIX-domain and INET-domain sockets can be used for
-communication. INET domain sockets are useful when more than one Web
-server, connected via a local-area network (LAN), is used for
-accessing an Interchange server.
-
-IMPORTANT NOTE: When sending sensitive information like credit card
-numbers over a network, always ensure that the data is secured by a
-firewall, or that the Interchange server runs on the same machine as
-any SSL-based server used for encryption.
-
-If only running a site with one method of communication, use the C<->i
-and C<->u flags.
-
- # Start only in UNIX mode
- VENDROOT/bin/interchange -r -u
-
- # Start only in INET mode
- VENDROOT/bin/interchange -r -i
-
-=head2 User Reconfiguration
-
-The individual catalogs can be reconfigured by the user by running the
-C<[reconfig]> support tag. This should be protected by one of the
-several forms of Interchange authentication, preferably by HTTP basic
-authorization. See C<RemoteUser>.
-
-Use reconfigure from the command line (as the Interchange user) with:
-
- VENDROOT/bin/interchange -reconfig <catalog>
-
-It is easy to manually reconfigure a catalog as an administrator.
-Interchange simply looks for a file C<etc/reconfig> (based in the
-Interchange software directory) at HouseKeeping time. If it finds a
-script name that matches one of the catalogs, it will reconfigure that
-catalog.
-
-=head2 Making the Product Database
-
-The DBM product databases can be built off-line with the C<offline>
-command. The directory to be used for output is specified either on
-the command line with the C<-d> option, or is taken from the
-C<catalog.cfg> directive OfflineDir; C<offline> in the catalog
-directory by default. The directory must exist. The source ASCII files
-should be present in that directory, and the DBM files are created
-there. Existing files will be overwritten.
-
- offline -c catalog [-d offline_dir]
-
-Do a C<perldoc VENDROOT/bin/offline> for full documentation.
-
-=head2 Updating Individual Records
-
-If a site has a very large DBM database that takes time to build,
-consider using the C<bin/update> script to change just one field in a
-record, or to add from a corrections list.
-
-The following updates the products database C<price> field for item
-19-202 with the new value 25.00
-
- update -c catalog -k 19-202 -f price 25.00
-
-More than one field can be updated on a single command line.
-
- update -c catalog -k 19-202 -f price -f comment 25.00 "That pitchfork couple"
-
-The following takes input from C<file>, which must be B<formatted
-exactly like the original database> and adds/corrects any records
-contained therein.
-
- update -c catalog -i file
-
-Invoke the command without any arguments for a usage message
-describing the options.
-
-=head2 Expiring Sessions
-
-If a site has DBM capability and Interchange is using it to store the
-sessions, periodically expire old sessions to keep the session
-database file from growing too large.
-
- expire -c catalog
-
-There is also an C<expireall> script which reads all catalog entries
-in C<interchange.cfg> and runs C<expire> on them.
-
-The C<expire> script accepts a C<-r> option which tells it to recover
-lost disk space.
-
-On a UNIX server, add a crontab entry such as the following:
-
- # once a day at 4:40 am
- 40 4 * * * perl /usr/local/interchange/bin/expireall -r
-
-Interchange will wait until the current transaction is finished before
-expiring, so that this can be done at any time without disabling Web
-access. Any search paging files for the affected session (kept in
-C<ScratchDir>) will be removed as well.
-
-If not running DBM sessions, a Perl script can be used to delete all
-files not modified in the last one or two days. The following will
-work if given an argument of the session directory or session files:
-
- #!perl
- # expire_sessions.pl -- delete files 2 days old or older
-
- my @files;
- my $dir;
- foreach $dir (@ARGV) {
- # just push files on the list
- if (-f $dir) { push @files, $_; next; }
-
- next unless -d $dir;
-
- # get all the file names in the directory
- opendir DIR, $dir or die "opendir $dir: $!\n";
- push @files, ( map { "$dir/$_" } grep(! /^\.\.?$/, readdir DIR) ) ;
- }
-
- for (@files) {
- unless (-f $_) {
- warn "skipping $_, not a file.\n";
- next;
- }
- next unless -M $_ >= 2;
- unlink $_ or die "unlink $_: $!\n";
- }
-
-It would be run with a command invocation like:
-
- perl expire_sessions.pl /usr/local/interchange/catalogs/construct/session
-
-Give it multiple directory names, if there is more than one catalog.
-
-This script can be adjusted or refined as needed. Refinements might
-include reading the file to "eval" the session reference and expire
-only customers who are not members.
-
-=head2 Administrator Permissions
-
-Select which operations each administrator can perform in the back
-office. Each section of the back office can be restricted with
-fine-grained control. An administrator can be given access to view the
-list of all orders, for instance, but not allowed to view details.
-Access to the rows of Interchange's internal tables can also be
-restricted on a per-table basis for each administrator.
-
-=head2 Administrators
-
-The Access Manager allows an administrator to create user accounts or
-groups of users and restrict the use of certain features. This feature
-is especially useful if a company has employees that need the ability
-to check orders, but not change Web content. Note that, by default,
-users in the back office are stored and managed separately from
-customer login accounts. Users can have permissions granted on an
-individual basis, or by group. If a user is a "super-user," all other
-permissions settings will be ignored and the user will be allowed to
-do anything.
-
-=head2 Administrators: Edit Affiliates
-
-Affiliates have the following attributes:
-
-"Affiliate ID" is displayed in the order and traffic statistics along
-with the orders and traffic they produce.
-
-"Affiliate Name" is the name of the affiliate.
-
-"Campaigns" can be used to track traffic from advertising campaigns.
-
-"Join_date" can be used to keep track of when the affiliate signed up.
-
-"URL" is used, if present, to redirect visitors coming from this
-affiliate to a special home page just for visitors from that
-affiliate's site. This should not be the URL of the Affiliate's home
-site.
-
-"Timeout delay" can be used to specify that orders attributed to this
-affiliate must happen within a certain amount of time from the time
-they were referred to the site by the affiliate. Measured in seconds.
-
-=head2 Direct Table Edit
-
-Edit any of Interchange's internal tables. Select a table to edit, or
-search a table for selected rows to edit.
-
-=head2 Direct Table Edit: Select for Table Edit
-
-Having selected a table to edit, a new row can be added, an existing
-row edited, all rows edited spreadsheet-style, or a row deleted.
-
-=head2 File Transfer
-
-Transfer pages, templates, and configuration files to and from the
-Interchange installation. Select C<Pages> to transfer files that will
-be visible to site visitors. Select C<catalog.cfg> to edit the
-configuration file for the store. C<Upload> (send a file to the
-server), C<download> (send a file from the server to a computer),
-C<view>, or C<edit> available files.
-
-=head2 Import/Export
-
-Interchange makes it easy to import and export data to and from a
-commerce Web site.
-
-Use C<Database Upload> to import a tab delimited database of all
-product information to Interchange to make set-up faster and easier.
-C<Database Download> does just the opposite, allowing data to be
-downloaded from Interchange.
-
-Use C<Layout Upload> to upload a site's layout information. Use
-C>Layout Download> to download a site's layout information.
-
-=head2 Logout
-
-This feature will only be useful if there are multiple users in the
-Access Manager. When C<logout> is clicked, a user will be asked to log
-in again. If C<logout> is pressed in error, the user must log in
-again.
-
-=head2 Meta Field Information
-
-Interchange can store meta information for selected columns of tables
-in a site's database. This meta information is used when the user
-interacts with the database. For example, the meta informaton for a
-C<Hide Item> field might specify that a checkbox be displayed when the
-user edits that field, since the only reasonable values are C<on> and
-C<off>. Or, the meta information might specify a filter on data
-entered for a C<Filename> field which makes sure that the characters
-entered are safe for use in a filename.
-
-C<Widget type> specifies the C<HTML INPUT> tag type to use when
-displaying the field in, say, the item editor.
-
-C<Width> and C<Height> only apply to some of the C<Widget type>
-options, for instance the C<Textarea> widget.
-
-C<Label> is displayed instead of the internal column name. For
-example, the C<category> column of the C<products> table might have a
-label of C<Product Category>.
-
-C<Help> is displayed below the column label, and helps describe the
-purpose of the field to the user.
-
-C<Help url> can be used to link to a page giving more information on
-the field.
-
-C<Lookup> can be used when a field is acting like a foreign key into
-another table. In that case, use some sort of select box as the widget
-type, and if referencing multiple rows in the destination table, use a
-multi select box, with C<colons_to_null> as the C<pre_filter>, and
-C<::> as the C<lookup_exclude>.
-
-C<Filter> and C<pre_filter> can be used to filter data destined for
-that field or data read from that field, respectively.
-
-=head1 Interchange Security
-
-=head2 SSL Support
-
-Interchange has several features that enable secure ordering via SSL
-(Secure Sockets Layer). Despite their mystique, SSL servers are
-actually quite easy to operate. The difference between the standard
-HTTP server and the SSL HTTPS server, from the standpoint of the user,
-is only in the encryption and the specification of the URL; C<https:>
-is used for the URL protocol specification instead of the usual http:
-designation.
-
-B<IMPORTANT NOTE: >Interchange attempts to perform operations
-securely, but no guarantees or warranties of any kind are made! Since
-Interchange comes with Perl source, it is possible to modify the
-program to create security problems. One way to minimize this
-possibility is to record digital signatures, using MD5 or PGP, of
-C<interchange>, C<interchange.cfg>, and all modules included in
-Interchange. Check them on a regular basis to ensure they have not
-been changed.
-
-Interchange uses the C<SecureURL> directive to set the base URL for
-secure transactions, and the C<VendURL> directive for normal
-non-secure transactions. Secure URLs can be enabled for forms through
-a form action of C<[process-target secure=1]>. An individual page can
-be displayed via SSL with C<[page href=mvstyle_pagename secure=1]>. A
-certain page can be set to be always secure with the C<AlwaysSecure>
-catalog.cfg directive.
-
-Interchange incorporates additional security for credit card numbers.
-The field C<mv_credit_card_number> will not ever be written to disk.
-
-To enable automated encryption of the credit card information, the
-directive C<CreditCardAuto> needs to be defined as C<Yes>.
-C<EncryptProgram> also needs to be defined with some value, one which
-will, hopefully, encrypt the number. PGP is now recommended above all
-other encryption program. The entries should look something like:
-
- CreditCardAuto Yes
- EncryptProgram /usr/bin/pgpe -fat -r sales@company.com
-
-See C<CreditCardAuto> for more information on how to set the form
-variables.
-
-=head2 Administrative Pages
-
-With Interchange's C<GlobalSub> capability, very complex add-on
-schemes can be implemented with Perl subroutines. And with the new
-writable database, pages that modify the catalog data can be made. See
-C<MasterHost>, C<RemoteUser>, and C<Password>.
-
-In addition, any Interchange page subdirectory can be protected from
-access by anyone except the administrator if a file called '.access'
-is present and non-zero in size.
-
-=head2 Controlling Access to Certain Pages
-
-If the directory containing the page has a file C<.access> and that
-file's size is zero bytes, access can be gated in one of several ways.
-
-=over 4
-
-=item 1.
-
-If the file C<.access_gate> is present, it will be read and scanned
-for page-based access. The file has the form:
-
- page: condition
-
-=back
- *: condition
-
-=over 4
-
-=item
-
-The C<page> is the file name of the file to be controlled (the .html
-extension is optional). The C<condition> is either a literal C<Yes/No>
-or Interchange tags which would produce a C<Yes> or C<No> (1/0 work
-just fine, as do true/false).
-
-The entry for C<*> sets the default action if the page name is not
-found. If pages will be allowed by default, set it to C<1> or C<Yes>.
-If pages are to be denied by default in this directory, leave blank or
-set to C<No>. Here is an example, for the directory C<controlled>,
-having the following files:
-
- -rw-rw-r-- 1 mike mike 0 Jan 8 14:19 .access
-
-=back
- -rw-rw-r-- 1 mike mike 185 Jan 8 16:00 .access_gate
- -rw-rw-r-- 1 mike mike 121 Jan 8 14:59 any.html
- -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 bar.html
- -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 baz.html
- -rw-rw-r-- 1 mike mike 104 Jan 8 14:19 foo.html
-
-=over 4
-
-=item
-
-The contents of C<.access_gate>:
-
- foo.html: [if session username eq 'flycat']
-
-=back
- Yes
- [/if]
- bar: [if session username eq 'flycat']
- [or scratch allow_bar]
- Yes
- [/if]
- baz: yes
- *: [data session logged_in]
-
-=over 4
-
-=item
-
-The page C<controlled/foo> is only allowed for the logged-in user
-B<flycat>.
-
-The page C<controlled/bar> is allowed for the logged-in user
-B<flycat>, or if the scratch variable C<allow_bar> is set to a
-non-blank, non-zero value.
-
-The page C<controlled/baz> is always allowed for display.
-
-The page C<controlled/any> (or any other page in the directory not
-named in C<.access_gate>) will be allowed for any user logged in via
-I<UserDB>. NOTE: The C<.access_gate> scheme is available for database
-access checking if the database is defined as an C<AdminDatabase>. The
-C<.access_gate> file is located in C<ProductDir>.
-
-=back
-
-=over 4
-
-=item 2.
-
-If the Variable C<MV_USERDB_REMOTE_USER> is set (non-zero and
-non-blank), any user logged in via the UserDB feature will receive
-access to all pages in the directory. NOTE: If there is a
-C<.access_gate> file, it overrides this.
-
-=item 3.
-
-If the variables C<MV_USERDB_ACL_TABLE> is set to a valid database
-identifier, the UserDB module can control access with simple ACL
-logic. See USER DATABASE. NOTE: If there is a C<.access_gate> file, it
-overrides this. Also, if C<MV_USERDB_REMOTE_USER> is set, this
-capability is not available.
-
-=back
-
-=head1 Usertag Reference
-
-=head2 email
-
- UserTag email Order to subject reply from extra
- UserTag email hasEndTag
- UserTag email Interpolate
- UserTag email Routine <<EOR
- sub {
- my($to, $subject, $reply, $from, $extra, $body) = @_;
- my($ok);
-
- $subject = '<no subject>' unless defined $subject && $subject;
-
- $reply = '' unless defined $reply;
- $reply = "Reply-to: $reply\n" if $reply;
- if (! $from) {
- $from = $Vend::Cfg->{MailOrderTo};
- $from =~ s/,.*//;
- }
-
- $extra =~ s/\s*$/\n/ if $extra;
- $ok = 0;
- SEND: {
- open(Vend::MAIL,"|$Vend::Cfg->{SendMailProgram} -t") or last SEND;
- print Vend::MAIL
- "To: $to\n",
- "From: $from\n",
- $reply,
- $extra || '',
- "Subject: $subject\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" .
- "From '$from'\n" .
- "With extra headers '$extra'\n" .
- "With reply-to '$reply'\n" .
- "With subject '$subject'\n" .
- "And body:\n$body");