Catalog-Building Tutorial ========================= iccattut.1.22 (Draft) 1. Purpose ========== The purpose of this document is to guide you through constructing a simple Interchange catalog from scratch. The demo catalog that ships with Interchange is quite complex since it highlights some of the many capabilities that Interchange offers. As a template for your own catalog, the demo can be an intimidating place to start if your purpose is to learn. The simple catalog you create using this tutorial should give you a feel for the basic Interchange system. It should also be considered a stepping stone to a more complete and functional e-commerce system built with Interchange. The tutorial relies as much as possible on default settings to accentuate how Interchange works. It will use as few of Interchange's capabilities as possible, while still building a usable store. The resulting site will be simple but usable. The value of this tutorial is in the instruction that occurs along the way. It is recommended that you create the files used in this tutorial yourself. You will learn more by creating the directory structure and using your favorite text editor to create files in the proper places on your own system as they are discussed. 2. Before you begin =================== This section explains the initial set up tasks that must be completed before you can begin building your simple e-commerce site. 2.1. Install Interchange and the demo catalog --------------------------------------------- The easiest way to get Interchange and the demo set up is through an RPM install on the Red Hat Linux or Linux Mandrake operating systems. You can also get Interchange by unpacking an Interchange tarball or checking out a copy of the CVS repository and doing a manual installation. These installations can be done either as a regular user or as root, installing for a special Interchange user. You must also know what type of installation you ran so you know where to place the various files created. Before proceeding, verify that Interchange is properly installed. Also, keep in mind which type of installation you did: o RPM (RPM Package Manager) install o Manual install as root o Manual install as regular user Note: After installation, makecat should be run to build your catalog. For information on installing Interchange and building your catalog using makecat, see the Interchange Getting Started Guide. Do not to continue with this tutorial without a working demo catalog. Installing the demo catalog set up the Interchange global configuration file interchange.cfg, which resides in the Interchange software directory. Also, it compiled the link program for your specific server and placed the executable program in your cgi-bin directory. This is necessary for your catalog to run properly. 2.2. The Interchange operating system user ------------------------------------------ If Interchange was installed as a regular user, that will be the user Interchange runs as. If Interchange was installed as root or from an RPM, you need to know the name of the separate Interchange user. The Interchange daemon will not run as root, and should not run as the web server user (usually 'apache', 'www', 'httpd', or 'nobody'). If Interchange was installed from the RPM, or with the default source installation settings, the username is interch. If you selected a different user name, you will need to know what it is. 2.3. Important directories -------------------------- In order to complete this tutorial you will need to know the location of each of the following directories and have write permissions on them: o Interchange software directory o RPM install: /usr/lib/interchange o Manual install as root: /usr/local/interchange o Manual install as regular user: /home/username/interchange o Catalogs directory o RPM install: /var/lib/interchange o Manual install as root: /usr/local/interchange/catalogs o Manual install as regular user: /home/username/catalogs o cgi-bin directory o RPM install or source install as root: /var/www/cgi-bin o Manual install as root (locally installed web server): /usr/local/htdocs, /opt/www, ... o Manual install as regular user: /home/username/public_html (with .cgi extension) Note: The installation of Interchange is very flexible and the file locations on your system may vary, depending on how your system was set up. It is recommended that you not proceed until you are sure you have this information and the necessary permissions to write to these directories. 2.4. Your catalog URL --------------------- Finally, you need to know the URL to access your store from a web browser. Again, this can vary depending on how your web server has been set up. But, assuming a common setup of the Apache web server, your URL should be one of the following: o Root or RPM install: http://localhost/cgi-bin/tutorial/pagename o Manual install as user: http://localhost/~username/tutorial.cgi/pagename If you aren't running your web browser on the server where Interchange is running, you need to substitute your server's host name (for example: machine.domain.com for localhost) where mentioned. Note: It is recommended that you use the real machine name instead of localhost. The standard for cookies specifies that they can only be set when a domain name has at least two dots in it. If you use localhost, you will lose session information if you leave catalog, since the session ID is passed only as part of the URL. 2.5. Starting or restarting Interchange --------------------------------------- When you make changes to the configuration files you need to restart the Interchange server. How this is done depends on how you installed Interchange: o RPM install as root: /usr/sbin/interchange -r o Manual install as Interchange user: /usr/local/interchange/bin/interchange -r o Manual install as root: su interch -c '/usr/local/interchange/bin/interchange -r' o Manual install as regular user: ~/interchange/bin/interchange -r Find the right command for your system and remember it, since you will need to restart Interchange a few times during the tutorial. 2.6. Tutorial assumptions ------------------------- Because it is impossible to cover all scenarios, this tutorial assumes that you installed Interchange on Red Hat Linux from the RPM packages. This creates the following settings: o Interchange software directory: /usr/lib/interchange o Catalogs directory: /var/lib/interchange o cgi-bin directory: /var/www/cgi-bin o Interchange user: interch o Demo catalog name: foundation o Demo catalog URL base: http://localhost/cgi-bin/foundation o Tutorial catalog name: tutorial o Tutorial catalog URL base: http://localhost/cgi-bin/tutorial o Tutorial catalog directory: /var/lib/interchange/tutorial If you did not install with these settings, substitute the correct values for your system when these settings are mentioned in the tutorial. 3. Building Your Catalog ======================== This section describes the pages and directories that need to be established to create a properly functioning catalog. 3.1. Create the link program ---------------------------- You need to make a copy of the demo link program in your cgi-bin directory and name it tutorial. The demo link program has the same name as your demo catalog, usually foundation. The link program links the Interchange daemon with your web server. Make sure that it has the same owner and file permissions as the one you copied from. The set-UID bit is especially (unless you installed as a regular user). Normally you will need to be root to have write permissions in the cgi-bin directory. Type this command as root while in your cgi-bin directory: cp -p foundation tutorial If everything is working correctly, typing ls -l should describe your files roughly like this: -rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 foundation -rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 tutorial 3.2. Create the tutorial catalog directory ------------------------------------------ As root, create a subdirectory named tutorial under your catalogs directory (probably /var/lib/interchange/). This is where all of the catalog-specific files will go. It needs to be readable, writable, and executable by the Interchange user. This will be referred to as your catalog directory. Type the following while in the catalogs directory to create the tutorial subdirectory: mkdir tutorial chown interch.interch tutorial chmod 770 tutorial 3.3. Become the Interchange user -------------------------------- You should be able to do everything you need to do as the 'interch' user for the rest of this tutorial. So you can switch to that user now (su - interch). If you installed Interchange from the RPM, the user interch probably doesn't have a password. You'll have to set it with a command such as passwd interch while root. 3.4. Go to the tutorial catalog directory ----------------------------------------- Change to the catalog directory with the 'cd' command. For the rest of this tutorial, all file locations will be given relative to the tutorial catalog directory. For example, pages/ord/basket.html would actually be /var/lib/interchange/tutorial/pages/ord/basket.html or the equivalent on your system. The only exception is interchange.cfg, which is in the Interchange software directory. Note: To improve clarity, we will append a trailing slash to directory names to clearly distinguish them from file names. (Similar to the output of the ls command with the -F option.) 3.5. Create the session directory --------------------------------- You need to create the session directory where Interchange saves information on each visitor's browsing session. If you do not have this directory, your catalog will not work. This directory is called session/ and goes under your catalog directory. Type mkdir session to create this directory. 4. Configuration files ====================== Interchange configuration is controlled by a number of directives, which are specified in two files. Global configuration directives go in interchange.cfg in the Interchange software directory. Catalog-specific configuration directives go in catalog.cfg in the catalog directory. A complete directive consists of the directive name followed by whitespace-separated parameters. Any number of spaces or tabs can be between the directive and its options, but the directive and its options must be on the same line. The directive is case-insensitive, but it is recommended that you use it consistently for readability. You can insert blank lines or comment lines (lines where the first non-blank character is '#') throughout the configuration files to improve readability. The order the lines appear in is significant, but unimportant for the simple catalog you are creating. For the next part, access your text editor (for example, vi, emacs, pico, joe, gedit, or nedit) to start editing some files. 4.1. interchange.cfg -------------------- The first directive we need to use is a global directive that tells Interchange where the new catalog is, called Catalog. The Catalog directive has the following format: Catalog name catalog_base_directory link_url_path Open interchange.cfg in the Interchange software directory. Go near the top of the file, right below the other Catalog directives, and add this line: Catalog tutorial /var/lib/interchange/tutorial /cgi-bin/tutorial Save the file. 4.2. catalog.cfg ---------------- For the rest of the tutorial, most of the files mentioned do not exist yet. You will create them yourself with initial text we give. You need to create a catalog.cfg file for your tutorial store (in the tutorial catalog directory). We'll start with a very simple products database table with a few fields and a few products. The Database directive describes a database table to the Interchange system in this format: Database name filename format Interchange has several database options available. We will use the simplest, which is the built-in default (specifically, some variant of DBM). The default location for filename is in a subdirectory called products under the catalog directory. Interchange recognizes a number of file formats. We will use a tab-delimited text file. Enter the following into catalog.cfg: Database products products.txt TAB This tells Interchange that you have a database table named 'products' that is described in a tab-delimited file named products.txt. You can describe an unlimited number of arbitrary database tables for the system to use this way. Interchange keeps a list of default tables called "Product Files," reflecting its e-commerce roots. You can specify all of the database tables that contain products by using the ProductFiles directive. There is no default for this, so you will have to specify your products table's name by adding the following line to catalog.cfg: ProductFiles products There are a few other directives that Interchange expects to see in order to complete the minimum configuration. They are VendURL, SecureURL, and MailOrderTo. They are, respectively, your catalog's base URL, its secure URL, and the e-mail address to mail order notices to. Add the following lines to catalog.cfg to establish these directives: VendURL http://localhost/cgi-bin/tutorial SecureURL http://localhost/cgi-bin/tutorial MailOrderTo your@email.address The catalog.cfg file should look like this when you save it: Database products products.txt TAB ProductFiles products VendURL http://localhost/cgi-bin/tutorial SecureURL http://localhost/cgi-bin/tutorial MailOrderTo your@email.address 5. The products database table ============================== 5.1. products/products.txt -------------------------- Create the products/ directory in your tutorial catalog directory. The products/products.txt file will serve two purposes. It will provide Interchange with the layout of the products database table and it will also provide the data. When Interchange parses the products.txt file, it will expect the first line to contain the names of the fields for the database table (for example, sku, description, price). The first field in the list is expected to be a primary key (unique identifier) for that row. In most cases you are going to use the SKU (stock keeping unit) as the unique identifier for each product. The product database is handled as a special case since Interchange expects at least the description, price, and product ID (sku) fields. In other words, the products.txt file must at least contain fields named sku, price, and description. You can have other fields too, if you wish. The simple store that we are going to build will sell tests. You can choose another sample product line, but it is recommended that you keep it simple. Create the file products/products.txt to look like this, with a single tab separating each field: sku description price 4595 Nice Bio Test 275.45 2623 Stack of Econ Quizzes 1.24 0198 Really Hard Physics Test 1589.34 1299 Ubiquitous diff eq final 37.00 Note: When using tab-delimited files as we are, make sure you have exactly one tab between each field. Some text editors will use spaces to simulate tabs. Interchange expects actual ASCII tab characters; extra spaces or other characters will corrupt your data. You may notice that the columns don't line up in your text editor. This is the nature of tab-delimited files. Do not try to fix these. 6. Page templates ================= Since most sites have certain aspects of the site that remain the same as the content of the pages changes, we are going to create a template that we can use for all pages. We'll divide the page into four sections: _____________________ | | | top | | | |---------------------| | | | | | | | left | main | | | | | | | |---------------------| | | | bottom | |_____________________| The "main" section holds the content that is different for each page. The "top" section is for headers, banners, menus, and so on. The "left" section can be used as a sidebar or navigation bar, and the "bottom" section can contain the copyright and contact info. The top, left, and bottom sections will remain constant throughout the site. Making a change to information in one of these sections will make that change to all pages in your site. Now type the HTML for each template section in an individual plain text file in the catalog directory, named 'top', 'left', and 'bottom', respectively using the code displayed below. No '.html' suffixes are used on these because they are not meant to be parsed directly by Interchange as full pages. 6.1. top --------
The Interchange Test Catalog | |
(left) | 6.3. bottom ----------- |
(bottom) |
Test # | Description | Price |
---|
Test # | Description | Price |
---|---|---|
[loop-code] | [loop-field description] | [loop-field price] |
[item-field description] . . . [item-field price]
[include bottom] Then, to provide links to the product flypages from your home page, modify pages/index.html slightly, so that:We're sorry, the page you requested has not been found.
Try finding what you need on the [page index]welcome page.
[include bottom] The addition of this page ensures that users see your error message instead of a mysterious server error if they mistype a URL. 10. The shopping basket ======================= 10.1. A link for ordering ------------------------- Now that you have your products available, let's add a shopping cart so customers can purchase them. This is created using the [order] tag. These tags create an HTML link that causes the specified item to be ordered and transfers the shopper to the basket page. This is a built-in shortcut to the complete order process which uses an HTML form submission process. The parameter for the [order] tag is the product ID. To add these tags to the catalog, make the following change to pages/index.html:Qty. | Description | Cost | Subtotal |
---|---|---|---|
[item-quantity] | [item-field description] | [item-price] | [item-subtotal] |
Total: | [subtotal] |
[page checkout]Purchase now
[page index]Return to shopping
[page order]View shopping cart
[include bottom] Refresh the page and test the shopping basket in your browser. 11. Order checkout ================== 11.1. pages/checkout.html ------------------------- The site can now be completed by adding the ability to check out with the shopping cart and finalize the order. To do this the customer needs to provide a shipping address (which, for the sake of this tutorial, we will assume is the same as the billing address), and payment information. We will process the order by verifying the customer's payment information and sending an email to the merchant (ourselves) detailing the order. First you need to create a checkout page. The checkout page consists of a form that receives order information from the customer and performs a simple credit card number check. In this tutorial we will use a built-in test that only checks to see if a given credit card number could be valid. If the information is acceptable the customer will move to the next phase of the order process. If it is not, an error page will be displayed. To create a checkout page, type the following code and save it as pages/checkout.html. The section that follows explains the code. [include top] [include left][page index]Return to shopping instead
[include bottom] The HTML form begins with a method of 'post' (which sends the form data as its own stream, as opposed to the 'get' method which encodes the data as part of the URL). The [process] tag creates a special URL for form processing. Interchange has a built-in form processor that is configured by submitting certain fields in the form. The Finalize button will invoke this form processor and link the user to the special_pages/receipt.html page, which is described later. You are submitting some hidden form values that will tell Interchange how to process this form. The first value, mv_todo was set as submit. This causes the form to be submitted for validation. The second value, mv_order_profile was set as order_profile. This determines the validation process for the form. It is explained further in the next section. The last value, mv_cyber_mode, was set to be minivend_test. The mv_cyber_mode value determines what method will be used to charge a credit card. The value of minivend_test uses the internal test method, which calculates a simple checksum against the card to determine if it is a valid number. When preparing an order for processing, Interchange looks for certain named fields in the form values for name, address, and credit card information. We are using all expected field names in this form so that no translation needs to take place. View the checkout page in your browser. The "Finalize!" link has not been enabled, but the page should display properly. 11.2. etc/profiles.order ------------------------ Create the etc/ directory in the tutorial catalog directory now. You need to set up verification for the order form by defining an order profile for the form. An order profile determines what fields are necessary for the form to be accepted. Create an order profile verification page by typing the following and saving it as etc/profiles.order. The section that follows explains the code used. __NAME__ order_profile fname=required lname=required address1=required city=required state=required zip=required &fatal=yes &final=yes __END__ A single file can contain multiple profile definitions. First the profile is named using the __NAME__ pragma. (This is unrelated to the __VARIABLE__ syntax seen elsewhere in Interchange.) Then in the profile there is a list of the form fields that are required. The &fatal setting indicates that validation will fail if any of the requirements are not met. &final indicates that this form will complete the ordering process. This setting is helpful if you have a multi-page ordering process and you want to validate each page individually. The __END__ pragma signals the end of this profile, after which you can begin another one. In order to activate your order profile, add the following OrderProfile directive to the end of catalog.cfg: OrderProfile etc/profiles.order Watch for white space in front of the __NAME__ pragma, it can cause your profile to be ignored. Rember to restart Interchange for any changes to take effect. 11.3. special_pages/needfield.html ---------------------------------- If the submitted form lacks a required field, Interchange will display an error page. The default location is special_pages/needfield.html. To create this page, type the following text and save it as special_pages/needfield.html. [include top] [include left]The following information was not given:
[error all=1 show_var=1 show_error=1 joiner='
']
Please go back to the [page checkout]checkout page and fill out the form properly.
[include bottom] The [error] tag is the most important tag on this page. The all parameter tells the tag to iterate through all of the errors reported from the failed verification, and the show_var parameter indicates that the failed variable name should be displayed. For example, if the first name was left empty, fname would be shown. The show_error parameter displays the actual error for the variable. The joiner parameter inserts an HTMLThank you for ordering stuff from us.
Have a nice day!
[page index]Return to our welcome page
[include bottom] Once the order is processed, the customer's shopping cart is emptied. At this point you have a more-or-less functional store. Congratulations. 12. Enhancing the catalog ========================= Now that you have a working catalog, you can go back and add improvements and test them incrementally. This section walks you through several and then suggests more enhancements you can attempt on your own. 12.1. Price pictures -------------------- You may have noticed that the product prices aren't formatted as prices usually are. The way to correct this is with an Interchange feature called price pictures. There are several properties to price pictures: the currency symbol, the thousands separator, the decimal point, the number of digits to show behind the decimal, and so on. Most Unix systems have U.S. currency and the English language as the default locale, which is called en_US. The only thing you need to do on such a system is specify the currency symbol, which, in this case, is the dollar sign. To do this, add the following line to your catalog.cfg file: Locale en_US currency_symbol $ Restart Interchange and view your catalog. You will notice little has changed on the welcome page or the flypages, but in the shopping cart all your prices should be formatted as U.S. dollars ("1347.3" has become "$1,347.30"). This is because Interchange automatically formats shopping cart prices as currency. To turn off this feature, you would have to change the [item-price] tag to [item-price noformat] in pages/ord/basket.html. But that's probably not what you want to do. You're probably more interested in formatting your other prices as currency. To do that, simply use the [currency] [/currency] tag pair for all price values. Make the following change to pages/index.html: [loop search="ra=yes/fi=products"]