[ic] Getting started...

[Chris Wenham]

On Monday 09 June 2003 03:17 pm, Patrick Galbraith wrote:

> What is the overall setup of the codebase? Is it mod-perl or CGI? 

 It's a daemon that runs all the time and talks through "stubs" that are 
ordinary CGI scripts. The "store.cgi" it puts in your document root is only a 
tiny program that relays get/post to and from the Interchange daemon via 
either a Unix or IP socket. 

 For a performance boost, someone wrote mod_interchange to replace the stubs. 
You still need to have the main Interchange daemon running, but 
mod_interchange can tie a <Directory> in Apache to that daemon.

> What is the design of
> Interchange? 

 In a nutshell it's a template processor that comes with a lot of functions, 
defaults and demos that lean towards making shopping-cart sites. It 
understands a turing complete macro language called IML (Interchange Markup 
Language), which itself revolves around tags in square brackets to set them 
apart from HTML tags.  Examples:

 [data table="products" field="price" key="sku-4252"]

 [data] is the tag for reading or writing single fields of data from a table 
in the database. In this case, the table is called "products", the field it 
will fetch from is called "price", and the value it'll search for in the 
index column is "sku-4252". 
 For most tags, Interchange also supports a relaxed syntax based on order, so 
the above could also be written as:

 [data products price sku-4252]

 Some tags are containers. Here's an example of a branching statement:

 [if scratch foo]
	<p>You have foo in your coffee.</p>
 [else]
	<p><a href="[area foo]">Click here to learn more about foo.</p>
 [/else]
 [/if]

 Session-persistent variables are stored in a scratch space, accessed in some 
tags with either the keyword "scratch" (as above), or with the [scratch] tag.

 IML can be extended with user defined functions (tags) at two different 
security levels: UserTags that run in perl's Safe mode and are defined in the 
catalog.cfg file, and GlobalTags that run at maximum privileges and are 
defined in the central interchange.cfg file. 

 Interchange is flexible with databases. It supports GDBM and BerkleyDB for 
flat files, but it can also talk to any SQL server that Perl's DBI can. It 
comes with sample configurations and table definitions for MySQL, Postgres, 
and Oracle.
 Regardless of what database format you use, Interchange will also always keep 
a shadow database of all tables in tab separated flat files. It can re-create 
tables from this shadow database whenever the main database file/table is 
missing. That means if you delete the .db file, or drop the SQL table and 
delete the .sql file, then Interchange will automatically recreated them the 
next time you restart it.
 I don't know why it does this, though. I think it makes it easier to do 
full-table keyword searches.
 
> What components are there from a high level? 

 There's the main tag parsing libraries (interpolate.pm is the biggie), and 
then there are some modular libraries for handling product options and 
payment methods.

> What
> modifications, if any, do I need to put in my httpd.conf? 

 If you're running one of the .cgi stub programs, then you only need to make 
sure ExecCGI is set for that directory. If you want to use mod_interchange, 
then it's simple to install and you just need to add a <Directory> block to 
your site's config.

> How can I run
> this site as a virtual domain, or run any additional site as a virtual
> domain? 

 The main Interchange daemon can run as many separate catalogs as your 
resources allow. The catalog apropriate for each get/post request is 
identified rather crudely from the pathname of the URL, as configured in 
interchange.cfg, but running a virtual domain is as simple as configuring any 
other virtual domain in Apache. 

 The only interesting thing about the way Interchange likes to store files is 
that the HTML for all the pages are stored outside of Apache's document root. 
Images and the stub .cgi are the only parts you need to have within the 
docroot. The Interchange daemon process needs permission to read the files it 
finds in your ~/catalogs/store tree. 
 That was done, of course, so that Apache couldn't read unparsed pages with 
IML in them, nor could it read any configuration or database file.

> How can I set up the admin password? Why does the user database
> store passwords in clear text?

 I believe Interchange can be configured to encrypt user passwords, but by 
default (specifically, by default in _the demo catalog_ it ships with) it 
doesn't encrypt so it can support a feature to mail forgotten passwords to 
their users. 

 Admin accounts and passwords are stored encrypted and in a separate table. It 
uses perl's crypt function, so you can use that to reset the admin password.

Regards,

Chris Wenham
www.synesmedia.com