# AppsFruit Elementor Embed - Setup Instructions

## Installation Steps

### 1. Prerequisites

Before installing the plugin, ensure you have:

- ✅ WordPress 5.8 or higher
- ✅ PHP 7.4 or higher
- ✅ Elementor plugin installed and activated

### 2. Install the Plugin

**Option A: Manual Installation**

1. Download or copy the `appsfruit-elementor-embed` folder
2. Upload it to `/wp-content/plugins/` directory
3. Go to WordPress Admin → Plugins
4. Find "AppsFruit Elementor Embed" in the list
5. Click "Activate"

**Option B: ZIP Upload**

1. Compress the plugin folder into a ZIP file
2. Go to WordPress Admin → Plugins → Add New
3. Click "Upload Plugin"
4. Choose the ZIP file and click "Install Now"
5. Click "Activate Plugin"

### 3. Verify Installation

After activation, you should see:

- ✅ "AEFE Templates" menu item in WordPress admin sidebar
- ✅ No error messages
- ✅ Elementor is detected (if not, you'll see a warning)

## Creating Your First Template

### Step 1: Create a New Template

1. Go to **AEFE Templates → Add New**
2. Enter a descriptive title (e.g., "Header CTA", "Pricing Table", "Contact Form")
3. Click **"Publish"** or **"Save Draft"**

### Step 2: Design with Elementor

1. Click the **"Edit with Elementor"** button
2. Design your template using Elementor's drag-and-drop interface
3. Add widgets, customize styling, set responsive options
4. Click **"Update"** to save your design

### Step 3: Get the Shortcode

After saving, you'll find the shortcode in two places:

**Location 1: Sidebar Meta Box**
- Look for the "Template Shortcode" box in the right sidebar
- Click "Copy Shortcode" button

**Location 2: Templates List**
- Go to **AEFE Templates → All Templates**
- Find your template in the list
- Copy the shortcode from the "Shortcode" column

### Step 4: Embed the Template

**Method A: Using Shortcode**

1. Edit any post or page
2. Paste the shortcode: `[aefe_embed id="123"]`
3. Update/Publish

**Method B: Using Gutenberg Block**

1. Edit any post or page in Gutenberg editor
2. Click the (+) button to add a block
3. Search for "Insert Elementor Template"
4. Select your template from the dropdown
5. Update/Publish

## Using Conditional Display

### Device-Specific Display

**Show only on mobile:**
```
[aefe_embed id="123" device="mobile"]
```

**Show only on desktop:**
```
[aefe_embed id="123" device="desktop"]
```

### Role-Based Display

**Show only to administrators:**
```
[aefe_embed id="123" role="administrator"]
```

**Show to multiple roles:**
```
[aefe_embed id="123" role="editor|author|contributor"]
```

**Common WordPress Roles:**
- `administrator` - Full site access
- `editor` - Can publish and manage posts/pages
- `author` - Can publish own posts
- `contributor` - Can write but not publish
- `subscriber` - Can only manage profile

### Post Type Specific

**Show only on pages:**
```
[aefe_embed id="123" post_type="page"]
```

**Show only on posts:**
```
[aefe_embed id="123" post_type="post"]
```

**Show on multiple post types:**
```
[aefe_embed id="123" post_type="page|post|product"]
```

### Combining Conditions

You can use multiple conditions together:

```
[aefe_embed id="123" device="mobile" role="subscriber" post_type="post"]
```

This shows the template only when ALL conditions are met:
- User is on a mobile device
- User is logged in as a subscriber
- User is viewing a single post

## Organizing Templates

### Using Categories

1. Go to **AEFE Templates → Categories**
2. Create categories like:
   - Headers
   - Footers
   - Call-to-Actions
   - Forms
   - Pricing Tables
3. Assign categories when editing templates

### Using Tags

1. Go to **AEFE Templates → Tags**
2. Create tags like:
   - seasonal
   - promotional
   - featured
   - homepage
3. Add tags to templates for easy filtering

## Common Use Cases

### 1. Reusable Header CTA

**Scenario:** Show a promotional banner on all blog posts

```
[aefe_embed id="101" post_type="post"]
```

### 2. Mobile-Only Contact Form

**Scenario:** Show a simplified contact form only on mobile

```
[aefe_embed id="102" device="mobile"]
```

### 3. Member-Only Content

**Scenario:** Show exclusive content to subscribers

```
[aefe_embed id="103" role="subscriber|contributor|author|editor|administrator"]
```

### 4. Product Showcase

**Scenario:** Show product grid on product pages

```
[aefe_embed id="104" post_type="product"]
```

### 5. Admin Dashboard Widget

**Scenario:** Show admin-only information

```
[aefe_embed id="105" role="administrator"]
```

## Where to Use Shortcodes

You can use AEFE shortcodes in:

✅ **Posts & Pages** - Classic or Gutenberg editor
✅ **Widgets** - Text widgets, HTML widgets
✅ **Custom Post Types** - Any CPT that supports content
✅ **Theme Files** - Using `do_shortcode()` function
✅ **Page Builders** - Most page builders support shortcodes
✅ **WooCommerce** - Product descriptions, shop pages

### Using in Theme Files

```php
<?php echo do_shortcode('[aefe_embed id="123"]'); ?>
```

### Using in Widgets

1. Go to **Appearance → Widgets**
2. Add a "Text" or "Custom HTML" widget
3. Paste your shortcode
4. Save

## Tips & Best Practices

### 1. Naming Convention

Use clear, descriptive names for templates:
- ✅ "Homepage Hero Section"
- ✅ "Blog Post CTA - Newsletter"
- ✅ "Product Page - Related Items"
- ❌ "Template 1"
- ❌ "Test"

### 2. Template Organization

- Create categories for different template types
- Use tags for special attributes (seasonal, featured, etc.)
- Keep templates focused on single purposes

### 3. Performance

- Don't embed too many heavy templates on one page
- Optimize images within Elementor templates
- Use Elementor's built-in performance features

### 4. Testing

Always test templates:
- On different devices (mobile, tablet, desktop)
- With different user roles
- On different post types
- After updates

### 5. Documentation

Keep notes about:
- Where each template is used
- What conditions are applied
- Special customizations or dependencies

## Troubleshooting

### Issue: "Template ID is required" error

**Solution:** Make sure you're using the correct shortcode format:
```
✅ [aefe_embed id="123"]
❌ [aefe_embed]
❌ [aefe_embed id=123]
```

### Issue: Template not showing

**Checklist:**
1. Is the template published? (not draft)
2. Is Elementor active?
3. Are conditional attributes correct?
4. Is shortcode in a supported area?

### Issue: Elementor editor won't load

**Solutions:**
1. Clear browser cache
2. Clear WordPress cache
3. Regenerate Elementor CSS: **Elementor → Tools → Regenerate CSS**
4. Check for plugin conflicts

### Issue: Shortcode appears as text

**Solutions:**
1. Verify shortcode syntax
2. Check if area supports shortcodes
3. Try in a different location (post content)

## Getting Help

### Built-in Help

Go to **AEFE Templates → Help** for:
- Quick reference guide
- Shortcode examples
- Developer documentation

### Support Resources

- Documentation: Check README.md
- Support: support@appsfruit.com
- Website: https://appsfruit.com

## Next Steps

Now that you're set up:

1. ✅ Create 2-3 test templates
2. ✅ Experiment with conditional display
3. ✅ Organize with categories and tags
4. ✅ Try the Gutenberg block
5. ✅ Explore developer hooks (if applicable)

Happy embedding! 🚀