 |
 |
|
|
|
|
|
|
Before using the shopping basket system with your own products, you will need to create a catalogue. The catalogue is easy to write - you'll need to do it on computer with a text editor by following these simple instructions. Writing a catalogue well is very important, not only does it help you section your products appropriately but it also helps to advertise them effectively by making them easy to browse, easy to understand, and of course easy to buy. By complying with the exact layout of catalogue file described below you will make your catalogue easy to read and display by the ECommerce software, which will automatically format it and lay it out in the style that you yourself can specify separately. Of course you can use one of our style templates for the final look and at a later time configure it to fit your needs exactly.
The format of the catalogue file is crucial to the operation of the shopping basket. This document describes the catalogue file format with examples.
Every product you intend to sell requires a unique product code. You may not have allocated product codes and may be unsure how to proceed. We describe three simple schemes for creating product codes.
A simple way to create product codes is to assign a prefix to each section of the catalogue and to number each item sequentially within that section. So, for example, items in a miscellaneous section could be assigned M1, M2, M3, etc or MISC101, MISC102, MISC103, etc. Numbering can begin from any value and gaps can occur. When creating new sections ensure that a unique prefix is selected. For efficiency, you may wish to avoid using letters that may be mistaken for numbers.
New items added to any section are assigned higher numbers. Numbers are not re-allocated. This prevents new items being dispatched when discontinued items are ordered. When old items are removed from the web site (MTECS Tier 1), no changes are required in the rest of the system. Old product codes allocated this way can remain dormant within the system. It does not affect operation of the system. (If you do want to re-allocate product codes, merely change the price and description.)
If all of your suppliers have product codes, you may want to prefix a supplier code to the existing product codes. This greatly simplifies re-ordering, although your customers and competitors may be able to deduce common suppliers of otherwise unrelated items. Supplier product coding only works well if prominent brands are retailed.
If your products are available in a variety of sizes or options, you may want to incorporate this in your product codes. It may be unlikely that compact product codes of uniform length can be created that include all options, and allow for future expansion. Numeric options are particularly troublesome. Use a separator, such as a dash ("-"), between numeric options.
The catalogue file can be created from any text editor or word processor with the ability to save ASCII files. This is also known as "plain text format" or "raw text format". This option is usually one of many file formats available, although many low featured editors only read and write this format.
Please note that frivolous text formatting, such as font faces, sizes, colours and attributes such as enbold, will not be preserved. You are free to add such formatting, but this not affect the final output in the slightest, because it will not be saved. (Why do people use such a format? It is the most compact and portable text format - the most widely implemented format in all software. It is one of the truly open, universal standards.)
It may also be possible to create a catalogue file from your existing stock control system. Stock control systems are too varied to provide details. To cover all cases, a full definition is provided of the data format required. Similar formats have been used successfully worldwide for two decades. A competent programmer should be able to write a utility to convert the data from any suitable system provided with suitable documentation regarding your system.
You may only need to use a simple subset of the catalogue file format. Each product has one line in the catalogue file. Each line is called a record. The record is divided into three fields, which are separated by colons. (Avoid using colons because this will confuse the software that decodes the record. Details for including colons are described below.) This is an example catalogue:
PR1:100:Product 1 PR2:200:Product 2 PR3:300:Product 3
In this example, we have three products: Product 1, Product 2 and Product 3. (As can be seen, it is fine to use spaces in the catalogue.) Product 1 has the product code PR1. Product 1 is priced at 100 units.
Price units are configured elsewhere in the system, but will typically be pence or cents. Products are not priced in pounds, dollars, etc, because it is faster and more accurate to not calculate using fractions. Care must be taken to ensure that prices are not accidently priced in wrong units. As a safeguard, the shopping basket administration (MTECS Tier 2 Administration) has integrity ckecks which include a count of products not priced in multiples of 100. Alternatively, you may want to price your products so that they end with 95 or 99. This helps ensure that prices are of the correct scale. Another example may be useful. In the following example, the units have been defined as UK Pence.
QT21:20000:Robots And Mechanical Men Corporation Interplanetary Robot WD40:500:WD40 - Oil in a can
Product QT21 costs £200 and is a robot. Product WD40 costs £5 and is oil.
It may not be apparent that everything in the shopping basket is keyed by product code. Prices and descriptions are not stored in each shopping basket, but are taken centrally from the catalogue file. Changes in price (and description) affect items that have already been placed in the shopping basket.
It is for this reason that discontinued items should remain in the catalogue file. Pending shopping sessions may be affected by not being able to obtain descriptions for discontinued items. The description can be modified to show that the item has been discontinued.
It is possible for two or more products to have the same description. Since MTECS works exclusively on product code, the system is able to distingish between products, although your customers may not. If you want to change your product codes, run both sets of product codes until pending shopping baskets no longer refer to the old product codes.
It is not possible for two or more records to have the same order code, except in the case of colour and size variations. Products that share the same product code, colour and size will have unpredictable results. In such case, depending upon software implementation, both products may be added to the shopping basket, or the first instance, or the last instance may be added, or some less predictable action may occur. Please ensure that product codes are not duplicated. This is one of the integrity checks provided by the MTECS Tier 2 Adminstration software.
Additional fields can be defined for colour and size. Such fields are optional. Records with the optional fields can be intermixed with the trivial records shown above. Colours and sizes do not have to be complete across a product range. Prices do not have to be the same either, as shown in the following example:
TS1:1500:TShirt:White:Small TS1:1500:TShirt:White:Medium TS1:1500:TShirt:White:Large TS1:1500:TShirt:Yellow:Large TS1:1500:TShirt:Red:Small TS1:1500:TShirt:Red:Medium TS1:2000:TShirt:Red:Large
The above example is for TShirts. The first feature of note is that the product code is shared by all variants of TShirt. This is only allowed when representing different colours and sizes. The second feature of note is that yellow TShirts are not available in the same sizes as white and red TShirts. The final feature of note is large, red TShirts cost more other variants.
There is an automated utility to convert an uploaded catalogue into functional web pages, although it is not particularly effective for products with variants in colour and size. It may be necessary to create such web pages manually or modify this software accordingly. One suggested format for products is shown:
If colour and size are consistant, two selection fields could be employed. If colour and size are consistant across product and / or style, additional selection fields can be added. Alternatively, you may choose to ignore the colour and size fields entirely and allocate separate order codes for each variant, although you will be unable to create multiple selection fields without additional software (and associated configuration).
It is possible to omit either colour or size. The following example demonstrates both:
J1:2000:Jeans::Small J1:2200:Jeans::Medium J1:2400:Jeans::Large W1:1500:Digital Watch:Black W1:1500:Digital Watch:Red W1:1500:Digital Watch:White: H1:2500:Hat
In this example, jeans are only available in three sizes and digital watches are only available in three colours. A hat is available in one unspecified colour and size. (The associated product description and picture appears on the web site.) The two colons ("::") in each of the first three records are in fact field separators around empty colour fields. The colour field is present, but contains nothing, allowing the next field to be decoded correctly as size information.
It is perfectly acceptable to have colons separating empty fields, including empty optional fields at the end of a record. For example, the next three records define product W1 in three colours. The last of these three records has a trailing field separator for an empty size field. Both forms are correct, although it may be preferable to minimise file size.
So far, we have defined five fields: product code, price, description and two optional fields for colour and size. There is a third optional field for comments. Such comments are only shown after a product has been added to the shopping basket. This can be used to indicate low stock or possible delay without unnecessarily alarming all customers. Such notices can be as specific as required. A comment can also be used as a reminder for awkward products that require special arrangements. Such arrangements would appear in the description of a product and the comment would be a handy summary.
J1:2000:Jeans::Small: J1:2200:Jeans::Medium J1:2400:Jeans::Large J1:2600:Jeans::Extra Large:Limited stock available. W1:1500:Digital Watch:Black W1:1500:Digital Watch:Red::Currently out of stock. This item will be sent separately. W1:1500:Digital Watch:White:: H1:2500:Hat:::There may be delays ordering this item in summer. F1:500:Chocolate Ice Cream:::Frozen food is only dispatched by courier and cannot be exported. C1:2500:Sunglasses Cleaner:::This chemical is toxic; handle with care and store out of reach of children. C2:3000:Very Powerful Sunglasses Cleaner:::This chemical is flammable; we require a safety certificate before this item is dispatched.
The comment field is the sixth field and is always preceded by five field separators. For records that do not use the optional colour and size fields, three field separators [colons] are always required between the description and the comment fields.
This file format is named as "MTECS Catalogue Table". This file format is an open standard developed by Xirium. You are free to implement this open standard without patent or copyright restriction from this party. No royalties are payable to this party for the implementation of this open standard. This file format definition may be freely distributed.
The catalogue file format is a fairly simple file format. There is no magic number or header. It is a colon delimited file; a Unix database file, similar to the Unix password file. The file consists of 7 bit ASCII printable characters and the Unix newline character (ASCII character 10 only). Records are defined one record per line throughout the file. Each record is terminated by the Unix newline character. Blank lines are not defined. Comments are not defined. It is recommended that records are less than 1024 ASCII characters for compatability.
Fields within the record are separated by a colon. Fields are of variable length. There are up to six fields with the record defined in the following sequence:
The first three fields are required, the last three fields are optional. Additional fields are illegal and software must not generate such data, although it is recommended that such data be accepted. Where subsequant fields are null, separating colons can be optionally omitted. For example, where a given record only has the first three fields non null, the last three fields and separating colons can be omitted. This is the "trivial format".
Where a given record has null colour or size but a non null comment, colons are required as place holders between null fields. This also applies in the case of a null colour field preceding a non null size field. This allows the placement of subsequant non null fields to be determined correctly. An example follows of a record with null colour and size but a non null comment:
JAM/BLUE:650:Blueberry Jam:::Delivery of this item may be delayed due to high demand.
Where colons are required within a field, these should be preceded by a backslash ("\"). This is refered to as an escaped character. To specify the backslash character itself, use two backslash characters. These escaped characters may appear as frequently as required within any non numeric field. Escaped characters are decoded sequentially after fields are split; decode is deterministic. Other pairs of characters beginning with the backslash are undefined. An example follows:
BOOK1:1500:Book\: Steal This Book by Abbie Hoffman VID1:2000:Video\: The Matrix MAG1:500:Future Publishing\: Magazine\: Amiga Format, issue 121
Other entities may be specified from the SGML entity table. There exists a well defined set of character strings that exist between a leading ampersand character ("&") and a trailing semicolon (";"). Entity compatability may vary with web client. For maximum compatability, some entities can be simplified. For example, accented characters can be mapped to unaccented characters. Other symbols such as copyright ("©") can be mapped to a sequence of characters ("(C)").
Use of raw ampersands are dependent on client and are discouraged. Use of UniCode or other extended character sets is undefined. (N, it's not 8 bit clean thanx to the Wintel users.) For systems that require a suffix, files conforming to this file format are denoted by ".table".
If demand arises, we will support Comma Separated Value [CSV] format.
|
| Xirium Penthouse Suite 102 Long Gore Farncombe Surrey GU7 3TD England UK |
Telephone: +44 1483 415 485 Mobile: +44 79 7779 1430 EMail: webmaster@xirium.com WWW: http://www.xirium.com/ |