Americart Database/Search Engine Documentation

[This feature is included in the base cost of your Americart Subscription.]
[We had to add this note prominently, because no one could believe we were not charging extra!]

Contents:
Overview
Creating the data file
Creating the rules file
Using the upload form
Q & A
The CSV data format
The Rules file format


Overview

The purpose of this feature set is twofold:

  1. To enable easy generation of product html web pages straight from a database or spreadsheet. The database processor has been tested with a half million products/descriptions, and achieved excellent results.
  2. To provide a product search engine which returns results in a format compatible with the shopping cart. This feature enables effective marketing of an inventory perhaps too large for browsing.
In general terms, here is how it works: Data for your products is uploaded to our server via Netscape from your local computer disk. A set of rules (formatting instructions) to apply to the data is also sent. Depending on your form selections, perform several possible actions are performed:

You can have more than one CSV file for you site's data. In fact, it's encouraged since it will make browsing easier if you categorize your data. The search engine supports this also by presenting a pull down menu offering the choices of categories to search.

Back to Table of Contents


Creating the data file

Data files must be in CSV format. The format was chosen because it is available as an output, export, or "save as..." from virtually every database and spreadsheet program. It can also be created and effectively maintained with just a text editor.

Here are a few lines of a simple CSV file:

2644,CONGOS CAPER,11.99
2647,CONTRA 3,23.99
2650,COOL SPOT,17.99
2653,COOL WORLD,3.99
2656,CRASH DUMMIES,5.99
7395,CRAZY CHASE,3.99
2665,CYBER SPIN,3.99
The above is a simple example of video game part numbers, titles, and prices. Not too hard, is it? Want to see what the page generated from this small file looks like? The full details of the CSV file format are here.

Back to Table of Contents


Creating the rules file
The rules file is a text file which contains the basic information needed to process the CSV file. Here is the text of the simplest rules file possible:
START FIELDDEF
PARTNUMBER,TITLE,PRICE
STOP FIELDDEF

START ITEM_ROW_STRUCTURE
<tr>
 <td>PARTNUMBER</td>
 <td>TITLE</td>
 <td>$PRICE</td>
 <td>ADDIMG</td>
</tr>
STOP ITEM_ROW_STRUCTURE

ADDIMG= http://www.cartserver.com/sc/cartaddsml.gif
The FIELDDEF section maps the fields in your CSV file to what action should be taken with them. The example above works with the simple CSV file example in the section above.

The ITEM_ROW_STRUCTURE defines how you want to visibly display your data in the table row. This method gives you ultimate control over placement and appearance of your data. The ADDIMG is simply the URL of the "add to cart" graphic on your website.

Everything else in the rules file is optional and is fully defined in the rules file format section. Note that in many cases you will have a different rules file for each CSV file you are working with, although if the fields are all the same, one rules file can cover them all.

Be sure to note the the rules file is CASE SENSITIVE. Having addimg= instead of ADDIMG= will result in things not working.

Back to Table of Contents


Using the upload form
The upload form is more than just a way to upload. It's your window to building search databases, deleting search data you don't need any more, and iterating through the process of tweaking a rules file to get your pages just the way you want them.

What to put into the fields is defined on the upload form itself for your convenience. The only thing that may be unfamiliar to you is the file upload feature. You basically just enter the local path to your rules file and your csv file, and when you hit the GO! button, Netscape will send the files to our server for processing. For instance, your rules and CSV files might be here:

C:\My Documents\rules.txt
C:\My Documents\videxam.csv
If you use the "Browse..." feature, remember to set All files (*.*) in the "files of type" field of the File upload browse window, or you'll see nothing to choose from but html files.

Back to Table of Contents


Q & A


Why can't I get my pages to look right in preview mode?

There are many possible causes for this. Here are the most common:


Will you please explain more about the ITEM_ROW_STRUCTURE?

Simply put, we take the html code you put in there, substitute actual data in place of the field names, and dump it into the page table. It's sort of our map to how we display the data in your CSV file. You can modify the table cells in the ITEM_ROW_STRUCTURE to achieve the width or look you want. Add font tags, or any html tags to it to display your data as you want people to see it. With ITEM_ROW_STRUCTURE, you have no boundaries as to how the table row looks (unless you don't know any html codes!).


