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:
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, MAQAM
Music, Hardbody
Nutrition, SAS Karaoke
Internet Division, or Parnassus
on the Net (Used Books) 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 main FAQ’s