iVend version 1.0a1 of 24 march 1998 
coding by Bill Welliver <hww3@riverweb.com>

these directions are very preliminary and need much work in order to be 
considered anywhere near complete. when all else fails, read the source! :) 

for the checkout process, your best bet is to look at the sample checkout
pages under examples/checkout/*

What is iVend?

iVend is a module for the Roxen Challenger web server which allows electronic
commerce functions to be provided quickly and easily. iVend supports 
multiple stores from a single installation, and provides direct support 
for SQL databases to handle product and order tracking.

iVend is currently in the very early stages of development, and as such 
there will be bugs and missing features. Hopefully with the support of 
alpha and beta testers iVend will grow up to be a mature, powerful and 
useful tool.

What do I need for iVend to work?

* A system running Roxen Challenger version 1.2 or higher.
* An SQL database server supported by Roxen Challenger.
  (iVend was developed using mysql, however other dbms systems should 
  work as well.) 
* A working knowledge of HTML, SQL databases, and Unix.

Installing iVend

1. Untar the ivend distribution file. You should get a directory called 
ivend. This directory contains the module, data files and example store.

2. Add the ivend directory to your module search path using the Roxen 
Administration interface.

3. Choose 'Add Module' to a virtual server.

4. Set the configuration username and password, as well as the module's root
and configuration directory. This is normally ivend/ and ivend/data/
respectively.

5. Save the settings and you're ready to go! iVend will be mounted by 
default on /ivend/, and configuration is located at /ivend/config/.


Adding a new store
------------------

1. Create a directory where all store related files will be kept. You
should copy all of the files and directories in the examples directory to
this new location using "cp -r examples newlocation". This will ensure
that all of the files required for operation are present.

2. Create a database where iVend will store all store related 
transactions. mysql users can use the 'mysqladmin create dbname' command. 
Other systems may vary. Provide select/insert/delete access to a user so 
that iVend can connect and use this db.

3. Create data tables in that database for iVend to use. A sample schema 
file is located in the examples directory called schema.mysql. It's
probably a good idea to start with the example schema and work from
there. These tables can contain as  many and varied fields as you like,
but at least the following must be  present:

products		groups			product_groups

id string key		id string key		group string
name string		name string		product string
image* string		image* string
price decimal(2)	price decimal(2)

The above fields are considered 'special' by iVend, and are expected to 
be present. The presence of additional fields is purely optional, however 
fields such as shipping wights and costs, product descriptions or 
inventory counts may also be useful. 

There are a number of tables that are required by iVend to operate. These
tables are:

customer_info
payment_info
orders
orderdata
sessions
taxrates
status 
type
shipping_*

* field names that begin with image are considered special by iVend. They
indicate images to be stored with groups and products. You can have as 
many image fields as you like, such as thumbnails and fullsize images.

4. Modify the iVend templates using standard HTML, RXML and additional 
IVML (ivend markup language) tags. A listing of IVML tags can be found in 
the section labelled IVML. The minimum files required by ivend to operate 
must be present in each store's data directory and are described below:

index.html -- the default page displayed upon arrival at the store.
groups.html -- this page is used to display all available store groups.
group_template.html -- template used to generate group listings.
product_template.html -- template used to generate individual product listings.
cart.ivml -- handles shopping cart functions.
error.html -- custom error message for iVend errors (optional).

examples of these files are located in the examples directory.

5. Enter the iVend configuration interface by pointing your browser to
http://virtualserver/ivend/config. You will pe prompted for the ivend config
username and password.

6. Click on 'New Store Configuration'. A form will be presented in which 
you should provide the information requested. Note: some information may 
not be nessecary ( such as database users and passwords, etc). When you
are offered an option of one or more Modules (such as shipping or
currency) , you may find the documentation in docs/ helpful.

7. After completing the information, click on the 'Add' button. You should be
returned to the main configuration screen. Click on the 'Save Changes' 
link to save the configuration.

8. You should now be able to point your browser to
http://virtualserver/ivend/storeid where storeid is the id name of the 
store you just created. You should be able to move around the various 
options, although there won't be any groups or products to choose from.

9. Point your browser to http://virtualserver/ivend/storeid/admin. This 
will bring up the iVend Store Administration Page, from which you can add 
and delete products and groups. This is also the central point for 
monitoring orders and store status.

10. Create some new groups, giving each a unique group id. It should be 
noted that currently, groups and products cannot share the same id. You 
can use your browser to add a graphic associated with that particular 
group. Also, that graphic must be in gif format currently.

11. After adding groups, you can add products, placing them in as many 
groups as desired. After addition, products and groups will become 
instantly available in the store.

12. Use the make_key.pike script in the scripts directory to create an RSA
keypair. Make a note of the filename you specified to save the key in.
When you create a store, you'll be asked for this information (the name of
the file containing your keypair).

IVML

The following tags are additions or modifications of existing HTML and 
RXML tags. They are only available within the iVend system. Please note
that checkout tags are discussed in a separate section, as they are
independent of the main iVend engine.

<ivml></ivml>  the grand daddy of the tags. surround all of your pages
that are served by ivend with these tags, otherwise the following tags
won't work. use in place of <html></html>.

<a></a> has been modified to provide session tracking capabilities. 
Additionally, the following attributes have been added:

  cart: generates a link to the store's shopping cart page.
  groups: generates a link to the store's group listing page.
  checkout: generates a link to the store's checkout page.

<ivstatus> when used on product pages, this tag will display information about
additions to a user's shopping cart, and possibly other information from 
the iVend system.

<ivmg> is used to insert an image from a product or group stored in ivend's
database. This tag takes the following attributes:

  field: indicates the field that contains the image you want to display.

<icart></icart> displays the store shopping cart for the current
sessionid. This tag takes the following attributes:

  fields: a comma separated list of additional fields to include in the cart.

<form></form> has been modified to automatically handle session tracking.

<listitems> generates a table of products which fall in a particular
group. The following attributes affect this tag:

  fields: a comma separated list of additional fields to include in the table.
  names: a comma separated list of alternate names for fields included in
     the table.

<category_output></category_output> will repeat the contents the container
once for each record found, replacing values of each field where instances
of the fieldname are surrounded by #s. Similar to formoutput in rxml. This
container takes the following attributes:

  type=products|groups: required. selects what type of records to select.
  restriction=restriction: optional restriction on selection. example:
    restriction="manufacturer='kodak'" must follow sql format rules.
  random: optional, when used with formrotate, the template to be used 
    will be chosen at random from those provided.

<formrotate></formrotate> is used within the category_output container. it
provides multiple templates to rotate through while processing records. if
you provide 2 formrotate containers, every odd record will be processed
using the contents of the first container and every even record will be
processed using the second container as the template.


Notes about data security
-------------------------

As with any application of this nature, one must be extremely sensitive
when designing and implimenting electronic commerce solutions. Improperly
implimented designs and security can open holes through which data, such
as account numbers or addresses might be compromised. 

iVend was written with this in mind, and therefore will use, if available,
the cryptography toolkit built into pike to secure sensitive data.
Sensitive data is never stored in the clear in databases or transmitted in
the clear over unsecure lines. 

The encryption methods used by iVend include RSA public key encryption.
This means that access to data encrypted with an entity's public key must
be made through the corresponding private key. For this reason, it is
*highly* recommended that the two keys be kept in separate directories,
preferably on different systems. This way, if the system running iVend is
compromised, it would not be possible to decrypt secured information
because the required private key would not be present.

*NOTE* Currently both private and public keys are held in the same file.
You should make sure that this file is readable only a trusted user.

Email Notification
------------------

Automatic email messages are sent by iVend following certain events. iVend
checks the notes directory of your store for the presence of text files.
Here is a list of the text files that iVend looks for:

notify.txt: sent to the store administrator when a new order is confirmed.

These messages are sent to the individual who places an order:

confirm.txt: sent after confirmation of a new order.
rejpay.txt: sent when payment information is rejected.
ship.txt: sent when all or part of an order is shipped.

Checkout Tags
-------------

the subtotal is the sum of all taxable and nontaxable items ( including
shipping if taxable ). discounts and salestax are calculated from the
subtotal. All checkout tags function within the checkout container,
<checkout></checkout>.

generate_form		generate a form from the database
  table=tablename	this is the table to get data for.
  hide=field1,field2    hide these fields in the list.

confirmemail
  field=fieldname	name of field containing email address to check.

salestax		added as a lineitem
  locality=fieldname	name of field in billing address to determine
			taxrate.

discount
  percent=percentage	percent discount of subtotal, which is then
			removed from the subtotal.
grandtotal
			sum of all lineitems

showorder		show all items in this order.

shipping		show the shipping charges

shippingtype		show the shipping type

addentry		add the data from the previous form.
  encrypt=field1,field2..  encrypt these fields using rsa.

cardcheck		check credit card number
  cardnumber=field	use this field name for card number
  cardtype=field	use this field name for card type (AMEX,VISA,etc)
  expdate=field		use this field name for expiration date

Other Stuff
-----------

The database schema to use currently is located in examples/schema.mysql

If the form generator finds an enum type (must be using patched mysql for
this), it will look for values in a file called 
	storeroot/db/tablename_fieldname.val ...

The iVend Main Index
--------------------

If you place a file called index.html in the iVend data directory (as
specified in the roxen config interface), and change "CreateIndex" to yes
in iVend's global variables, that file will be returned upon an access to
the ivend root mountpoint (such as /ivend/). This is useful for providing
a list of lists for all stores provided by a particular module. 

To aid in the generation of a list of lists, a special container called
<ivindex></ivindex> is available in this page. It works much like the 
formoutput container in that field names from store configurations that
are surrounded by #s like this: #name# will be replaced with that store's
value. For a better example, see the file data/index.html.
