QuickStart

Interchange V4.6.2

Copyright (C) 1996-2000 Akopia, Inc. <info@akopia.com>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version. See the GNU General Public License for more details.
The GNU General Public License is distributed with this program; if not,
write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA  02111-1307  USA.


Welcome to Interchange!

--------------------------------------------------------------

                        QUICK START

Intro
    This document is a subset of the complete Interchange documentation.
    Most of the information contained here is is duplicated in the general
    Interchange documentation. This document is designed to give you a
    starting point. 

What happened to Minivend and Tallyman?
    First there was Minivend, the open source e-commerce system begun by
    Mike Heins about five years ago. Thousands of sites are using it,
    and it evolved into a powerful and versatile tool over the years.
    Separately, Akopia was started by an experienced e-commerce development
    team with the goal of making a sophisticated open source e-commerce
    system that's intuitive and easy to use. Minivend was very feature
    rich, but difficult to learn and use. Tallyman was intuitive, and
    had great content management features, but lacked many of Minivend's
    capabilities. So we joined forces, and Interchange is the result.
    Interchange 4.6 replaces both Tallyman and Minivend. Minivend users
    will find the upgrade to Interchange relatively painless. Tallyman
    users will not be as lucky. Keep an eye on the web site and the
    mailing list for more details. In order to preserve compatibility,
    the name "minivend", and prefixes like "mv_" and "MVC_" will still
    appear in source code and configuration files.

Requirements:

        Perl 5.005 or higher
            Interchange is written (almost) entirely in Perl. No extra
            modules are required to work, but some may be necessary to
            extend Interchange's functionality.

        Web Server
            Any web server with which you are familiar and has CGI
            capabilities should work. Apache is most commonly used.
            The install scripts assume Apache is installed and running.

Install Walkthrough

		**The installation procedure described here applies to the tarball installation only.**
        Make sure that you have user permissions to do the following:
             Write on the catalog install directory
             Read on the Apache config file (if possible)
             Write on the cgi-bin for the web server

        Unpack the distribution:
            gzip -dc interchange-4.6.2.tar.gz | tar xvf -

        Run the configuration script:
            ./configure

        You will be asked to enter the path for the install directory
        for the Interchange distribution. If you have the Storable
        module installed, you may be asked how you would like to use
        it. Choose the default.

Demo Store Install Walkthrough

		**The installation procedure described here applies to the tarball installation only.**
     We'll be walking the whole install and setup process. The text
     that you'll see during the install will be displayed with <-- next
     to it. What's marked with --> is what you'll need to enter in.

     In order to begin, you will need permissions on your server for
     the following:
        Write on the catalog install directory
        Write on the Interchange install directory
        Write on the cgi-bin directory
        Write on the httpd document root

     If you don't know what any of this means, you might as well
     stop now. Akopia can set you up with a server with Interchange
     pre-installed and you won't have to know anything about server
     permissions or root access. See the web site for more details.

     To begin:

     Change to the directory in which Interchange is installed:
            cd /home/user/interchange
     Run the makecat script
            bin/makecat

     You will be asked a series of questions at this point. If you
     want to change the answers to any of these questions later, it
     can be done through the editing of the configuration scripts.
     The installer does its best to pick defaults that will work best
     with your configuration. Most of the time the default responses
     will work just fine.

<--Select a short, mnemonic name for the catalog. This will be
<--used to set the defaults for naming the catalog, executable,
<--and directory, so you will have to type in this name frequently.

<--NOTE: This will be the name of 'vlink' or 'tlink', the link CGI
<--program. Depending on your CGI setup, it may also have the
<--extension .cgi added.

<--If you are doing the demo for the first time, you might use "construct".

    This will be the name of your catalog. The installer will use this
    name as the unique identifier for this catalog. This will be the
    name of the cgi script that intercepts interchange requests. It
    will also be used as the default for the directory in which to
    store catalog files.

<--Catalog name?
-->construct

    I chose "construct" as the catalog name in this case.

<--makecat -- Interchange catalog installation program.

<--*** We will be making a catalog named 'construct'. ***


