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 carefully 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 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 district, Conselheiro Pena, Minas Gerais, 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, create these columns in this exact order:
     • Column A: SKU
     • Column B: Description
     • Column F: Location
     • Column X: Price
   • You don’t need to fill in columns C, D, E, G through W, or any columns after X. Leave them blank or include them with any data; the generator will ignore them.
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 district, Conselheiro Pena, Minas Gerais, 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 district, Conselheiro Pena, Minas Gerais, 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 it short (e.g., under 20 characters) to fit on the label.
   • Description (Column B): Up to 69 characters total, split into three lines of 23 characters each. Longer text will be cut off.
   • Location (Column F): Up to 69 characters total, split into three lines of 23 characters each. Longer text will be cut off.
   • Price (Column X): No strict limit, but keep it concise (e.g., “19.99” or “5”). Do not include the currency symbol here; select it in the Label Generator interface.
5. Save Your File:
   • In Excel or Google Sheets:
     • Go to File > Save As (or Download in Google Sheets).
     • Choose CSV (Comma delimited) (*.csv) as the file type.
     • Save with a name like labels.csv.
   • In a text editor:
     • Save the file with a .csv extension (e.g., labels.csv).
     • Ensure no extra spaces or lines are added at the end.
6. Upload to the Label Generator:
   • Click the “CSV File” input in the Label Generator interface.
   • Select your saved CSV file.
   • Click “Preview PDF from CSV” to see your labels or “Download PDF from CSV” to save them.

Common Mistakes to Avoid

• Incorrect Column Placement: Ensure SKU is in Column A, Description in Column B, Location in Column F, and Price in Column X. Wrong columns will cause missing or incorrect label data.
• Missing Commas in Text Files: If using a text editor, include commas for all columns (even empty ones) up to Column X. For example, use ,,,, for empty columns C, D, E, etc.
• Quotes for Special Characters: If your Description or Location contains commas (e.g., “Sapo Mine, Ferruginha”), enclose the text in double quotes (e.g., "Sapo Mine, Ferruginha"). In spreadsheets, this is handled automatically when saving as CSV.
• Exceeding Character Limits: Keep Description and Location under 69 characters each. Longer text will be truncated, which may make labels incomplete.
• Empty Rows: Avoid blank rows in your CSV, as they may cause errors or blank labels.
• Incorrect File Format: Ensure the file is saved as .csv, not .xlsx or .txt. Other formats will cause an error when uploading.

Testing Your CSV

Before uploading, open your CSV in a text editor to check its structure. It should have commas separating each column, with data in the correct positions. Try a small test file with 1-2 rows to ensure the Label Generator reads it correctly.

If you see a “CSV error” message when uploading, double-check your file for the above issues. For further help, refer to the Experienced User Instructions or contact support.

Back to Top

CSV Instructions for Experienced Users

This guide provides technical details for preparing a CSV file for the Label Generator to produce labels matching the Sapo Tourmaline example. It assumes familiarity with CSV structure and data manipulation.

CSV Structure

The Label Generator expects a CSV file with data mapped to specific columns, parsed using PapaParse with skipEmptyLines: true. Each row represents a label with the following fields:

• Column A (index 0): SKU (string, e.g., “SKU-204”). No strict character limit, but recommend <20 characters for label fit.
• Column B (index 1): Description (string, e.g., “Tourmaline var. Elbaite, ‘Blue Cap’, 1997 Production”). Maximum 69 characters, split into three lines of up to 23 characters each.
• Column F (index 5): Location (string, e.g., “Sapo Mine, Ferruginha district, Conselheiro Pena, Minas Gerais, Brazil”). Maximum 69 characters, split into three lines of up to 23 characters each.
• Column X (index 23): Price (string, e.g., “19.99”). No currency symbol; select symbol in the UI. No strict character limit, but keep concise for label fit.

Columns C, D, E, G through W, and beyond X are ignored. At least one of Description (B) or Location (F) must be non-empty for a row to be processed; otherwise, it’s skipped.

Example CSV

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

Use commas to delimit fields, even if empty (e.g., 4 commas for columns C-E). Enclose fields with commas or special characters in double quotes. Escape internal quotes with double quotes (e.g., "Blue Cap" becomes " ""Blue Cap"" "). No header row is required, but including one is fine, as the first row is skipped.

Character Limits

• SKU (Column A): No enforced limit, but keep short (<20 chars) to avoid overflow.
• Description (Column B): 69 characters max (3 lines × 23 chars). Excess is truncated.
• Location (Column F): 69 characters max (3 lines × 23 chars). Excess is truncated.
• Price (Column X): No limit, but keep concise (e.g., “19.99”). Exclude currency symbol.

Creating the CSV

• Spreadsheet Software (Excel, Google Sheets):
  • Map data to columns A, B, F, X.
  • Save as CSV (Comma delimited, UTF-8 encoding recommended).
• Text Editor:
  • Write rows with commas for all columns up to X (24 columns total, indices 0-23).
  • Example: SKU-204,"Tourmaline var. Elbaite, ""Blue Cap"", 1997 Production",,,,Sapo Mine, Ferruginha district, Conselheiro Pena, Minas Gerais, Brazil,,,,,,19.99
  • Save with .csv extension.

Potential Errors and Warnings

• Incorrect Column Indices: Data must be in columns A (0), B (1), F (5), X (23). Misplaced data (e.g., SKU in column B) will result in incorrect or missing label content.
• Malformed CSV: Missing commas or unbalanced quotes will cause parsing errors, triggering a “CSV error” alert. Example: SKU-204,Tourmaline, Blue Cap,,,Sapo Mine (missing quotes around “Tourmaline, Blue Cap”) will fail.
• Character Limit Exceeded: Description or Location >69 characters will be truncated, potentially losing critical information. Check text length before saving.
• Empty Rows: Rows with both Description and Location empty are skipped, which may reduce the number of labels generated.
• Encoding Issues: Non-UTF-8 encoding may cause special characters (e.g., é in “Minas Gerais”) to render incorrectly. Use UTF-8 when saving.
• Invalid File Type: Uploading non-CSV files (e.g., .xlsx, .txt) will fail. Ensure .csv extension and valid CSV format.

Validation Tips

Verify CSV structure in a text editor to ensure correct comma placement and quoting. Test with a small CSV (1-2 rows) to confirm parsing and label output. Use PapaParse’s online tool (https://www.papaparse.com/) to validate CSV syntax if issues persist.

If errors occur, check the console for PapaParse error messages or review the Novice User Instructions for simpler guidance.

Back to Top