# Artwork Referral Links - Installation Guide

## ⚡ Quick Installation (2 Minutes)

### Prerequisites
- ✅ FINEART plugin installed
- ✅ Referral system already set up (see `REFERRAL-PROGRAM-SETUP.md`)
- ✅ WooCommerce + Vendor plugin active

---

## 📦 What's Included

The following files have been added to your plugin:

```
fineart-plugin/
├── includes/vendor-dashboard/
│   └── class-fineart-artwork-referral-links.php    ← Main class
├── js/
│   └── artwork-referral-links.js                   ← Frontend JavaScript
├── css/
│   └── artwork-referral-links.css                  ← Styles
└── includes/
    └── class-fineart-loader.php                    ← Updated loader
```

---

## 🚀 Installation Steps

### Option 1: Files Already in Place (Recommended)

If you're using the complete plugin folder, the feature is **already installed**! Just:

1. **Upload/update the plugin folder** to your WordPress site
2. **Activate or reload** the FINEART plugin
3. **Test it out:**
   - Log in as a vendor
   - Go to Dashboard > Products
   - Look for "🔗 Get Referral Link" buttons

That's it! ✅

---

### Option 2: Manual File Upload

If you need to add files manually:

#### Step 1: Upload PHP Class
1. Upload `class-fineart-artwork-referral-links.php`
2. Place in: `wp-content/plugins/fineart-plugin/includes/vendor-dashboard/`

#### Step 2: Upload JavaScript
1. Upload `artwork-referral-links.js`
2. Place in: `wp-content/plugins/fineart-plugin/js/`

#### Step 3: Upload CSS
1. Upload `artwork-referral-links.css`
2. Place in: `wp-content/plugins/fineart-plugin/css/`

#### Step 4: Update Loader
1. Open `wp-content/plugins/fineart-plugin/includes/class-fineart-loader.php`
2. Add this code before the closing `}`:

```php
// Vendor Dashboard: Artwork Referral Links (v3.3)
$artwork_referral_links_file = FINEART_PATH . 'includes/vendor-dashboard/class-fineart-artwork-referral-links.php';
if (file_exists($artwork_referral_links_file)) {
    require_once $artwork_referral_links_file;
    FineArt_Artwork_Referral_Links::init();
}
```

#### Step 5: Clear Cache
- Clear WordPress cache (if using caching plugin)
- Clear browser cache
- Reload the vendor dashboard

---

## ✅ Verification Checklist

After installation, verify everything works:

### 1. Check Files Exist
```bash
# Via FTP/File Manager, verify these exist:
/wp-content/plugins/fineart-plugin/includes/vendor-dashboard/class-fineart-artwork-referral-links.php
/wp-content/plugins/fineart-plugin/js/artwork-referral-links.js
/wp-content/plugins/fineart-plugin/css/artwork-referral-links.css
```

### 2. Test Vendor Dashboard
- [ ] Log in as a vendor
- [ ] Navigate to Products page
- [ ] See "🔗 Get Referral Link" buttons on each product
- [ ] Click a button
- [ ] Modal appears with referral link
- [ ] Copy button works
- [ ] Link format: `https://fineart.gallery/product/name/?ref=artist-slug`

### 3. Test Permissions
- [ ] Non-vendors cannot access feature
- [ ] Vendors can only get links for their own products
- [ ] AJAX requests are properly secured

### 4. Test Functionality
- [ ] Click referral link in new incognito browser
- [ ] Cookie is set (check browser dev tools)
- [ ] Make test purchase
- [ ] Verify commission bonus applied
- [ ] Check order notes for "Artist-driven sale bonus"

---

## 🔧 Configuration

### File Paths (fineart.php)

Ensure these are defined in your main plugin file:

```php
define('FINEART_PATH', plugin_dir_path(__FILE__));
define('FINEART_URL', plugin_dir_url(__FILE__));
define('FINEART_VERSION', '3.3');
```

### Supported Vendor Plugins

Works automatically with:
- MultivendorX (MVX)
- WC Vendors
- Dokan (with some theme adjustments)

### Custom Dashboard URLs

The JavaScript auto-detects these URLs:
- `/dashboard/products`
- `/dashboard/artworks`
- `/vendor-dashboard/products`

If your vendor dashboard uses a different URL structure, update line 26 in `class-fineart-artwork-referral-links.php`:

```php
if (strpos($current_url, '/your-custom-dashboard-url') !== false) {
    // Load assets
}
```

---

## 🎨 Customization

### Change Button Text

Edit `js/artwork-referral-links.js` line ~94:

```javascript
'text': '🔗 Get Referral Link'  // Change this
```

### Change Button Style

Edit `css/artwork-referral-links.css`:

```css
.fineart-get-referral-link {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    /* Customize colors, fonts, etc. */
}
```

### Change Modal Design

