This feature is included in the base cost of your Americart Subscription.
[We had to add this note prominently since no one could believe we do not charge extra!]
Overview
The purpose of this feature set is twofold:
- 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.
- 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 your browser from your local computer disk using our upload form. 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:
- preview: shows you how your pages will look with your current set of rules applied to the data.
- download zip: after you've got your data rules set such that the preview looks like you wish, choose this setting to download a zip file containing the pages generated. You then upload your new pages to the appropriate place on your website.
- build search database: after preview mode shows your data as you wish, choose this option to add the product search feature to your website. (No CGI is needed on your site.)
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 top]
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 top]
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 top]
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/IE 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 top]
FAQs
Q1: Why can't I get my pages to look right in preview mode?
Q2: How does the ITEM_ROW_STRUCTURE work?
Q3: My data will display better if I have TWO table rows per product. Can I do that?
Q4: Can I display a picture of the product in my pages, or maybe a link to a detailed page?
Q5: 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?
Q6: I use Front Page, and if I load the generated pages into FP, it rearranges the form tags until they no longer work correctly. What can I do?
Q7: I'm using a Mac. Is there anything special I need to know?
Q8: Some of my products contain options I'd like to show as "select" pull down menus. Can I do that?
Q9: I don't want to use your generated pages, but could really use the search engine feature. Can I?
Q10: How do I add a search box to my site?
Q11: I want my search to be a simple box. Can I do that?
Q12: I want to have keywords in my CSV data that search will find, but I don't want to display it. Can I?
Q13: In a search, I'd like to offer another select pulldown besides just “Category”. Can I do that?
Q14: How can I use text links to initiate searches?
Q15: Is there a switch I can set which will require ALL terms typed into the search box to be present before returning a match?
Q16: Can I display an out of stock message when something is unavailable?
Q17: 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?
Q18: What text editor should I use to edit the rules file or the CSV file?
Q19: I need the generator to do (whatever) for me. Can you add that as a new property to the rules file?
Q20: How much does it cost to use the page generator and search engine?
Q21: Will the page generator also make an index file for easier browsing?
Q22: Are there any real world example of this system being used?
Q23: My CSV file is very large, and times out while waiting for the upload to complete. Must I break my CSV into smaller pieces?
Q1: Why can't I get my pages to look right in preview mode?
A1: There are many possible causes for this. Here are the most common:
- field definitions in the rules file don't match the csv file fields.
- you've edited the rules file in an html editor and it's corrupted the format of the file.
- your csv data is corrupt. We count on data that is in accordance with the csv standards. Deviating from that standard will confuse the processor. Make sure your data conforms to the format as defined in the CSV format section below <link to The CSV data format section of this web page>.
- You've got some "extra data" in your CSV file. Set PRICE_ERROR_ACTION= DROP in the rules file to filter this extra info.
- Your ITEM_ROW_STRUCTURE is not correct. We simply plug in the data where you have the fields names, and if you've got an html problem in there, it will hash things up.
[back to FAQ] [back to top]
Q2: How does the ITEM_ROW_STRUCTURE work?
A2: 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!).
[back to FAQ] [back to top]
Q3: My data will display better if I have TWO table rows per product. Can I do that?
A3: 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.
[back to FAQ] [back to top]
Q4: Can I display a picture of the product in my pages, or maybe a link to a detailed page?
A4: 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.
[back to FAQ] [back to top]
Q5: 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?
A5: 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.
[back to FAQ] [back to top]
Q6: I use Front Page, and if I load the generated pages into FP, it rearranges the form tags until they no longer work correctly. What can I do?
A6: 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.
[back to FAQ] [back to top]
Q7: I'm using a Mac. Is there anything special I need to know?
A7: 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.
[back to FAQ] [back to top]
Q8: Some of my products contain options I'd like to show as "select" pull down menus. Can I do that?
A8: 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 rules file format section 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
[back to FAQ] [back to top]
Q9: I don't want to use your generated pages, but could really use the search engine feature. Can I?
A9: 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.
[back to FAQ] [back to top]
Q10: How do I add a search box to my site?
A10: 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.
[back to FAQ] [back to top]
Q11: I want my search to be a simple box. Can I do that?
A11: Sure. Just make the maxhits and category be hidden variables with the appropriate data.
[back to FAQ] [back to top]
Q12: I want to have keywords in my CSV data that search will find, but I don't want to display it. Can I?
A12: Yes. 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.
[back to FAQ] [back to top]
Q13: In a search, I'd like to offer another select pulldown besides just “Category”. Can I do that?
A13: 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.
[back to FAQ] [back to top]
Q14: How can I use text links to initiate searches?
A14: There is a trick you can use to make figuring out what to use as a link very easy. In the standard search box code we provide, on the page you see after doing a search upload, run a few searches and get the results as you want, then "copy" the info displayed in the "location bar" of the browser, and "paste" into a link!
[back to FAQ] [back to top]
Q15: Is there a switch I can set which will require ALL terms typed into the search box to be present before returning a match?
A15: Yes. Add this to your search box code:
<input type=hidden name="bool" value="AND">
If you want to give people the choice, make a select:
<select name=bool>
<option value="AND">Match ALL Keywords
<option value="">Match ANY Keywords
</select>
[back to FAQ] [back to top]
Q16: Can I display an out of stock message when something is unavailable?
A16: 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.
[back to FAQ] [back to top]
Q17: 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?
A17: 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.
[back to FAQ] [back to top]
Q18: What text editor should I use to edit the rules file or the CSV file?
A18: We recommend the freeware editor Wordtabs. If using WordTabs, be sure to pull down "Tools...Options...Click the "general" tab, and UNcheck "RTF is default Format". This editor is GREAT freeware, although the author has moved on to other things.
Remember, the standard windows Notepad 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.
[back to FAQ] [back to top]
Q19: I need the generator to do (whatever) for me. Can you add that as a new property to the rules file?
A19: 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.
[back to FAQ] [back to top]
Q20: How much does it cost to use the page generator and search engine?
A20: 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.
[back to FAQ] [back to top]
Q21: Will the page generator also make an index file for easier browsing?
A21: 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.
[back to FAQ] [back to top]
Q22: Are there any real world example of this system being used?
A22: Visit Amateur Electronic Supply, Land of Marbles, Muzzys Performance Products, Country Lane Specialty Store, Hardbody Nutrition, or SAS Karaoke Internet Division for an example. Drop us a note if you don't mind us listing your site here.
[back to FAQ] [back to top]
Q23: My CSV file is very large, and times out while waiting for the upload to complete. Must I break my CSV into smaller pieces?
A23: 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 FAQ] [back to top]
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 shrink the font size.
[back to top]
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>
</td><td>Price</td><td> </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= COLONin 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 top]
< Back to FAQ’s