My data will display better if I have TWO table rows per product. Can I do that?

Yes. The processor won't know if you have an extra row in there. It just makes the substitutions and dumps the code into the table. For instance:

START ITEM_ROW_STRUCTURE
<tr>
 <td>PARTNUMBER</td>
 <td>TITLE</td>
 <td>$PRICE</td>
 <td>ADDIMG</td>
</tr>
<tr>
 <td colspan=4>PROMOTIONAL_TEXT</td>
</tr>
STOP ITEM_ROW_STRUCTURE
Of course the above structure assumes you defined a field named PROMOTIONAL_TEXT which in your CSV file was a paragraph about your item. If you're clever with ITEM_ROW_STRUCTURE, you can achieve any look you wish.
Can I display a picture of the product in my pages, or maybe a link to a detailed page?

There are several ways to do it. Let's say that you have a picture of each of your products, and name each after the item partnumber. You've got a REALLY easy way to show the picture now.

In your ITEM_ROW_STRUCTURE:

...
  <td>PARTNUMBER</td>
  <td><img src=http://www.yoursite.com/yourpix/PARTNUMBER.gif></td>
...
The processor will replace the fieldname PARTNUMBER with the actual partnumber of the item. Notice that you can still display the partnumber itself as usual. The processor will substitute any FIELDNAME as many times as it appears in the ITEM_ROW_STRUCTURE.

Another way is of course to have the URL of the image in your csv data, and use a method similar to the above, but with another FIELDNAME. That would be handy if you wanted to spec the height/width also, or display a "no picture" image:

line from CSV:
"xyz","Wacky Widget","5.00","xyz.gif","50","40"

START FIELDDEF
PARTNUMBER,TITLE,PRICE,PIX,PHEIGHT,PWIDTH
STOP FIELDDEF

START ITEM_ROW_STRUCTURE
<tr>
  <input type=hidden name=pictureurl value="http://www.yoursite.com/yourpix/PIX">
  <td>PARTNUMBER</td>
  <td><img src=http://www.yoursite.com/yourpix/PIX height=PHEIGHT width=PWIDTH></td>
  <td>TITLE</td>
  <td>$PRICE</td>
  <td>ADDIMG</td>
</tr>
STOP ITEM_ROW_STRUCTURE
Doing a link is about the same thing. It is just an "<a href=..." instead of a "<img src=..."

Note that the hidden variable name=pictureurl tells the cart the URL to use for the "view" function in the cart display. Be sure to use the "skip" mechanism on the picture lines if your csv file doesn't have pictures for all data. See below for more info.


My CSV data doesn't contain picture URL data for all entries. How can I keep the processor from displaying links to nowhere or broken images?

You can use our "skip" feature to handle this. If you were using a field name PIX like the example above, you could change the line in the item row structure to:

  <td><!--PIXskipstart--><img src=http://www.yoursite.com/yourpix/PIX height=PHEIGHT width=PWIDTH><!--PIXskipstop--></td>
Any time the processor hits an empty (really empty, not just a space or two) value in the CSV for PIX, it strips out all code between the <!--PIXskipstart--> and the <!--PIXskipstop-->. You can have more than one skip construct on a line also, in case you need to skip something, leave something in, then skip something. The skip feature will work with any fieldname. Make sure matching skipstart/skipstop functions are on the same line.
I use Front Page 98, and if I load the generated pages into FP, it rearranges the form tags until they no longer work correctly. What can I do?

Shield them from Front Page using their html markup tag:

START ITEM_ROW_STRUCTURE
<!--webbot bot="HTMLMarkup" startspan -->
<tr>
  <input type=hidden name=pictureurl value="http://www.yoursite.com/yourpix/PIX">
  <td>PARTNUMBER</td>
  <td><img src=http://www.yoursite.com/yourpix/PIX height=PHEIGHT width=PWIDTH></td>
  <td>TITLE</td>
  <td>$PRICE</td>
  <td>ADDIMG</td>
