forked from interchange/interchange
-
Notifications
You must be signed in to change notification settings - Fork 0
/
QuickStart
745 lines (540 loc) · 24.6 KB
/
QuickStart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
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