Documentation

System - AI Meta Documentation

System - AI Meta is a Joomla plugin designed to automate the generation of SEO-friendly meta descriptions and keywords for your content using AI services. Compatible with Joomla 5.x, it integrates with AI providers like Ollama and OpenAI-compatible APIs to create tailored meta content based on your articles, contacts, or custom fields. This documentation provides a comprehensive guide to installing, configuring, and using the plugin to enhance your site's search engine optimization.

Installation

  1. Download: Obtain the plugin from the Joomla Extensions Directory or the developer's website.
  2. Install:
    • Log in to your Joomla administrator panel.
    • Navigate to System > Install > Extensions.
    • Upload the plugin package (e.g., plg_system_aimeta.zip) or install via the Joomla installer.
  3. Enable:
    • Go to System > Manage > Plugins.
    • Search for "System - AI Meta" and enable the plugin.

Requirements

  • Joomla 5.x or later.
  • PHP 7.4 or higher.
  • Access to an AI service (Ollama or OpenAI-compatible API).
  • Administrative access to your Joomla site.
  • cURL extension enabled for OpenAI-compatible connections (for model retrieval).

Configuration

The plugin is configured through the Joomla plugin manager. Follow these steps to set it up:

  1. Access Plugin Settings:
    • Go to System > Manage > Plugins.
    • Search for "System - AI Meta" and click to edit.
  2. Basic Settings:
    • Instructions: A description field explaining the plugin's purpose (no configuration required).
  3. Connections:
    • Connection Instances: Add one or more AI service connections using the subform.
      • Connection Name: A unique name for the connection (e.g., "MyOllama").
      • Connection Type: Choose between "Ollama" or "OpenAI Compatible".
      • Connection URL: Enter the AI service endpoint (e.g., http://localhost:11434 for Ollama).
      • API Key: Provide the API key for OpenAI-compatible services (leave blank for Ollama unless required).
    • Multiple connections can be added for flexibility.
  4. Meta Descriptions:
    • Connection: Select a configured AI connection for generating meta descriptions.
    • Model: Choose an AI model (populated dynamically based on the selected connection).
    • Temperature: Set a value between 0 and 2 (default: 0.7). Lower values produce focused outputs; higher values increase creativity.
    • Knowledge Files: Optionally specify knowledge file IDs from your AI provider for enhanced context (leave blank if unused).
    • Prompt: Define a chat conversation to guide meta description generation.
      • Role: Choose "System", "User", or "Assistant" to define the message's context.
      • Content: Use placeholders like %title%, %article%, or %#jform_field_id% to include dynamic content. For example:

         

        System: Generate a meta description (120–160 characters) for an article with the title "%title%" and content "%article%".
      • Multiple prompt entries can be added to create a conversation flow.
  5. Meta Keywords:
    • Similar to Meta Descriptions, configure:
      • Connection, Model, Temperature, and Knowledge Files.
      • Prompt: Define a chat conversation for keywords. For example:

         

        System: Generate 5–10 relevant keywords for an article with the title "%title%" and content "%article%".
    • The plugin automatically cleans keywords by removing leading/trailing commas or periods.
  6. Save: Click Save & Close to apply the configuration.

Usage

Once configured, the plugin integrates into Joomla's content editing interface for supported contexts (e.g., com_content.article, com_contact.contact).

  1. Edit Content:
    • Navigate to Content > Articles or Components > Contacts and open an item to edit.
  2. Generate Meta Content:
    • In the article or contact editor, locate the Meta Description or Meta Keywords fields.
    • Click the AI Generate button next to the field to generate content based on your configured prompts and AI settings.
    • The plugin pulls content from fields like the title, article text, or custom fields (using %#jform_field_id%) and sends it to the AI service.
  3. Regenerate Content:
    • If the generated content needs refinement, click the Regenerate button (with a repeat icon).
    • Provide a brief reason for regeneration (e.g., "Make it more concise") to guide the AI.
    • The plugin sends the current meta content and reason to the AI for improved output.
  4. Save Content: After generating or regenerating, save the article or contact to store the meta content.

Features

  • AI Integration: Supports Ollama and OpenAI-compatible APIs for flexible AI model usage.
  • Dynamic Prompts: Use placeholders (%title%, %article%, %keywords%, %#jform_field_id%) to incorporate content dynamically.
  • Customizable Output: Adjust temperature for creative or deterministic results and use knowledge files for context.
  • User-Friendly Interface: Adds "AI Generate" and "Regenerate" buttons to Joomla's editor for seamless operation.
  • Context Support: Works with articles, contacts, and custom fields, with potential for additional contexts.
  • Caching: Caches AI model lists to improve performance during configuration.
  • Security: Restricts access to authorized users (requires core.admin permission) and uses Joomla’s CSRF token for API requests.

Technical Details

  • Supported Contexts: com_content.article, com_contact.contact (extensible via code modifications).
  • Events: Listens to onAjaxAimeta for API requests and onContentPrepareForm for form enhancements.
  • JavaScript:
    • admin.js: Handles dynamic model loading in the plugin configuration based on selected AI connections.
    • aimeta.js: Manages the front-end interface, adding buttons and handling meta content generation.
  • PHP Classes:
    • AIMeta.php: Core plugin logic, handling AI requests and form preparation.
    • provider.php: Service provider for Joomla’s dependency injection.
    • JavascriptField.php and BetterspacerField.php: Custom form fields for enhanced configuration UI.
  • XML Forms: Define configuration fields for connections, prompts, and knowledge files (connections.xml, ai.xml, chat.xml, knowledge.xml).
  • Caching: Uses Joomla’s caching system for model retrieval (configurable via plugin settings).
  • Dependencies: Requires the ArdaGnsrn\Ollama library for Ollama connections (included via vendor/autoload.php).

Troubleshooting

  • No Models Loaded:
    • Verify the AI service URL and API key (if applicable).
    • Ensure the AI service is running and accessible.
    • Check Joomla’s error logs for cURL or API errors.
  • Generation Fails:
    • Confirm the user has core.admin permissions.
    • Ensure the session is active and CSRF token is valid.
    • Check prompt configuration for valid placeholders.
  • Invalid Output:
    • Adjust the temperature setting for more focused or creative results.
    • Refine prompts to provide clearer instructions to the AI.
    • Use the "Regenerate" feature with a specific reason to improve output.
  • Performance Issues:
    • Enable caching in the plugin settings to reduce API calls.
    • Verify server resources and AI service responsiveness.

Security Considerations

  • User Authorization: Only users with core.admin permissions can generate meta content.
  • API Key Storage: Store API keys securely in the plugin configuration and avoid sharing them.
  • CSRF Protection: The plugin uses Joomla’s CSRF token for all API requests.
  • Session Validation: Ensures active sessions to prevent unauthorized access.