<--New configuration file '/home/sonny/akopia/tmp/interchange/etc/makecat.cfg'

<--If you are using the Apache or NCSA web server, Interchange can set
<--some of the default parameters for you by reading the file.

<--If you use the Netscape Enterprise server or other non-NCSA HTTP server,
<--enter 'none' -- the information, if any, will not be useful.


<--Try using the UP arrow at some of the prompts -- you have the
<--Term::ReadLine module installed, and Interchange may find some
<--default values in your HTTP server configuration file.  You can
<--cycle among them with the UP and DOWN arrows.

<--Enter path to httpd.conf file: /usr/local/apache/conf/httpd.conf
-->/usr/local/apache/conf/httpd.conf

<--This demo configuration sometimes requires root permissions,
<--depending on your ISP.  It needs to copy a few files to the CGI
<--and HTML directories.

<--You must either have your own CGI directory, or be able to run
<--a CGI with an extension like '.cgi'.

<--If you will be operating only on directories owned by the
<--user you are running this as, you will be able to do
<--everything.


<--Since there was no master configuration file, we will ask
<--some questions to help set initial defaults for making this
<--and future catalogs.

<--Interchange can set many of the defaults for you if it knows the server
<--name that is going to be used.

<--Enter the default server that should be used. This is only a default, to
<--determine the *first* one that will be looked at -- you will be given
<--a choice of all available servers.

<--There is a "history" mechanism that will allow you to use the up
<--and down arrows on your terminal (assuming you have a standard terminal)
<--to cycle between possible choices.  This should contain the available
<--servers.

<--Default server? localhost
-->localhost

    It is the name at which the web server is receiving connections.
    Interchange will also be running on this server.


<--We need to know if all of your CGI programs are run as a file ending
<--in .cgi or some other extension, or whether you have your own personal
<--CGI directory.

<--Do you have a CGI directory? y
-->y

<--# The location of the normal CGI directory. This is a
<--# file path, not a script alias.
<--#
<--# If all of your CGI programs must end in .cgi, this is
<--# should be the same as your HTML directory.
<--#

<--CgiDir? [/usr/local/httpd/cgi-bin]
-->/usr/local/httpd/cgi-bin

<--#
<--# The URL-style location of the normal CGI directory.
<--# Only used to set the default for the CgiUrl setting.
<--#
<--# DO NOT PUT A TRAILING /.
<--#
<--# http://www.virtual.com/cgi-bin/prog
<--#                       ^^^^^^^^
<--#
<--# If you have no CGI-bin directory, (your CGI programs end
<--# in .cgi), leave this blank.
<--#


<--CgiBase? /cgi-bin
-->/cgi-bin

    This is the URL to the cgi program for your catalog (example in
    this case).  This would be the script-alias in the httpd.conf set
    up for your cgi-bin.


<--# The base directory for HTML for this (possibly virtual) domain.
<--# This is a directory path name, not a URL -- it is your HTML
<--# directory.
<--#

<--DocumentRoot? /home/ic_user/public_html
-->/home/ic_user/public_html

	This is the directory path to your html document root.  A number of
  	static elements of your catalog will be stored here.


<--# This is a directory path name (not a URL) where the administration user
<--# interface images from share/ should be copied to. These will normally be
<--# shared by all catalogs. Often this is the same as your DocumentRoot.
<--#

<--ShareDir? /home/ic_user/public_html
-->/home/ic_user/public_html

	If you wish to use the same admin interface for all of your catalogs, the
	common files can be shared in this directory.

<--# The URL base for the administration user interface images. Sets the
<--# Variable UI_IMG directive in the UI configuration file, ui.cfg.
<--# This is a URL fragment, not an entire URL. If you set ShareDir to be
<--# the same as DocumentRoot, this would just be a '/'.
<--#
<--#         <IMG SRC="/akopia/ui/bg.gif">
<--#                   ^
<--#

<--ShareUrl? /
-->/

<--# The directory where the Interchange software is installed.
<--#


<--VendRoot? /home/ic_user/interchange
-->/home/ic_user/interchange

