module-vendor-notes/README.md

# Shopkeeper Vendor Notes Extension

This Magento 2 extension displays vendor-specific notes on the admin order view page based on the vendor attribute assigned to order items.

## Features

- Displays vendor notes on the admin order view page
- Configurable notes per vendor via admin configuration
- Supports HTML formatting (links, line breaks, etc.)
- Automatically shows notes when products with specific vendors are in an order

## Adding New Vendors

To add a new vendor option and corresponding note configuration, follow these steps:

### Step 1: Add the Vendor Option to the Attribute

The vendor attribute code is: **`vendor`**

You can add new options through the Magento admin:

1. Navigate to **Stores > Attributes > Product**
2. Search for and edit the **Vendor** attribute
3. Go to the **Manage Options** section
4. Click **Add Option** and enter your new vendor name
5. Save the attribute

Alternatively, you can add options programmatically by creating an upgrade script.

### Step 2: Add Configuration Field for the New Vendor

Edit the file: `app/code/Shopkeeper/VendorNotes/etc/adminhtml/system.xml`

Add a new field block within the `<group id="general">` section:

```xml
<field id="new_vendor_note" translate="label" type="textarea" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>New Vendor Name Note</label>
    <comment>Enter notes here. Supports HTML for links and emails.</comment>
</field>
```

**Important:** Replace `new_vendor_note` with a lowercase, underscore-separated version of your vendor name (e.g., "ABC Company" becomes `abc_company_note`).

### Step 3: Add Default Configuration Value (Optional)

Edit the file: `app/code/Shopkeeper/VendorNotes/etc/config.xml`

Add a new default value within the `<general>` section:

```xml
<new_vendor_note>Example note for New Vendor.&lt;br&gt;Contact: &lt;a href="mailto:support@newvendor.com"&gt;support@newvendor.com&lt;/a&gt;</new_vendor_note>
```

### Step 4: Update the Block Logic

Edit the file: `app/code/Shopkeeper/VendorNotes/Block/Adminhtml/Order/View/VendorNotes.php`

In the `getVendorNotes()` method, add your new vendor to the `$vendorConfigPaths` array:

```php
$vendorConfigPaths = [
    'Thermo Fisher' => 'vendor_notes/general/thermo_fisher_note',
    'Orion' => 'vendor_notes/general/orion_note',
    'Nalgene' => 'vendor_notes/general/nalgene_note',
    'Thermo Fisher Parts' => 'vendor_notes/general/thermo_fisher_parts_note',
    'New Vendor Name' => 'vendor_notes/general/new_vendor_note', // Add this line
];
```

**Important:** The key must match **exactly** the vendor option label as it appears in the admin.

### Step 5: Clear Cache

After making these changes, clear the Magento cache:

```bash
php bin/magento cache:clean
php bin/magento cache:flush
```

## Configuration

After installation, configure vendor notes at:

**Stores > Configuration > Shopkeeper > Vendor Notes**

Each vendor has a textarea field where you can enter notes. HTML is supported for:
- Links: `<a href="https://example.com">Link Text</a>`
- Email links: `<a href="mailto:email@example.com">email@example.com</a>`
- Line breaks: `<br>`

## How It Works

1. The extension checks all items in an order
2. For each item, it retrieves the `vendor` attribute value
3. If a vendor matches one in the configuration, the corresponding note is displayed
4. Multiple vendor notes can appear if an order contains items from different vendors
5. Duplicate notes are automatically filtered out

## File Structure

```
app/code/Shopkeeper/VendorNotes/
├── Block/
│   └── Adminhtml/
│       └── Order/
│           └── View/
│               └── VendorNotes.php
├── etc/
│   ├── acl.xml
│   ├── config.xml
│   ├── module.xml
│   └── adminhtml/
│       └── system.xml
├── Setup/
│   └── InstallData.php
├── view/
│   └── adminhtml/
│       ├── layout/
│       │   └── sales_order_view.xml
│       └── templates/
│           └── order/
│               └── view/
│                   └── vendor_notes.phtml
└── registration.php
```

## Support

For issues or questions, please contact your development team.

## Installing via Composer

You can install this module into a Magento 2 project using Composer in a few ways.

1) Local path repository (during development)

Add this to your Magento project's `composer.json` repositories section:

```json
{
    "type": "path",
    "url": "../path/to/VendorNotes",
    "options": { "symlink": true }
}
```

Then require the package:

```bash
composer require shopkeeper/module-vendor-notes:1.1.0
```

2) VCS repository

If this module is hosted in a Git repository, add a VCS entry to your project's `composer.json`:

```json
{
    "type": "vcs",
    "url": "https://code.shopkeeper.dev/McQueen/module-vendor-notes.git"
}
```

Then require it the same way:

```bash
composer require shopkeeper/module-vendor-notes:dev-main
```

After installing, run these Magento commands from your project root:

```bash
php bin/magento module:enable Shopkeeper_VendorNotes
php bin/magento setup:upgrade
php bin/magento cache:flush
```