</tr>
<!--webbot bot="HTMLMarkup" endspan -->
STOP ITEM_ROW_STRUCTURE
Front Page 2000 does not exhibit this problem, so upgrading your FP is an option as well.
I'm using a Mac, anything special I need to know?

The Mac uses a slightly different line ending character sequence. If you have trouble saving CSV so it will work, look for something like ( CSV Windows ) in your program's export options.


Some of my products contain options I'd like to show as "select" pull down menus. Can I do that?

Yes, and the options can either be simple descriptive options or they can affect the price of the product. Look for SELECT1, SELECT2 & SELECT3 fieldnames as detailed in the Rules File format below.

When you use SELECT1, SELECT2, or SELECT3, don't forget to set the field separator in the rules file. An example command is:

SELECT1_SEPARATOR= COLON

I don't want to use your generated pages, but could really use the search engine feature. Can I?

Sure. Just don't do the "download zip" step or upload any of the generated pages to your site. Simply get the preview mode working right and then perform the "build search database" operation.


How do I add a search box to my site?

When you build a search database, you'll get the URL of a page which contains the html code of the search interface. You can then paste the box anywhere on your site you wish. Here is an example.


I want my search to be a simple box. Can I do that?

Sure. Just make the maxhits and category be hidden variables with the appropriate data.


I want to have keywords in my CSV data that search will find, but I don't want to display it. Can I?

Add a field to your CSV data, and put keywords in it. Set the field name to anything you wish, and it won't interfere or be displayed in the search results as long as you don't map it into the table row with ITEM_ROW_STRUCTURE.


In a search, I'd like to offer another select pulldown besides just category. Can I?

If your data upload for a given category contains, for instance, multiple brand names, and you want people to be able to select a certain brand in a category, the default search box won't allow that level of refinement. The good news is that you can add one. Just make a <select name=keywords_1>, and have the options be the various brand names in your CSV file. The engine will still return matches based on what they enter in the search box, but since it's also looking for that brand name, it will return those with the matching brand name first. You can have up to three of them, keywords_1, keywords_2, & keywords_3. In theory, you could dispense with a text box altogether, and have only select pull downs which would supply the keyword choices you want people to have.


Can I display an out of stock message when something is unavailable?

Yes. Define a FIELDNAME called STOCK (only the name STOCK will work). STOCK is special in that if it is zero, you get a message: "out of stock" instead of an add to cart button.

That is currently the only inventory control available, and for it to work effectively, you would need to update pages/reload the search with updated stock amounts when needed. You can either display or not display the actual stock quantity by including STOCK into the ITEM_ROW_STRUCTURE. It is less "update intensive" just to use STOCK as a "zero" trigger. Note: There is currently a bug in the code that if the field contains a 0 (zero) alone, it must be in quotes "0" to show the "out of stock" message. Using 0.0 works also.


I use MS Access, and it won't save to csv exactly how I want my csv data to look. Is there anything else I can do?

Just export from Access to Excel and from there to .csv. It works to your advantage anyway since when exporting from an Access query, the fields that you use to determine the query output are not necessarily needed in the .csv file, but get exported also. When you've got it in MS Excel, just delete the unwanted fields/columns, then save as csv.


What text editor should I use to edit the rules file or the CSV file?