<--#
<--# DIRECTORY where the Interchange catalog directories will go. These
<--# are the catalog files, such as the ASCII database source,
<--# Interchange page files, and catalog.cfg file. Catalogs will
<--# be an individual subdirectory of this directory.
<--#

<--BaseDir? /home/ic_user/catalogs
-->/home/ic_user/catalogs

<--# The user name the Interchange server runs under on this machine. This
<--# should not be the same as the user that runs the HTTP server (i.e.
<--# NOT nobody).
<--#


<--InterchangeUser? ic_user
-->ic_user

<--#########     END BASE CONFIGURATION      #########
<--
<--######### BEGINNING CATALOG CONFIGURATION #########

<--During many of the following operations, defaults are placed in
<--a buffer for you.  You may use the up and down arrows to toggle
<--between the defaults.

<--If you made a mistake on a *previous* entry and realize that
<--in a later one, if you enter ONLY an @ sign and press return you
<--should be returned to the previous step.

<--# The server name, something like: www.company.com
<--#                                  www.company.com:8000
<--#                                  www.company.com/~yourname
<--#
<--Server name? [localhost]
-->localhost

<--# The type of demo catalog to use. Standard types
<--# distributed are:
<--#
<--#    construct   -- 'Construct Something' demo store
<--#
<--# If you have defined your own custom template catalog,
<--# you can enter it's name.
<--#
<--# If you are new to Interchange and not a sophisticated web designer,
<--# use "construct" to start with.

<--DemoType? [construct]
-->construct

    Currently "Construct Something" ('construct') is the only included
    demo. The Interchange Developer Resource at http://developer.akopia.com/
    has others, and a future release of Interchange will include the
    'foundation' demo which will be much simplified to assist you in building
    your own store.


<--# The email address where orders for this catalog should go.
<--# To have a secure catalog, either this should be a local user name and
<--# not go over the Internet -- or use the PGP option.
<--#


<--MailOrderTo? ic_user
-->orders@construct.net

    The construct catalog is designed to email the orders once they are
    made to the person responsible for handling orders.

<--# Where the Interchange files for this catalog will go, pages,
<--# products, config and all.  This should not be in HTML document
<--# space! Usually a 'catalogs' directory below your home directory
<--# works well. Remember, you will want a test catalog and an online
<--# catalog.
<--#


<--CatRoot? [/home/ic_user/catalogs/example]
-->/home/ic_user/catalogs/example

    This is where the catalog config files and working data go. The
    default location is a good place for this.


<--# The location of the normal CGI directory. This is a
<--# file path, not a script alias.
<--#
<--# If all of your CGI programs must end in .cgi, this is
<--# should be the same as your HTML directory.
<--#

<--CgiDir? /home/ic_user/public_html/cgi-bin

    A file with your store's name will go into the cgi-bin dir. This
    program (vlink or tlink) will provide the bridge between the web
    server and the Interchange server.


<--# The URL location of the CGI program, without the http://
<--# or server name.
<--#
<--# http://www.virtual.com/cgi-bin/prog
<--#                       ^^^^^^^^^^^^^
<--#
<--# http://www.virtual.com/program.cgi
<--#                       ^^^^^^^^^^^^
<--#


<--CgiUrl? /cgi-bin/construct
-->/cgi-bin/construct

    This is the URL to the cgi program for your catalog (construct in
    this case). This would be the script-alias in the httpd.conf set
    up for your cgi-bin.

<--#
<--# Additional URL locations for the CGI program, as with CgiUrl.
<--# This is used when calling the catalog from more than one place,
<--# perhaps because your secure server is not the same name as the
<--# non-secure one.
<--#
<--# http://www.secure.domain/secure-bin/prog
<--#                         ^^^^^^^^^^^^^^^^
<--#
<--# We set it to the name of the catalog by default to enable the
<--# internal HTTP server.
<--#


<--Aliases? /construct
-->/construct

    This one is "beyond the scope of this document." For the purposes
    of getting started, this option can be safely ignored. For those
    who really want to know what it is for right now, see the
    documentation for interchange.cfg.


