# Dispensary Analytics - User Guide

## Table of Contents
1. [Installation & Setup](#installation--setup)
2. [Plugin Configuration](#plugin-configuration)
3. [Using Elementor Widgets](#using-elementor-widgets)
4. [Using Shortcodes](#using-shortcodes)
5. [Widget Reference](#widget-reference)
6. [Shortcode Reference](#shortcode-reference)
7. [Troubleshooting](#troubleshooting)

---

## Installation & Setup

### Requirements
- WordPress 5.0 or higher
- PHP 7.4 or higher
- Elementor plugin (for widget functionality)

### Installation Steps
1. Download the `dutchie-analytics.zip` file
2. Go to WordPress Admin → Plugins → Add New
3. Click "Upload Plugin" and select the zip file
4. Click "Install Now" and then "Activate"

---

## Plugin Configuration

### Setting Up API Connection

1. Go to **WordPress Admin → Settings → Dispensary Analytics**
2. Configure the following settings:
   - **API URL**: Your backend API URL (e.g., `http://localhost:3010/api` or `https://yourdomain.com/api`)
   - **API Token**: Your authentication token (if required)
3. Click "Save Changes"

---

## Using Elementor Widgets

### Finding the Widgets

1. Edit any page with **Elementor**
2. Look for the **"Dutchie Analytics"** category in the widgets panel
3. You'll find 5 widgets available:
   - Products Grid
   - Products Carousel
   - Stores List
   - Brands List
   - Specials

### Adding a Widget to Your Page

1. Open a page in **Elementor Editor**
2. Drag the desired widget from the sidebar to your page
3. Configure the widget settings in the left panel
4. Click "Update" to save your changes

---

## Using Shortcodes

Shortcodes allow you to display dispensary data in any post, page, or widget area without using Elementor.

### How to Use Shortcodes

1. Edit any post or page
2. Add a shortcode block (or paste directly in the classic editor)
3. Copy and paste one of the shortcodes below
4. Customize the parameters as needed
5. Publish or update your page

---

## Widget Reference

### 1. Products Grid Widget

**Purpose**: Display products in a responsive grid layout

**Widget Settings**:
- **Store ID** (required): The dispensary store ID
- **Category ID** (optional): Filter by specific category
- **Limit**: Number of products to show (default: 12)
- **Columns**: Number of columns (default: 4)
- **In Stock Only**: Show only available products (default: Yes)
- **Search**: Filter by keyword
- **Style**: Choose visual style (modern, classic, minimal)
- **Fields**: Customize which product fields to display

**Elementor Location**: Dutchie Analytics → Products Grid

---

### 2. Products Carousel Widget

**Purpose**: Display products in a sliding carousel/slider

**Widget Settings**:
- **Store ID** (required): The dispensary store ID
- **Category ID** (optional): Filter by specific category
- **Limit**: Number of products to show (default: 12)
- **Slides Per View**: How many products visible at once (default: 4)
- **Autoplay**: Enable automatic sliding (default: Yes)
- **Loop**: Enable infinite loop (default: Yes)
- **Navigation**: Show prev/next arrows (default: Yes)
- **Pagination**: Show dot indicators (default: Yes)

**Elementor Location**: Dutchie Analytics → Products Carousel

---

### 3. Stores List Widget

**Purpose**: Display a list of dispensary locations

**Widget Settings**:
- **Limit**: Number of stores to show (default: 10)
- **State**: Filter by state (e.g., "Arizona")
- **City**: Filter by city
- **Style**: List style (cards, list, table)
- **Show Address**: Display store address (default: Yes)
- **Show Phone**: Display phone number (default: Yes)
- **Show Hours**: Display business hours (default: Yes)

**Elementor Location**: Dutchie Analytics → Stores List

---

### 4. Brands List Widget

**Purpose**: Display available brands

**Widget Settings**:
- **Store ID** (optional): Filter brands by store
- **Limit**: Number of brands to show (default: 20)
- **Style**: Display style (grid, list, carousel)
- **Show Logo**: Display brand logos (default: Yes)
- **Show Product Count**: Show number of products per brand (default: Yes)

**Elementor Location**: Dutchie Analytics → Brands List

---

### 5. Specials Widget

**Purpose**: Display current deals and promotions

**Widget Settings**:
- **Store ID** (required): The dispensary store ID
- **Limit**: Number of specials to show (default: 6)
- **Active Only**: Show only active promotions (default: Yes)
- **Style**: Display style (banner, card, minimal)
- **Show Expiration**: Display when deal expires (default: Yes)

**Elementor Location**: Dutchie Analytics → Specials

---

## Shortcode Reference

### 1. Products Grid Shortcode

Display products in a grid layout.

**Basic Usage**:
```
[dutchie_products store_id="1"]
```

**Full Example**:
```
[dutchie_products store_id="1" limit="12" category_id="5" columns="4" in_stock="true" style="modern" search="indica"]
```

**Parameters**:
- `store_id` (required) - Store ID number
- `limit` - Number of products (default: 12)
- `category_id` - Filter by category ID
- `columns` - Grid columns: 2, 3, 4, or 6 (default: 4)
- `in_stock` - Show only in-stock: "true" or "false" (default: true)
- `search` - Filter by keyword
- `style` - Visual style: "modern", "classic", "minimal"
- `fields` - Comma-separated fields: "name,price,brand,thc,cbd"

---

### 2. Products Carousel Shortcode

Display products in a carousel/slider.

**Basic Usage**:
```
[dutchie_carousel store_id="1"]
```

**Full Example**:
```
[dutchie_carousel store_id="1" limit="16" slides_per_view="4" autoplay="true" loop="true"]
```

**Parameters**:
- `store_id` (required) - Store ID number
- `limit` - Number of products (default: 12)
- `category_id` - Filter by category ID
- `slides_per_view` - Products visible at once (default: 4)
- `autoplay` - Auto-slide: "true" or "false" (default: true)
- `loop` - Infinite loop: "true" or "false" (default: true)
- `navigation` - Show arrows: "true" or "false" (default: true)
- `pagination` - Show dots: "true" or "false" (default: true)

---

### 3. Stores List Shortcode

Display dispensary locations.

**Basic Usage**:
```
[dutchie_stores]
```

**Full Example**:
```
[dutchie_stores limit="10" state="Arizona" city="Phoenix" style="cards"]
```

**Parameters**:
- `limit` - Number of stores (default: 10)
- `state` - Filter by state
- `city` - Filter by city
- `style` - Display style: "cards", "list", "table"

---

### 4. Brands List Shortcode

Display available brands.

**Basic Usage**:
```
[dutchie_brands]
```

**Full Example**:
```
[dutchie_brands store_id="1" limit="20" style="grid"]
```

**Parameters**:
- `store_id` - Filter by store ID
- `limit` - Number of brands (default: 20)
- `style` - Display style: "grid", "list", "carousel"

---

### 5. Specials Shortcode

Display current deals and promotions.

**Basic Usage**:
```
[dutchie_specials store_id="1"]
```

**Full Example**:
```
[dutchie_specials store_id="1" limit="6" active_only="true" style="banner"]
```

**Parameters**:
- `store_id` (required) - Store ID number
- `limit` - Number of specials (default: 6)
- `active_only` - Show only active: "true" or "false" (default: true)
- `style` - Display style: "banner", "card", "minimal"

---

## Troubleshooting

### Widget Not Appearing
- Make sure Elementor is installed and activated
- Clear Elementor cache: Elementor → Tools → Regenerate CSS & Data
- Check if plugin is activated

### No Data Displaying
- Verify API URL in Settings → Dispensary Analytics
- Check that store_id is correct
- Test API connection in browser
- Check browser console for errors (F12)

### Shortcode Shows as Text
- Make sure you're using the correct shortcode format: `[shortcode_name]`
- Verify the plugin is activated
- Check that the post/page content is not in HTML mode

### Styling Issues
- Clear WordPress cache
- Clear browser cache (Ctrl+F5)
- Check for theme CSS conflicts
- Try switching to a default WordPress theme temporarily

### API Connection Issues
- Verify API URL is correct and accessible
- Check if API token is required and configured
- Ensure backend server is running
- Check server firewall settings

---

## Support

For additional support:
- Check plugin settings: WordPress Admin → Settings → Dispensary Analytics
- Review backend API logs
- Contact: creationshop.io

---

## Version Information

**Current Version**: 1.0.2
**Author**: Creationshop LLC
**License**: GPL v2 or later