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.