<--# The base directory for HTML for this (possibly virtual) domain.
<--# This is a directory path name, not a URL -- it is your HTML
<--# directory.
<--#


<--DocumentRoot? [/usr/local/httpd/htdocs]
-->/usr/local/httpd/htdocs

<--# Where the sample HTML files (not Interchange pages) should be
<--# installed. There is a difference.  Usually a subdirectory of
<--# your HTML directory.
<--#


<--SampleHtml? [/usr/local/httpd/htdocs/construct]
-->/usr/local/httpd/htdocs/construct

    Interchange will create a directory under the html document root in
    order to store the static html pages for the demo catalog.

<--# Where the image files should be copied. A directory path
<--# name, not a URL.
<--#


<--ImageDir? [/home/sonny/public_html/construct/images]
-->/home/sonny/public_html/construct/images

    Additionally, a place for the images.

<--# The URL base for the sample images. Sets the ImageDir
<--# directive in the catalog configuration file. This is a URL
<--# fragment, not a directory or file name.
<--#
<--#         <IMG SRC="/simple/images/icon.gif">
<--#                   ^^^^^^^^^^^^^^
<--#


<--ImageUrl? [/construct/images]

    This is the URL for the images stored in the directory created
    above. Interchange needs this in order to create <IMG> tags
    for the catalog's dynamic pages.


<--Interchange can use either UNIX- or internet-domain sockets.
<--Most ISPs would prefer UNIX mode, and it is more secure.

<--If you already have a program there, or use a common program
<--and the FullURL directive, select NONE. You will then need
<--to copy the program by hand or otherwise ensure its presence.

<--INET or UNIX mode? [UNIX]
-->UNIX

    Again, this is outside of this document's scope. UNIX sockets
    will work just fine.

<--Do you use CGIWRAP or SUEXEC? [n]
-->n

    If you don't know the answer, no should be the right answer.

    Does some stuff.

<--Your company name: .....................Construct Something

<--Interchange has a workable internal database, but many things will
<--work better (and a few worse) if you use a SQL database. Interchange
<--can configure MySQL and Postgres in a test configuration.

<--Set to 1 if you want to use MySQL or Postgres: ..
-->0

    For the purposes of this document, we are going to use the
    Interchange internal database. Consult the documentation for
    information about using your SQL database of choice.

<--You can use Interchange's companion configuration
<--interface, to do upload/download of files, manipulation of
<--the database, reconfiguration of the catalog, and much more.

<--To enable the UI, you will need a "super-user" account
<--name that has full access.

<--The initial password is "pass". CHANGE IT! You can do this
<--by going to the admin menu and selecting the superuser and
<--then "Change password".

<--Account name that will control this catalog: ..ic_user
-->ic_user
<--Administrative password: ...............pass
-->pass


<--Found system commands to run.

    does some more stuff

<--Found additional system commands to run.

<--To enable image upload feature, you need to make a symbolic
<--link of the image base directory into your catalog directory.

<--uct/images /home/sonny/akopia/catalogs/construct1"? ..y
-->y

    Say yes here if you would like to be able to upload images
    into Interchange.

<--Add catalog to interchange.cfg? y

    This will make your catalog available to the interchange server.
    Now you're done with the catalog configuration.


    That's it. The demo store should be installed and ready to go. Now
    you want to start the Interchange server:

        /home/user/interchange/bin/interchange

    You should see something like this:

Low traffic settings.
Calling UI....
....UI is loaded....
Interchange V4.6.2
Configuring catalog example...done.
Interchange server started in INET and UNIX mode(s) (process id 22200)

    At this point the Interchange server should be running and waiting
    for connections.

Show off demo store
    Some day we will expand this section.

