> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useinvent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Joomla

> Add your Invent assistant to Joomla sites

## Overview

Add your Invent AI assistant to any Joomla website with a floating bubble. Perfect for community sites, corporate websites, and portals.

## Installation

### Method 1: Custom HTML Module (Easiest)

<Steps>
  <Step title="Create New Module">
    Go to **Extensions** → **Modules** → **New**
  </Step>

  <Step title="Select Custom HTML">
    Choose **Custom HTML** as the module type
  </Step>

  <Step title="Configure Module">
    * **Title:** Invent Assistant
    * **Show Title:** No
    * **Position:** Choose a position (usually **footer** or **debug**)
    * **Status:** Published
  </Step>

  <Step title="Add the Code">
    In the **Custom Output** field, switch to editor and paste:

    ```html theme={"system"}
    <invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
    <script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
    ```

    Replace `YOUR_ASSISTANT_ID` with your actual assistant ID.
  </Step>

  <Step title="Set to All Pages">
    In the **Menu Assignment** tab, select **On all pages** or choose specific menu items
  </Step>

  <Step title="Save">
    Click **Save & Close**
  </Step>
</Steps>

### Method 2: Template Override

Add directly to your template:

```php theme={"system"}
<?php
// In your template's index.php
?>
<invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
<script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>

<?php echo $this->renderModule('footer'); ?>
</body>
</html>
```

### Method 3: Using a Plugin

Create a system plugin:

```php theme={"system"}
<?php
// plugins/system/inventassistant/inventassistant.php

defined('_JEXEC') or die;

class PlgSystemInventassistant extends JPlugin
{
    public function onBeforeCompileHead()
    {
        $doc = JFactory::getDocument();

        $script = '<invent-assistant assistant-id="YOUR_ASSISTANT_ID"></invent-assistant>';
        $script .= '<script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>';

        $doc->addCustomTag($script);
    }
}
```

## Customization

### Match Your Joomla Template

```html theme={"system"}
<invent-assistant
  assistant-id="YOUR_ASSISTANT_ID"
  theme-appearance="auto"
  theme-button-background-color="#1C3D5A"
  theme-button-color="#FFFFFF"
/>
<script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
```

### Show Only on Specific Components

In your Custom HTML module settings:

1. Go to **Menu Assignment** tab
2. Select **Only on the pages selected**
3. Choose specific menu items (e.g., only on Articles, or only on com\_content)

### Component-Specific Display

```php theme={"system"}
<?php
// In template index.php
$option = JFactory::getApplication()->input->getCmd('option', '');

// Only show on com_content (articles)
if ($option == 'com_content') {
?>
  <invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
  <script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
<?php
}
?>
```

## User Authentication

<Warning>
  **Security Requirement:** When using any `user-*` attributes (`user-id`, `user-name`), you **must** also provide `user-hash`. Both `user-id` and `user-hash` must be provided together, or neither should be provided. The `user-hash` must be generated on your backend using HMAC-SHA256 with your assistant's secret key. Never expose the secret key to the client.
</Warning>

Pass Joomla user information to provide personalized experiences:

```php theme={"system"}
<?php
$user = JFactory::getUser();

if (!$user->guest) {
    $secretKey = 'your_secret_key_here';
    $userId = (string) $user->id;
    $userName = $user->name;
    $userHash = hash_hmac('sha256', $userId, $secretKey);
?>
    <invent-assistant
        assistant-id="YOUR_ASSISTANT_ID"
        user-id="<?php echo htmlspecialchars($userId); ?>"
        user-name="<?php echo htmlspecialchars($userName); ?>"
        user-hash="<?php echo htmlspecialchars($userHash); ?>"
    />
    <script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
<?php
} else {
?>
    <invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
    <script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
<?php
}
?>
```

## Tips for Joomla

<CardGroup cols={2}>
  <Card title="Joomla 3 & 4" icon="check">
    Compatible with both Joomla 3.x and 4.x
  </Card>

  <Card title="Multilingual" icon="language">
    Works with Joomla multilingual sites
  </Card>

  <Card title="VirtueMart" icon="cart-shopping">
    Perfect for e-commerce support
  </Card>

  <Card title="Community Sites" icon="users">
    Help forum and community members
  </Card>
</CardGroup>

## Extension Compatibility

Works seamlessly with:

* **K2** - Advanced content management
* **VirtueMart** - E-commerce
* **HikaShop** - Online store
* **JomSocial** - Social networking
* **Community Builder** - User profiles
* **JEvents** - Event management

## Module Positions

Common positions for the assistant:

* **debug** - Bottom of page (recommended)
* **footer** - Footer area
* **user3** - Various template positions
* Custom position in your template

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bubble not appearing">
    **Solutions:**

    * Verify module is Published
    * Check module position exists in template
    * Ensure "Show Title" is set to No
    * Clear Joomla cache (System → Clear Cache)
    * Check Menu Assignment settings
  </Accordion>

  <Accordion title="Module position not showing">
    **Solutions:**

    * Verify position exists in your template
    * Try using "debug" position (always available)
    * Check template's templateDetails.xml for valid positions
  </Accordion>

  <Accordion title="Conflicts with template">
    **Solutions:**

    * Check for JavaScript conflicts in browser console
    * Adjust module ordering
    * Try different module position
    * Update to latest template version
  </Accordion>
</AccordionGroup>

## Joomla Version Compatibility

<Note>
  * **Joomla 3.x:** Fully supported
  * **Joomla 4.x:** Fully supported
  * **Joomla 5.x:** Fully compatible (when released)
</Note>

## Popular Joomla Templates

Tested with:

* **Helix Ultimate**
* **JA Templates**
* **Gantry 5**
* **T3 Framework**
* **Warp Framework**
* **RocketTheme**
* And most other Joomla templates

## Cache Considerations

If using Joomla cache:

1. Go to **System** → **Global Configuration** → **System** tab
2. Clear cache after adding the assistant
3. Consider excluding the module from cache if needed