diff --git a/TEXT_IMPORT_GUIDE.md b/TEXT_IMPORT_GUIDE.md new file mode 100644 index 0000000..29de1e8 --- /dev/null +++ b/TEXT_IMPORT_GUIDE.md @@ -0,0 +1,201 @@ +# LittleShop Text Import Guide - Variant Collections + +## Summary of Changes + +The text import format **already supports variant collections** natively! The CSV import was incorrectly using multi-buys instead of proper variant collections. + +## Text Import Format (with Variant Collections) + +### Basic Structure + +``` +# Product Name; Variant Collection Name + +Optional description here + +category: CategoryName +price: BasePrice (optional when using variants) +weight: BaseWeight (optional when using variants) +unit: Unit +stock: StockQuantity + +- Variant1Name; Price; StockLevel +- Variant2Name; Price; StockLevel +- Variant3Name; Price; StockLevel +``` + +### Example: Weight-Based Product (Grams) + +``` +# Four whittteee; Weights - Standard +category: Flour +unit: Grams +stock: 100 +- 28g; 700; 100 +- 14g; 360; 100 +- 7g; 190; 100 +- 3.5g; 100; 100 +``` + +### Example: Unit-Based Product (Tablets) + +``` +# tablets - Vitamin-C; Single Units +Dutch import +category: Vitamins +unit: Unit +stock: 100 +- 100; 150; 100 +- 50; 80; 100 +- 25; 50; 100 +- 10; 30; 100 +``` + +## Key Differences: Variants vs Multi-Buys + +### Variants (Lines starting with `-`) +**Format**: `- VariantName; Price; StockLevel` +**Use Case**: Different sizes, weights, or quantities of the SAME product +**Example**: `- 28g; 700; 100` (28g size for £7.00 with 100 in stock) +**Links to**: Variant Collections ("Weights - Standard", "Single Units", etc.) + +### Multi-Buys (Lines starting with `+`) ❌ **DON'T USE FOR THIS DATA** +**Format**: `+ Name; Quantity; Price` +**Use Case**: Bulk purchase discounts (2 for £19, 3 for £25) +**Example**: `+ Twin Pack; 2; 19.00` (Buy 2 items for £19) +**Not applicable**: For single product variants + +## Variant Collections + +You must create variant collections in the admin panel first: + +1. **Weights - Standard**: For gram-based products (28g, 14g, 7g, etc.) +2. **Single Units**: For individual countable items (tablets, capsules) + +These collections define the presentation format and UI behavior for variants. + +## Complete Import File + +See: `products_text_import.txt` - Ready to use with 13 products properly formatted + +### Products Included: +- **Flour Category** (3 products): Four whittteee, double washed Flour, Chocolate infused +- **Cereal Category** (3 products): Cereal, Himalayan Cereal Blush, Cereal Rock +- **Vitamins Category** (5 products): Various vitamin tablets and organic options +- **Herbal Category** (2 products): Guarana products + +## How to Import + +### Option 1: Via Admin UI +1. Go to **Admin → Products → Import (Text Format)** +2. Upload `products_text_import.txt` **OR** paste content into textarea +3. **Check "Replace All"** if you want to delete all existing products first +4. Click **Import Products** + +### Option 2: Via API (if needed) +```bash +POST /Admin/Products/ImportText +Content-Type: multipart/form-data + +textContent: [paste file content] +replaceAll: true +``` + +## Important Notes + +### ✅ **DO THIS** +- Use `-` prefix for product variants (different sizes/quantities) +- Link products to variant collections for consistent UX +- Use `Unit` for countable items (tablets, capsules) +- Use `Grams` for weight-based products +- Use "Replace All" checkbox to clear existing data before import + +### ❌ **DON'T DO THIS** +- Don't use `+` multi-buys for size variants +- Don't use multi-buys at all (they're for bundle discounts) +- Don't forget to create variant collections first +- Don't import without checking "Replace All" if you want clean data + +## Variant Collection Setup + +Before importing, create these variant collections in admin panel: + +### 1. Weights - Standard +- Name: `Weights - Standard` +- Description: Standard weight-based product variants +- Used for: Flour, Cereal, Herbal gram-based products + +### 2. Single Units +- Name: `Single Units` +- Description: Individual countable items +- Used for: Tablets, capsules, individual items + +## Field Reference + +| Field | Required | Description | Example | +|-------|----------|-------------|---------| +| `# ProductName; VariantCollection` | Yes | Product name and variant collection | `# Vitamin-C; Single Units` | +| `Description` | No | Product description | `Dutch import` | +| `category: CategoryName` | Yes | Product category | `category: Vitamins` | +| `unit: WeightUnit` | Yes | Unit type (Unit/Grams/etc.) | `unit: Grams` | +| `stock: Number` | No | Base stock quantity | `stock: 100` | +| `- Name; Price; Stock` | No | Variant definition | `- 28g; 700; 100` | + +## Weight Unit Options + +- `Unit` - For individual items (tablets, pills, pieces) +- `Grams` - Standard metric weight +- `Kilograms` - Larger metric weight +- `Pounds` - Imperial weight +- `Ounces` - Imperial weight + +## Features Added + +1. ✅ **Replace All Option**: Checkbox in text import UI (same as CSV) +2. ✅ **Controller Support**: `replaceAll` parameter added to ImportText action +3. ✅ **Documentation**: Updated UI hints to show variant collection format +4. ✅ **Unit Support**: Added `Unit` to the weight unit documentation + +## Files Modified + +1. **ProductsController.cs**: Added `replaceAll` parameter to ImportText action +2. **ImportText.cshtml**: Added "Replace All" checkbox and updated documentation +3. **products_text_import.txt**: Created properly formatted import file + +## Testing + +1. **Create Variant Collections** in Admin Panel: + - "Weights - Standard" + - "Single Units" + +2. **Import Data**: + - Go to Admin → Products → Import (Text Format) + - Upload `products_text_import.txt` + - Check "Replace All" if needed + - Click Import + +3. **Verify Results**: + - Check Products page shows 13 products + - Check each product has variants linked to correct collection + - Verify variant pricing displays correctly + +## Migration from CSV + +The old CSV format used multi-buys incorrectly: +```csv +Variations,PhotoUrls +"28g:1:700;14g:1:360" ← WRONG (multi-buy format) +``` + +The text format uses variants correctly: +``` +# Product; Weights - Standard +- 28g; 700; 100 ← CORRECT (variant format: name; price; stock) +- 14g; 360; 100 +``` + +--- + +**Generated**: 2025-10-08 +**Format**: Human-Readable Text Import with Variant Collections +**Ready to Use**: Yes diff --git a/products_text_import.txt b/products_text_import.txt new file mode 100644 index 0000000..64db950 --- /dev/null +++ b/products_text_import.txt @@ -0,0 +1,126 @@ +# Four whittteee; Weights - Standard +category: Flour +unit: Grams +stock: 100 +- 28g; 700; 100 +- 14g; 360; 100 +- 7g; 190; 100 +- 3.5g; 100; 100 + +# double washed Flour; Weights - Standard +Will come as a organic +category: Flour +unit: Grams +stock: 100 +- 28g; 900; 100 +- 14g; 460; 100 +- 7g; 240; 100 +- 3.5g; 130; 100 +- 1g; 50; 100 + +# Chocolate infused double washed Flour; Weights - Standard +category: Flour +unit: Grams +stock: 100 +- 28g; 920; 100 +- 14g; 470; 100 +- 7g; 250; 100 +- 3.5g; 140; 100 +- 1g; 50; 100 + +# Cereal; Weights - Standard +category: Cereal +unit: Grams +stock: 100 +- 100g; 200; 100 +- 28g; 80; 100 +- 14g; 50; 100 +- 7g; 30; 100 + +# Himalayan Cereal Blush; Weights - Standard +Rare pink super clean +category: Cereal +unit: Grams +stock: 100 +- 28g; 180; 100 +- 14g; 100; 100 +- 7g; 60; 100 +- 3.5g; 40; 100 + +# Cereal Rock; Weights - Standard +category: Cereal +unit: Grams +stock: 100 +- 28g; 160; 100 +- 14g; 90; 100 +- 7g; 50; 100 + +# tablets - Vitamin-C; Single Units +Dutch import +category: Vitamins +unit: Unit +stock: 100 +- 100; 150; 100 +- 50; 80; 100 +- 25; 50; 100 +- 10; 30; 100 + +# tablets Vitamin-B; Single Units +25mg RAW organic capsules VEGAN +category: Vitamins +unit: Unit +stock: 100 +- 50; 150; 100 +- 25; 80; 100 +- 10; 40; 100 + +# Vitamin-B tablets; Single Units +Dutch import +category: Vitamins +unit: Unit +stock: 100 +- 100; 160; 100 +- 50; 90; 100 +- 25; 50; 100 +- 10; 30; 100 + +# Vitamin-B raw organic; Weights - Standard +Very very VEGAN 0.025g max per hit take orally +category: Vitamins +unit: Grams +stock: 100 +- 28g; 1600; 100 +- 14g; 860; 100 +- 7g; 450; 100 +- 3.5g; 250; 100 +- 1.75g; 140; 100 +- 1g; 100; 100 +- 0.5g; 60; 100 + +# N N Guarana; Weights - Standard +category: Herbal +unit: Grams +stock: 100 +- 28g; 1000; 100 +- 14g; 550; 100 +- 7g; 290; 100 +- 3.5g; 150; 100 + +# Vitamin-B pyramid gel tabs; Single Units +category: Vitamins +unit: Unit +stock: 100 +- 10; 50; 100 +- 25; 80; 100 +- 50; 130; 100 +- 100; 250; 100 + +# aco Guarana tablets 18mg; Single Units +VEGAN +category: Herbal +unit: Unit +stock: 100 +- 10; 60; 100 +- 25; 90; 100 +- 50; 160; 100 +- 100; 300; 100