FishCart General Information This is the FishNet(r) shopping cart, an Open Source online catalog management system. See COPYING and LICENSE for licensing information. Major points of discussion in this file: LISTSERVER DEFINITIONS SQL DATABASE ENGINE CSV DATABASE LOADING SHIPPING MODELS PGP ENCRYPTION USING YOUR OWN BLANK WEB PAGE WEB PAGE TEMPLATES CVS TREE ===================================================================== LISTSERVER There is a list server at fishcart@fishcart.org for support related questions. Subscribe by sending email to fishcart-request@fishcart.org with the single body line: subscribe fishcart ===================================================================== DEFINITIONS These are the major divisions listed in the maintenance Web site. MASTER: this table carries items that are independent of any particular catalog; these apply equally to all catalogs. ZONE: synonymous with "catalog", or a self contained set of products, languages, shipping methods, currency, and so forth. Catalogs, or zones, can be delineated in a variety of ways. One way is geographical; that is, a multinational could have several catalogs, one for North America, one for Europe, etc. Another could have a different catalog for each of the Western European countries and one for North America. Also, wholesale and retail catalogs could be maintained for the US by having different zones, or catalogs. SUBZONE: the subdivided areas of a zone determined by unique shipping and/or tax requirements. For example, if an American company has offices in Texas and Florida, and charges higher shipping rates to Alaska and Hawaii, there would be 4 subzones involved: one for Texas and one for Florida for sales tax requirements, one for the remaining continental 46 states because no tax is charged, and one for Alaska and Hawaii to cover higher shipping costs. Subzones are always coupled to zones, with unique entries per zone. SHIPPING: shipping rate schedules, always assigned to a particular subzone. Multiple shipping profiles per subzone are possible, with a default shipping profile being selectable by the cart admin. Multiple shipping schedules could consist of UPS Ground as a default, with oxcart, 2nd day air and overnight air as optional shipping methods. Each set of shipping profiles must be duplicated under each subzone. Though requiring more administration, having separate shipping profiles per subzone provides for the maximum granularity in shipping rates. WEB: things that pertain to the general appearance of the Web pages are contained here. The web table is coupled to the zone, with unique entries per zone. VENDOR: this section contains vendor general contact and customer support information. The vendor table is coupled to the zone, with unique entries per zone. LANGUAGE: general messages pertaining to individual languages are contained in this section. The language table is coupled to the zone, with unique entries per zone. NEW/SPECIAL PRODUCTS: there is provision in FishCart for a list of products recently added to the catalog, as well as a list of products that are on sale. The language table is coupled to the zone, with unique entries per zone. CATEGORIES: products are organized by categories. Categories are independent of products; products are independent of categories. Products and categories are associated by join tables that associate products with selected categories. The category table is coupled to the zone, with unique entries per zone. SUBCATEGORIES: optional 2nd tier of product organization. Subcategories must be enabled in the zone first. Once enabled, subcategories can be enabled on a category by category basis, allowing mixing categories with and without subcategories. A product can be in one and only one subcategory under any category. ===================================================================== SQL DATABASE ENGINE FishCart first ran on a Solid database (http://www.solidtech.com/). Solid was chosen for several reasons. Solid is reasonably priced and has good performance without overly restrictive licensing. It supports transactions, automatic backups, and other features which seemed important in a online commerce application. Solid has performed well in operation since January 1998. Since then, the PHPlib (http://phplib.shonline.de/) database abstraction class, DB_Sql, has been incorporated into FishCart to give database engine independence. To avoid naming conflicts with sites that are using PHPlib, the class has been renamed to DBbase_Sql. PHPlib does not have to be installed to run FishCart. The necessary database class has been incorporated into FishCart to avoid the necessity of installing PHPlib. Full acknowledgement is given to the PHPlib team for their fine work. PHPlib currently supports ODBC, Postgres, MySQL, and Sybase engines. FishCart may or may not have run against these; check with the mailing list for current information. The cart typically runs against a single database, by default called 'fishcartsql'. A unique operating environment in the 'fishcartsql' database is created for each client, with unique table names, user names and passwords, and stored procedures (where applicable). Unique database names are not required for installations where each cart is installed with its own database (typically MySQL, perhaps PgSQL). Some SQL database engines (Solid for one) only have one database to contain all tables, and thus each table must be customized to distinguish it from others. The '$custID' value in each db.??? file is used to make the table names unique for each installed cart. If each cart is running in its own unique database, the $custID variable in the db.??? file can be left blank. This customized client information is stored in a "db.???" file in a directory peer to the unpacking, "../fishcartsql.db/". The 'install.pl' perl script reads the db.??? files and does a series of regex substitutions to customize the SQL definition files and the operational PHP3 scripts while copying them to the client cart destination directory. The install.pl script copies the database SQL files under the client installation directory. These files all begin with 'sql_'. As part of the initial installation of any client cart, the SQL tables, user IDs, etc. must be created by running the appropriate file(s) through the SQL command for your database. See the docs for the database engine you are using for this step. *** THIS SHOULD ONLY BE DONE AT INITIAL INSTALLATION *** OR YOU MAY DESTROY YOUR DATABASE. ===================================================================== CSV DELIMITED FILE DATABASE LOADING One method for loading a MySQL FishCart database from delimited files is given in a very complete example in the /csvparse directory. This entire example is provided 'as is' by Simon Weller, simon@sound.co.nz. This allows exporting an Excel sheet as a delimited file, uploading it via the maintenance upload pages, and then loading the file by accessing a Web site to start the process. NOTE: Be sure to put the Web page that activates the load underneath the password protected /maint directory. Many thanks to Simon for including such a complete working example. ===================================================================== SHIPPING MODELS FishCart currently has provision for the following shipping models. ** Percentage of Order Total ** Line Item Unit Cost ** Line Item Price Threshold ** Weight Threshold ** Percentage of Order Total In this model, a flat percentage of the order total is taken for the total shipping charge. The shipping percent charge is kept in the shipping table. To use this method, put "shippercent.php" (unquoted) in the Ship Charge Calculation Script field. ** Line Item Unit Cost In this model, each line item has a unit cost. The current model allows for a first item cost, and a second and subsequent item cost that is different. ** Order Price Threshold This is the shipping model that seems to best fit what most clients want. In this model, shipping costs are calculated by looking up the order subtotal in an SQL table; the resulting row contains a decimal number. (The shipping charge table for this model is separate from the shipping table.) If the number is greater than one, the result is the final shipping cost. If the number is between 0 and 1, it is the percentage to apply for shipping charges. The following is a sample structure for this model. Order Total: Shipping: 0.00 - 19.99 3.00 (shipping charge) 20.00 - 39.99 4.00 (shipping charge) 40.00 - 59.99 6.00 (shipping charge) 60.00 - 99.99 .10 (percent) 100.00 - 199.99 .09 (percent) 200.00 and over .08 (percent) To use this method, put "threshpercalc.php" (unquoted) in the Ship Charge Calculation Script field. ** Order Weight Threshold In this model, shipping costs are calculated on an order weight basis. This model works much like as the Order Price Threshold model, but now shipping charges are computed by comparing the total weight of the products with a threshold table. In this case, shippping prices are always 'absolute' because the percent method used in the Order Price Threshold model have no sense here. The following is a sample structure for this model. Order Weight (kg): Shipping: 0.00 - 4.99 3.00 (shipping charge) 5.00 - 9.99 4.00 (shipping charge) 10.00 - 19.99 6.00 (shipping charge) 20.00 and over 8.00 (shipping charge) To use this method, put "shipthreshweight.php" (unquoted) in the Ship Charge Calculation Script field. ===================================================================== SUBCATEGORIES Subcategories are designed to provide a flexible method to structure products in two tiers. Categories are the first level and are always active; subcategories are an optional second tier of organization for installations with large numbers or a wide variety of products. To use subcategories, begin by checking the "Use Subcategories" flag in the zone profile. You then must specifically enable subcategories within each category that you want subcategories. There is a checkbox in the category profile to turn on subcategories. If not specifically enabled, subcategories are not active within a category. This allows flexibly mixing categories with and without subcategories to best fit the structure of each product category. For categories with subcategories enabled, there is a checkbox labeled "Use subcategory display and promotional information" in the category. This enables using the subcategory profile information instead of the category information when displaying the subcategory. If this is not checked, the category information is used. This includes the Web background graphic, background color, link colors, and other cosmetic features. By permitting the appearance of catalog pages to be uniquely crafted all the way to the subcategory level, a wide variety of presentations is possible, each tailored to its products. A product associated with a category can be listed in only one subcategory within that category. As has always been possible, the same product can still be simultaneously listed in multiple categories and/or subcategories simultaneously. ===================================================================== PGP ENCRYPTION Provisions are included for PGP encrypting your email orders. In the db.? file that you set up for each cart (see INSTALL), there is an entry for a hex PGP key ID. This is the PGP key ID of the public key that will be used to encrypt the orders. FishCart will automatically adapt its order processing to send encrypted email orders when the hex key ID is provided at cart installation time. In addition to these built in steps, it may be necessary to set the PGPPATH environment variable for the Web server to point to the proper keyrings. One example is below. It is taken from a shell script that starts the Web server. The following would be placed in the script before actually starting the server. In this case, the keyrings used for encryption are in the .pgp directory below the /usr/nobody directory. The path needs to point to the PGP keys that are accessible by the user the Web server runs under (not root!). This is for PGP version 2.7; you may need to adapt this for your version of PGP. export PGPPATH=/usr/nobody/.pgp GNUPG: if you are using GNUPG, you will need to modify the emailorder.php file, uncommenting the 'gpg' and commenting out the 'pgp' line. ===================================================================== USING YOUR OWN BLANK WEB PAGE TEMPLATE N.B.: the process below describes how to manually install FishCart into a template of your own design once it is installed into its final destination with the command line tools. The graphic installer uses a different process to install FishCart into your template. Please see the instructions included in the graphic installer for how to build your template for use with the installer. There are a few cut marks in the main public files to help you lift out the essential code to fit into your own Web page templates. The essential public files are: index.php display.php showcart.php showgeo.php contribute.php contribute_order.php orderform.php orderfinal.php (little to no changes to make) Start by defining a Web page template that has a good sized block of white space wherever you want the cart display to go. That space can be just about any size; I've even fit the cart into a 360 pixel wide window in a table. The font size may need reducing, and the forms may need serious reduction, but it can be made to fit. Rename the above files to something like *.orig, then copy your template to these five names. Everything from the first line of the original files down to the following comment line should go above everything else in your page code. For various reasons these blocks of code must be the first things in your pages. // END OF ESSENTIAL CART DISPLAY CODE FROM LINE 1 TO HERE The rest of the essential page display code within each page is bracketed by the two following lines. // START OF ESSENTIAL CART DISPLAY CODE ... // END OF ESSENTIAL CART DISPLAY CODE Using a text editor, copy these blocks of code from the original FishCart Web pages and paste them into the large block of space you've reserved for the cart display. This should get the basics working, and you can then fine tune the display to fit your needs. ===================================================================== CVS TREE You can get a copy of the current CVS tree as follows. You must have a recent CVS client installed on your machine; as of this writing, FishNet(r) is running cvs 1.10. You may need to add the following to your environment on Unix; for Win32, read the CVS docs to see what is necessary. CVSROOT= /repository export CVSROOT First you must log onto the CVS server: cvs -d :pserver:fishcart@cvs.fni.com:/repository login password: fishcart Now, you can check out a copy of the source with the following command: cvs -d :pserver:fishcart@cvs.fni.com:/repository checkout fishcart_v3 Once you have logged in and checked out a copy of the tree, you can update it to the latest CVS tree by entering the following command from within the ~/fishcart_v3 checkout directory. cvs update -d Be aware that the current CVS tree may be in the middle of development and may not be work. USE AT YOUR OWN RISK. For assistance with using CVS on Windows, the following links may be helpful. These sites are unrelated to FishCart or FishNet and are given "as is". http://www.tortoisecvs.org/ http://www.cvsgui.org/ http://www.cvshome.org/dev/codewindow.html http://www.webmasterbase.com/article.php/831 ===================================================================== FishCart: an online catalog management / shopping system Copyright (C) 1997-2002 FishNet, Inc. FishNet(r), Inc. 850 S. Greenville, Suite 102 Richardson, TX 75081 voice: 972.669.0041 fax: 972.669.8972