Edit `css/artwork-referral-links.css` starting at line 32:

```css
.fineart-referral-modal-content {
    background: white;
    border-radius: 12px;
    /* Customize appearance */
}
```

---

## 🐛 Troubleshooting

### Buttons Not Appearing

**Possible causes:**
1. JavaScript not loaded
   - Check browser console for errors
   - Verify file path is correct
   - Clear cache and reload

2. Wrong page
   - Feature only loads on products/artworks pages
   - Check the URL path contains `/products` or `/artworks`

3. Vendor plugin not detected
   - Verify WC Vendors or MVX is active
   - Check user has vendor role

**Solutions:**
- Check browser console (F12) for JavaScript errors
- Verify `artwork-referral-links.js` is loaded (Network tab)
- Test with browser cache disabled
- Check file permissions (should be 644)

---

### Modal Not Opening

**Possible causes:**
1. AJAX error
2. Nonce verification failing
3. Product ID not detected

**Solutions:**
- Check browser console for errors
- Verify AJAX URL is correct
- Test with WordPress debugging enabled:
  ```php
  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);
  ```
- Check `/wp-content/debug.log` for errors

---

### Copy Button Not Working

**Possible causes:**
1. Browser doesn't support clipboard API
2. Page not served over HTTPS

**Solutions:**
- Test in modern browser (Chrome, Firefox, Safari)
- Ensure site uses HTTPS
- Manual fallback: Users can select and copy manually

---

### Referral Link Not Tracking

**Possible causes:**
1. Referral system not installed
2. Cookie blocked by browser
3. Commission filter not added

**Solutions:**
- Verify referral system is installed (see `REFERRAL-PROGRAM-SETUP.md`)
- Test in incognito mode
- Check `functions.php` has commission filter
- Verify permalinks are flushed

---

## 📊 Performance

### Load Impact
- **File sizes:**
  - JS: ~10KB
  - CSS: ~7KB
  - PHP: ~8KB

- **Only loads on vendor dashboard products page**
- **No impact on frontend shop pages**
- **Minimal database queries (only on button click)**

### Optimization Tips
1. Use caching plugin (WP Rocket, W3 Total Cache)
2. Combine/minify assets if needed
3. Files are already optimized

---

## 🔐 Security Features

✅ **Nonce Verification** - AJAX requests validated
✅ **Capability Checks** - Only vendors can access
✅ **Ownership Validation** - Can't get links for other vendors' products
✅ **Input Sanitization** - All user input sanitized
✅ **XSS Prevention** - HTML escaped in JavaScript
✅ **SQL Injection Prevention** - Using WordPress functions

---

## 🔄 Updating

When updating the plugin:

1. **Backup current files**
2. **Upload new version**
3. **Clear all caches**
4. **Test functionality**
5. **Check for errors in debug log**

No database updates required - feature is file-based only.

---

## 📱 Mobile Compatibility

✅ **Fully responsive design**
✅ **Touch-friendly buttons**
✅ **Mobile-optimized modal**
✅ **Works on iOS and Android**

Tested on:
- iOS Safari
- Chrome Mobile
- Firefox Mobile
- Samsung Internet

---

## 🎯 Success Metrics

After launching, track:
- Number of referral links generated
- Which products get most link requests
- Artist engagement with feature
- Increase in artist-driven sales

---

## 📞 Support

### Common Questions

**Q: Do I need to reinstall the referral system?**
A: No, this builds on the existing referral system.

**Q: Will this work with my vendor plugin?**
A: Yes, it's compatible with MVX, WC Vendors, and most vendor plugins.

**Q: Can I disable this feature?**
A: Yes, just comment out the loader code or remove the files.

**Q: Does it require any theme changes?**
A: No, it works with any WordPress theme.

---

## 🎊 Launch Checklist

Before announcing to artists:

- [ ] Files uploaded correctly
- [ ] Tested as vendor user
- [ ] Buttons appear on products page
- [ ] Modal opens and closes properly
- [ ] Copy button works
- [ ] Referral tracking works (test purchase)
- [ ] Commission bonus applied correctly
- [ ] Mobile version works
- [ ] No JavaScript errors in console
- [ ] Documentation prepared for artists

---

## 📖 Additional Resources

- **Feature Documentation:** `ARTWORK-REFERRAL-LINKS-README.md`
- **Referral System Guide:** `REFERRAL-PROGRAM-README.md`
- **Full Setup Guide:** `REFERRAL-PROGRAM-SETUP.md`

---

## 🎉 You're All Set!

The artwork referral links feature is now ready to help your artists promote their work and earn more commission!

**Next steps:**
1. Announce the feature to your artists
2. Share the README with usage instructions
3. Monitor adoption and engagement
4. Collect feedback for improvements

---

Made with ❤️ for FINEART
Version 1.0 | February 2026