littleshop/TEXT_IMPORT_GUIDE.md

# 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
<text>
Optional description here
</text>
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
<text>Dutch import</text>
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` |
| `<text>Description</text>` | No | Product description | `<text>Dutch import</text>` |
| `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