We recommend the freeware editor Notespad. (NOT MS Notepad which won't edit large files). Note that you typically won't be editing the CSV file if you are exporting from a database. That would add an extra step you'd have to repeat each time you updated your site. The Notespad editor is great for editing CSV's if you are making them by hand though. Any good "true" text editor should work.


I need the generator to do (whatever) for me. Can you add that as a new property to the rules file?

We plan to keep adding properties to the rules file as time goes on. Feel free to send in your requests, but make them specific, concise and well thought out. Sending an actual property along with what it should do is a good idea.


How much does it cost to use the page generator and search engine?

It is included with your shopping cart at no extra cost. There is no limit to the number of products you can upload for search capability, but we reserve the right in the future to limit someone's usage if it gets WAY out of control, or traffic becomes a burden on the server. We don't see that happening, but it COULD happen. For instance, amazon.com could in theory upload their entire book database to cartserver and the whole thing, along with the million+ hits/day would cost them $249/year. Obviously that wouldn't work out too well for us, and we would limit or meter their usage.


Will the page generator also make an index file for easier browsing?

Yes. Just turn GENERATEINDEX= ON in your rules file, and set which of your data fields will be the "index" field. Ex: INDEXFIELD= TITLE See the rules file documentation below for more information.


Are there any real world example of this system being used?

Visit www.biondoracing.com for an example. Enter chrome in the Find: box and click GO! Drop us a note if you don't mind us listing your site here.


My CSV file is very large, and Netscape times out while waiting for the upload to complete. Must I break my CSV into smaller pieces?

No. If you're having problems with a large CSV either timing out, or just being too slow to upload as you tweak things out, you can put your CSV file up on the web. Once there, you put the URL of where to find the CSV data inside the CSV file on your computer. For instance, on your local computer, you'd have a file named: csvpointer.txt which contains the single line: http://www.----.com/data/data.csv (url of your csv file)

Put the filename csvpointer.txt in the "CSV file" box of the upload form. Since your website has more bandwidth than your local system, things will go much faster, and you can still keep your rules file locally for easier adjustments.

Back to Table of Contents


The CSV data format
CSV is a plain ascii format consisting of an arbitrary number of fields per line in the file. If you're exporting from a database or spreadsheet, you don't need to worry too much about this since the "save as .csv" will format your data correctly. If creating by hand, you should read these simple format guidelines.

The fields are comma separated:

data,other kind of data,yet another kind of data
What if your data has a comma in it? That would add an unwanted field to the line. CSV deals with this by enclosing a field with quotes if the field contains a comma:
data,"other kind of data, with comma",yet another kind of data
CSV allows enclosing all fields with " regardless of field content:
"data","other kind of data","yet another kind of data"
Now what if your data field had a " in it? CSV deals with this by escaping a quote WITH a quote:
"data","other ""kind"" of data","yet another kind of data"
The field will now legally contain the word kind in quotes.

The last case is if you have carriage returns inside a given data field. That would make your CSV line span more than one line when exported:

PN1244,"Dance Tunes
1. Boogie Down
2. Shining Star
...
10. YMCA",13.99
Notice that there are still THREE fields above, and the center field spans multiple lines. We can process it because it is enclosed by quotes. This is processed into the <br> code by the page generator and the search engine, taking advantage of the carriage return to get superior readability in the pages and cart display.

This may have given you the hint that you can embed html code into your data fields. You can, and it can be powerful. For instance, you could use the <i> tag right before the song titles above to get good readability, or maybe shrunk the font size.

Back to Table of Contents


The Rules file format
The rules file is also a plain text file. It contains definitions and properties to apply to the csv file being processed. The simplest form of the file was previously defined in the Creating the Rules File section above. Here we will see more detail.

This section contains the complete details of currently supported properties and field names. For your convenience, here is a template rules file which is commented as to what each thing does. Actual rules file commands are shown in blue below.

Display Properties:

ITEMS_PER_TABLE= 50
TABLES_PER_PAGE= 1
(generate 50 items/table and 1 table per page.)

TABLEPROPS= width=550 border=0 cellpadding=1 cellspacing=0
(<table> props for the returned table of products)

TABLE_HEADER_ROW= <tr bgcolor=#f0aaaa><td>Part#</td><td>Title</td><td>&nbsp;</td><td>Price</td><td>&nbsp;</td></tr>
(you can put a header row here that will appear at the top of every generated table)
(works for search engine too. be sure to match to # of table cells in ITEM_ROW_STRUCTURE)

NAV_TABLE_ALIGN= left
(aligns the navigation function to left, center, or right)
(this is for the next/previous/index links. Defaults to left if not in rules file.)

ODDROWPROPS= bgcolor=#ffffff
EVENROWPROPS= bgcolor=#f0f0f0
(these are <tr> props. we do even AND odd row so we can alternate color)

START ITEM_ROW_STRUCTURE
<tr>
 <td>PARTNUMBER</td>
 <td>TITLE</td>
 <td>$PRICE</td>
 <td>ADDIMG</td>
</tr>
STOP ITEM_ROW_STRUCTURE
(the table rows will appear as you lay them out here.)
Item Index Page Properties:
GENERATEINDEX= ON
(set to ON if you need an index page generated for better browsing.)
(index page info is ignored for search engine since it is irrelevant.)
INDEXTABLE_PROPS= border=5 cellpadding=1 cellspacing=0
INDEX_ITEM_MAXLENGTH= 20
(if your index field data is too long and makes the index table ugly, you can truncate)
INDEXFIELD= TITLE
(sets the data field you're indexing with)
Field Type Definitions and position mapping:
START FIELDDEF
PARTNUMBER,TITLE,PRICE,ANYNAME
STOP FIELDDEF
(map CSV field positions to our field types. Special fieldnames are:
PARTNUMBER,TITLE,PRICE,SHIPPING,INSURANCE,UNITMEAS,WEIGHT
STOCK,SELECT1,SELECT2,SELECT3)

(minimum data fields are: TITLE,PRICE)
Most of the field names are self explanatory, and map straight into the generated Americart form tags. Some need further explanation:
  • TITLE will be what is actually used as the "description" of the item when it is added to the cart by the shopper. TITLE is a good choice to generate the browsing index when we generate browsable product pages.
    It is possible that your data might be structured such that you need more than one field to map into the description field of the cart display. If so, use DESCRIPTION1, DESCRIPTION2, DESCRIPTION3, DESCRIPTION4 instead of TITLE. The processor will string up to four fields together and make the "item" description.

  • SELECT1, SELECT2, or SELECT3 will offer a pull down <select> for products with different sizes, colors, etc. For instance, a product comes in three colors which are listed in a single field of your CSV data; "red:green:blue". Name that field as SELECT1, and the processor will generate a pull down so the shopper may choose a color. The separator in this example is colon, but it can be anything. You set that with: SELECT1_SEPARATOR= COLON in the rules file.

    If the options affect the price, use our standard format for that: "red - $2.00:green - $3.00:blue - $4.00". You can still have a PRICE field if you wish; in that case the SELECT1, SELECT2 & SELECT3 Values are added to the PRICE.

  • ANYNAME simply means you can make up your own field names. If you have those names listed in the ITEM_ROW_STRUCTURE, the corresponding data will appear on the generated pages! If you've got data in your CSV file that you don't want to display, just don't list that field name in the ITEM_ROW_STRUCTURE.

Select field properties:

SELECT1_SEPARATOR= COLON
SELECT2_SEPARATOR= SEMICOLON
SELECT3_SEPARATOR= COLON
(valid are: COMMA, COLON, SEMICOLON. Sets the separator character for SELECT1, SELECT2, or SELECT3.
Example: Use SELECT1_SEPARATOR= COLON when SELECT1 is "red:green:blue")

Header/Footer sections:

START HEADER
<head><title>Wayne's Video Games</title>
<body bgcolor=#ffffff>
<center>
<h3>Your Logo (or other html) Here</h3>
Super Nintendo Video Games
STOP HEADER
(html/verbiage to insert into top of the generated pages.)

START FOOTER
<p><a href=http://www.cartserver.com/americart>Americart Home</a>
<hr>
STOP FOOTER
(optional html/verbiage to insert into bottom of the generated pages.)

No entries found message: (displayed when searching returns no entries)


START NOTHING_FOUND<head><title>Wayne's Video Games</title>
<body bgcolor=#ffffff>
<center>
<h3>Your Logo (or other html) Here</h3>
Super Nintendo Video Games
<p>No matching entries found.
<p>Hit "back" to try again.
<p> HINT: Can't think what query might find something?
A single . (period) alone in the search string box will return ALL entries up to Max hits.
STOP NOTHING_FOUND
(optional html/verbiage to display if a search finds no matching entries.)

Add to Cart Image URL:

ADDIMG= http://www.cartserver.com/sc/cartaddsml.gif
(URL of "add to cart" graphic. Pick one on YOUR site please.)
Back to Table of Contents

Link to the Upload Form
Americart Home