The administrative side
    The administrative site has built-in context sensitive help. If
    you want more detailed information on how a particular section
    works, click on the "help" link in the upper right hand corner of
    the screen. A help window will pop up and explain what's going on
    in that particular area.

    How to get there
        Go to http://localhost/cgi-bin/construct/admin/login.html
        changing whatever is necessary for your setup. If you see an
        Akopia Interchange login prompt, that's a very good sign it
        worked. If not, that is a good sign that it didn't work.

    Logging In
        When you installed the store, you set up a "super-user" and
        password for control of the administrative section. This is
        it; enter the correct information and click login.

    The main page
        This is the front admin page. From here you can access the
        other pages of the admin section.

        Orders
            From here you can view a summary of all of the orders as
            well as select a particular order to view in complete
            detail. This is the command center for viewing and
            managing the site's transaction information.

            Archive Orders
                Archive (remove from the active list, but store for future
                reference) orders which have been processed.

            Enter Order
                Enter a new order into the Interchange system.

        Customers
            Customer information can be managed from this interface.
            You can deactivate accounts or delete customers as well as
            view and modify information about each one.

            Active Customers
                Show active customers

            Inactive Customers
                Show inactive customers

            Create New Customer
                Enter a new customer into the Interchange system.

        Items
            From this page, you can manipulate your product data, as well
            as merchandising and inventory.

            Item List
                List items in product database.

            Create New Item
                Add an item to the Interchange system.

        Content
            This section allows you to upload, download, edit, and create
            site content.

            Page Edit
                Edit an existing page.

            File Transfer
                Upload and download Interchange and catalog files.
            Page Edit
                Edit an existing page.

        Design
            Configure the site design for your catalog.

            Site Layout
                This is the layout editor which allows you some control over the
                layout of the site, allowing you to organize logical categories
                for pages and items.

             Search Builder
                Interchange searches can be constructed and executed from
              this interface. This can be used for generating actual
                code for searches or just doing something you thought up
                but don't have an interface for.

            Button Builder
                This interface is for generating buttons and links to
                Interchange components.

            Generate Static
                Interchange can be configured to generate any of your catalog
                pages statically so that they are not parsed each time they
                are requested.

            File Transfer
                Upload and download Interchange and catalog files.

            Page Edit
                Edit an existing page.

        Merchandising
            Allows you to set up and manipulate quantity pricing, up-sell,
            promotions, and affiliates.

            Product Merchandising
                Control merchandising parameters for products.

            Affiliates
                The affiliates feature lets referral orders from other web
                sites be flagged and recorded for the purposes of reimbursing
                the affiliate or simply for research purposes. Here, you
                can add or remove affiliates.

            Generate "Others who" . . .
                Generate links for "Others who bought this product" products.

        Reporting
            Interchange keeps statistics on both order information and
            web site traffic.

            Orders
                Report on order stats

            Traffic
                Report site traffic stats

            Custom
                Run custom reports on your catalog.

        Administration
            Various site/catalog administration tools.

            Info
                Interchange system information

            Tax
                Tax definitions can be set up here.

            Shipping
                Shipping options and tables are configured and manipulated
                from this interface.

            Payment
                From this interface, you set whether your accept or don't
                accept each payment method.

            Access
                Control administrative access for Interchange users with
                varying degrees of granularity.

            Preferences
                A high-level interface to some Interchange system variables
                used to control the environment.

            Knar Editor
                The Knar is an acronym for "Knar's not a registry." That
                is in fact exactly what it is: a random collection of
                Interchange system variables and flags. This is a low level
                interface to control the environment.

                Edit
                    Modify Knar variables.

                Import Data
                    Import data into the Interchange tables.

                Export
                    Export data from the Interchange tables.

                Spreadsheet
                    A spreadsheet-format editor for Knar variables.

                New Entry
                    Create a new variable.

                Re-Select Table
                    Link to the table configurator.

            Table
                Tables can be imported into or exported from the interchange
                database, as well as viewed and edited. Some of the tables
                you might want to import or export: inventory, pricing,
                shipping info.

            Apply Changes
                Updates the Interchange system to apply your changes. If
                you change a tax rate or a shipping option, for example, it
                won't affect the live site until you apply changes.



Interesting files
    interchange.cfg
    catalog.cfg

In future versions of this document:

Where everything went
What's going on underneath the hood?
Anatomy of a catalog
Anatomy of an Interchange page