CSV Instructions for Novice Users

This guide helps you create a CSV file for the Label Generator to produce labels like the Sapo Tourmaline example. Follow these steps to ensure your labels print correctly.

What is a CSV File?

A CSV (Comma-Separated Values) file is a simple text file where each line represents a row of data, and values are separated by commas. You can create it using software like Microsoft Excel, Google Sheets, or a text editor like Notepad.

Step-by-Step Guide to Create Your CSV File

1. Open a Spreadsheet Program:
   • Use Microsoft Excel or Google Sheets, which are easy for beginners.
   • If you don’t have these, use a text editor like Notepad (Windows) or TextEdit (Mac).
2. Set Up Your Columns:
   • The Label Generator uses four specific pieces of information from the CSV for each label:
     • SKU (e.g., “SKU-204”): A unique identifier for your item.
     • Description (e.g., “Tourmaline var. Elbaite, ‘Blue Cap’, 1997 Production”): A brief description of the item.
     • Location (e.g., “Sapo Mine, Ferruginha, Conselheiro Pena, MG, Brazil”): The origin or location of the item.
     • Price (e.g., “19.99”): The price of the item, without the currency symbol.
   • In your spreadsheet, place these in:
     • Column A: SKU
     • Column B: Description
     • Column F: Location
     • Column X: Price
   • You don’t need to fill columns C, D, E, G through W, or any columns after X. Leave them blank or include any data; the generator ignores them.
   • The Name, Address, and Email fields are entered directly in the web interface and apply to all labels.
3. Enter Your Data:
   • For each item, add a row in your spreadsheet.
   • Example (in Excel or Google Sheets):

     A         B                                     C  D  E  F                                              G ... W  X
     SKU-204   Tourmaline var. Elbaite, "Blue Cap"      Sapo Mine, Ferruginha, Conselheiro Pena, MG, Brazil         19.99
     SKU-205   Quartz, Smoky, 2020 Production           Mt. Ida, Arkansas, USA                                     12.50

   • In a text editor, the same data would look like:

     SKU-204,"Tourmaline var. Elbaite, ""Blue Cap""",,,,Sapo Mine, Ferruginha, Conselheiro Pena, MG, Brazil,,,,,,19.99
     SKU-205,Quartz, Smoky, 2020 Production,,,,Mt. Ida, Arkansas, USA,,,,,,12.50

     Note the commas for empty columns and quotes around text with commas or special characters.

4. Character Limits:
   • SKU (Column A): No strict limit, but keep short (e.g., under 20 characters) to fit the label.
   • Description (Column B): Keep concise (e.g., under 60 characters) to avoid font size reduction. Text is split to fit within the label’s middle section.
   • Location (Column F): Keep concise (e.g., under 60 characters) to avoid font size reduction. Text is split to fit within the middle section.
   • Price (Column X): No strict limit, but keep concise (e.g., “19.99”). Exclude the currency symbol; select it in the interface.
   • Name, Address, Email (Web Interface): Keep each under 30 characters to avoid font size reduction in the bottom section.
5. Save Your File:
   • In Excel or Google Sheets:
     • Go to File > Save As (or Download in Google Sheets).
     • Choose CSV (Comma delimited) (*.csv).
     • Save with a name like labels.csv.
   • In a text editor:
     • Save with a .csv extension (e.g., labels.csv).
     • Ensure no extra spaces or lines at the end.
6. Upload to the Label Generator:
   • Click the “Upload CSV File” input.
   • Select your CSV file.
   • Enter Name, Address, and Email in the web interface.
   • Click “Preview Labels” to view or “Download PDF” to save.

Common Mistakes to Avoid

• Incorrect Column Placement: Ensure SKU in Column A, Description in Column B, Location in Column F, Price in Column X. Incorrect placement causes missing or wrong data.
• Missing Commas in Text Files: In text editors, include commas for all columns up to X (e.g., ,,,, for empty columns).
• Quotes for Special Characters: Enclose text with commas (e.g., “Sapo Mine, Ferruginha”) in double quotes. Spreadsheets handle this automatically.
• Long Text: Description, Location, Name, Address, or Email that are too long may reduce font size or be truncated. Keep under 60 characters for Description/Location and 30 for Name/Address/Email.
• Empty Rows: Avoid blank rows, as they may produce blank labels.
• Incorrect File Format: Save as .csv, not .xlsx or .txt.

Testing Your CSV

Open your CSV in a text editor to verify commas and data placement. Test with a small file (1-2 rows) to ensure correct label output. If you see a “CSV Error” message, check for the above issues.

CSV Instructions for Experienced Users

This guide details how to prepare a CSV file for the Label Generator to produce labels matching the Sapo Tourmaline example, assuming familiarity with CSV structure.

CSV Structure

The Label Generator uses PapaParse with skipEmptyLines: true. Each row represents a label with fields:

• Column A (index 0): SKU (string, e.g., “SKU-204”). No strict limit, recommend <20 characters.
• Column B (index 1): Description (string, e.g., “Tourmaline var. Elbaite, ‘Blue Cap’, 1997 Production”). No fixed limit, but keep <60 characters to avoid font reduction (6.2–8pt).
• Column F (index 5): Location (string, e.g., “Sapo Mine, Ferruginha, Conselheiro Pena, MG, Brazil”). No fixed limit, but keep <60 characters to avoid font reduction.
• Column X (index 23): Price (string, e.g., “19.99”). No currency symbol; set in UI. Keep concise.

Columns C, D, E, G–W, and beyond X are ignored. Name, Address, and Email are set via the web interface (recommend <30 characters each). Rows with both Description and Location empty are skipped.

Example CSV

SKU,Description,,,Location,,,Price
SKU-204,"Tourmaline var. Elbaite, ""Blue Cap"", 1997 Production",,,,Sapo Mine, Ferruginha, Conselheiro Pena, MG, Brazil,,,,,,19.99
SKU-205,Quartz, Smoky, 2020 Production,,,,Mt. Ida, Arkansas, USA,,,,,,12.50

Use commas for empty columns. Enclose fields with commas or quotes in double quotes, escaping internal quotes (e.g., " ""Blue Cap"" ").

Character Constraints

• SKU: <20 characters recommended.
• Description/Location: <60 characters to avoid font reduction in the 54pt middle section.
• Price: No limit, but keep concise (e.g., “19.99”).
• Name/Address/Email: <30 characters each to fit in the 36pt bottom section without font reduction.

Creating the CSV

• Spreadsheet: Map to columns A, B, F, X. Save as CSV (UTF-8).
• Text Editor: Write rows with 24 columns (indices 0–23), e.g., SKU-204,"Tourmaline...",,,,Sapo Mine...,,,,,,19.99. Save as .csv.

Potential Errors

• Incorrect Columns: Data must be in A (0), B (1), F: 5), X (23). Misplacement causes incorrect labels.
• Malformed CSV: Missing commas or unbalanced quotes trigger “CSV Error”.
• Long Text: Description/Location >60 characters or Name/Address/Email >30 characters may reduce font size or truncate.
• Encoding: Non-UTF-8 may corrupt special characters (e.g., é).
• Invalid File: Only .csv files are accepted.

Validation

Verify CSV in a text editor for correct commas and quotes. Test with a small file. Use PapaParse’s tool (papaparse.com) for syntax validation if needed.