ALAMARTE - OPEN GRAPH PARA JDOWNLOADS v2.1
Plugin System para Joomla!^® 5 y 6

DESCRIPCIÓN

Plugin profesional que automatiza la generación de metadatos Open Graph en
categorías y descargas de jDownloads. Optimiza cómo se ven tus enlaces cuando
los compartes en Facebook, Twitter, WhatsApp, LinkedIn y otras redes sociales.

¿QUÉ ES OPEN GRAPH?

Open Graph es un protocolo que permite controlar exactamente cómo aparecen tus
enlaces al compartirlos en redes sociales. Sin Open Graph, las redes eligen
aleatoriamente el título, descripción e imagen. Con este plugin, TÚ decides
qué mostrar.

CARACTERÍSTICAS PRINCIPALES

✓ Detección Automática de Imágenes
Extrae la imagen de cada categoría jDownloads automáticamente desde:
- Campo de imagen de la categoría
- Primera imagen en la descripción HTML
- Parámetros de #__categories de Joomla

✓ Metadatos Inteligentes
Usa automáticamente:
- Título de la página (og:title)
- Meta descripción configurada en el menú (og:description)
- URL canónica (og:url)
- Imagen de categoría (og:image)

✓ Extracción de Atributos HTML
Detecta automáticamente desde el HTML de la categoría:
- Atributo alt de la imagen
- Ancho (width) de la imagen
- Alto (height) de la imagen

✓ Twitter Card Opcional
Genera metadatos especiales para Twitter/X cuando lo actives:
- twitter:card
- twitter:title
- twitter:description
- twitter:image

✓ Configuración Flexible
- Valores predeterminados para todo el sitio
- Descubrimiento automático por categoría
- Fallbacks inteligentes
- Sin configuración compleja

REDES SOCIALES COMPATIBLES

• Facebook, Instagram, Messenger
• Twitter / X
• WhatsApp, Telegram
• LinkedIn
• Slack, Discord
• Pinterest
• Y cualquier plataforma que use Open Graph

INTERFAZ PROFESIONAL

Backend organizado en 3 pestañas:

[Básico]
Configuración principal de imagen, descripción y redes sociales.
Todo lo que necesitas para el día a día.

[Avanzado]
Opciones técnicas opcionales para casos específicos.
Solo si necesitas configuración avanzada.

[Información]
Guía completa sobre Open Graph, validación y troubleshooting.
Ayuda integrada para principiantes.

DISEÑO NO INVASIVO

• Solo se activa en páginas de jDownloads
• Compatible con extensiones SEO/canónicas
• No rompe el sitio si falla (fail-safe)
• Overhead mínimo (una consulta SQL cuando es necesario)
• Sin dependencias externas

MULTIIDIOMA

Interfaz disponible en:
• Español (es-ES) - Traducciones técnicas profesionales
• Inglés (en-GB) - Textos nativos completos

AYUDA INTEGRADA

Cada campo incluye:
• Descripción detallada de qué hace
• Valores recomendados específicos
• Ejemplos de uso real
• Tips con mejores prácticas
• Explicaciones para principiantes

CASOS DE USO IDEALES

✓ Sitios de descargas con jDownloads
✓ Repositorios de traducciones Joomla
✓ Catálogos de extensiones
✓ Bibliotecas de componentes
✓ Marketplaces de plugins
✓ Cualquier sitio que use jDownloads y comparta en redes

POR QUÉ USAR ESTE PLUGIN

1. AUTOMATIZACIÓN COMPLETA
Olvídate de configurar manualmente cada categoría. El plugin descubre
automáticamente la información de cada página.

2. PREVIEWS PROFESIONALES
Tus enlaces se verán profesionales en todas las redes sociales con
imagen grande, título claro y descripción atractiva.

3. MÁS CLICS
Los enlaces con buenas previews reciben hasta 3× más clics que enlaces
sin Open Graph.

4. CONTROL TOTAL
Decides exactamente qué imagen, título y descripción mostrar. Nada
queda al azar.

5. CERO CONFIGURACIÓN TÉCNICA
Funciona de inmediato. Opcionalmente personaliza valores predeterminados
y activa descubrimiento automático.

DESARROLLADO POR

ALAMARTE Ingeniería Web
https://alamarte.com

LICENCIA

GPL-3.0-or-later
Software libre y de código abierto

SOPORTE

• Documentación completa incluida en el plugin
• Guías de validación y troubleshooting
• Actualizaciones regulares
• Compatible con Joomla 5 y 6
• Probado con PHP 8.1, 8.2, 8.3, 8.4

ALAMARTE - OPEN GRAPH PARA JDOWNLOADS v2.1
INSTRUCCIONES DE INSTALACIÓN Y CONFIGURACIÓN

REQUISITOS PREVIOS

Antes de instalar, verifica que tengas:
✓ Joomla 5.0+ o Joomla 6.0+
✓ PHP 8.1+ (8.4 recomendado)
✓ jDownloads instalado y funcionando
✓ Acceso al panel de administración de Joomla

 PARTE 1: INSTALACIÓN

PASO 1: DESCARGAR EL PLUGIN

Descarga el archivo:
plg.alamarte_opengraph_jdownloads-v2.1.0.zip

No descomprimas el archivo. Joomla lo instalará directamente.

PASO 2: INSTALAR EN JOOMLA

1. Inicia sesión en el administrador de Joomla
2. Ve a: Sistema → Instalar → Extensiones
3. Arrastra el archivo .zip a la zona de carga
O haz clic en "Examinar archivos" y selecciónalo
4. Espera el mensaje: "Instalación del plugin correcta"
5. Haz clic en el botón verde "Habilitar"

¡Listo! El plugin está instalado y activo.

PASO 3: VERIFICAR INSTALACIÓN

1. Ve a: Sistema → Extensiones → Plugins
2. Busca: "ALAMARTE - Open Graph for jDownloads"
3. Verifica que el estado sea: ● Habilitado (punto verde)

 Si aparece deshabilitado (punto rojo), haz clic para habilitarlo.

 PARTE 2: CONFIGURACIÓN BÁSICA (5 MINUTOS)

ACCEDER A LA CONFIGURACIÓN

Sistema → Extensiones → Plugins
2. Busca "ALAMARTE - Open Graph"
3. Haz clic en el nombre del plugin
4. Verás 3 pestañas: [Básico] [Avanzado] [Información]

⚙️ Las siguientes pestañas le guiarán paso a paso en la configuracion del Plugin Alamarte Open Graph for jDownloads

ALAMARTE - OPEN GRAPH PARA JDOWNLOADS
CHANGELOG RESUMIDO

v2.1.1 (29 de noviembre de 2025)
================================================================================
CORRECCIÓN CRÍTICA: Validación de Seguridad

✓ IMPLEMENTADA funcionalidad de campos avanzados (antes no operativos)
✓ categoriesMenuUrl ahora valida URL actual vs. URL configurada
✓ categoriesMenuId ahora valida Itemid actual vs. ID configurado
✓ Lógica OR: plugin se activa si cumple URL O ID
✓ Descripciones actualizadas explicando funcionalidad real
✓ Mayor control sobre dónde se activa el plugin

CASO DE USO:
Si tienes múltiples componentes o menús, puedes restringir Open Graph solo
a URLs/menús específicos de jDownloads.

v2.1.0 (29 de noviembre de 2025)
================================================================================
VERSIÓN MAYOR: Interfaz con 3 Pestañas

✓ Pestaña "Básico": Configuración principal (imagen, descripción, redes)
✓ Pestaña "Avanzado": Validación de seguridad (URL base, ID menú)
✓ Pestaña "Información": Guía integrada (qué es OG, validación, troubleshooting)
✓ Organización profesional tipo JCH Optimize / Akeeba
✓ Ayuda educativa para principiantes
✓ Sin scroll excesivo

v2.0.1 (29 de noviembre de 2025)
================================================================================
MEJORA UX: Selector Visual de Imagen

✓ Campo imagen ahora usa selector de medios Joomla (type="media")
✓ Navegación visual por carpetas images/
✓ Previsualización de imagen antes de guardar
✓ Menos errores de escritura en rutas

v2.0.0 (29 de noviembre de 2025)
================================================================================
VERSIÓN MAYOR: Nueva Interfaz y Ayudas Avanzadas

✓ Campos siempre visibles (sin condicionales showon)
✓ Ayudas de 3-5 líneas por campo con ejemplos reales
✓ Valores recomendados por red social (Facebook/Twitter/LinkedIn)
✓ Organización con emojis y separadores visuales
✓ Secciones: Imagen, Descripción, Redes Sociales, Avanzado
✓ Textos en español e inglés completamente reescritos

v1.11.0 (29 de noviembre de 2025)
================================================================================
NUEVA FUNCIONALIDAD: Descripción Automática

✓ Selector "Usar descripción automática" (Sí/No)
✓ Usa meta descripción de Joomla → título → fallback manual
✓ Consistente con lógica de imagen y alt

v1.10.0 (29 de noviembre de 2025)
================================================================================
FUNCIONALIDAD MAYOR: Auto-Discovery Completo

✓ Extrae alt, width, height desde HTML de categoría
✓ Descubrimiento automático de metadatos de imagen
✓ Fallbacks inteligentes a valores manuales
✓ 100% automático cuando hay datos en HTML

v1.9.3 (29 de noviembre de 2025)
================================================================================
CORRECCIÓN: Metadatos de Imagen Faltantes

✓ Agregado og:image:alt (accesibilidad)
✓ Agregado og:image:width (optimización)
✓ Agregado og:image:height (optimización)

v1.9.2 (29 de noviembre de 2025)
================================================================================
MEJORA UX: Orden Visual

✓ Selector Twitter Card invertido: [No] [Sí]
✓ Más intuitivo visualmente

v1.9.1 (29 de noviembre de 2025)
================================================================================
HOTFIX CRÍTICO: Parámetro No Se Guardaba

✓ Renombrado enableTwitterCard → twitter_card
✓ Ahora se guarda correctamente en base de datos

v1.9.0 (29 de noviembre de 2025)
================================================================================
NUEVA FUNCIONALIDAD: Twitter Card Opcional

✓ Control manual de Twitter Cards (antes siempre activas)
✓ Default: No (desactivado)
✓ Genera twitter:* solo si se activa
✓ Compatible Joomla 6.x + PHP 8.4

v1.8.0 (31 de octubre de 2025)
================================================================================
REBRAND COMPLETO

✓ Renombrado: OGJD → ALAMARTE OpenGraph
✓ Media dentro de directorio del plugin
✓ Nuevos parámetros: setLocale, localeOverride
✓ Branding actualizado

v1.7.1 (21 de octubre de 2025)
================================================================================
RELEASE INICIAL

✓ Generación automática Open Graph para jDownloads
✓ Facebook App ID (fb:app_id)
✓ Twitter Cards
✓ Bilingüe (en-GB, es-ES)
✓ Descubrimiento de imágenes desde jDownloads y HTML

================================================================================
⏳ EVOLUCIÓN DEL PLUGIN
================================================================================

Líneas de código:
v1.7.1: 355 líneas → v2.1.1: 390 líneas

Documentación:
v1.7.1: ~500 palabras → v2.1.1: ~3,500 palabras (ayuda integrada)

Strings de idioma:
v1.7.1: 25 strings → v2.1.1: 45+ strings

Toggles configurables:
v1.7.1: 0 (todo automático) → v2.1.1: 7 toggles

Compatibilidad:
v1.7.1: Joomla 5, PHP 8.1
v2.1.1: Joomla 5/6, PHP 8.1-8.4

================================================================================
✨ PRÓXIMAS VERSIONES
================================================================================

v2.2.0 (Planeado)
-----------------
• Update server para actualizaciones automáticas
• Soporte og:video
• Detección de imágenes WebP

v3.0.0 (Planeado)
-----------------
• Panel de vista previa en tiempo real
• Validación integrada (sin salir de Joomla)
• Estadísticas de compartidos

================================================================================
ℹ️ INFORMACIÓN
================================================================================

Licencia: GPL-3.0-or-later
Desarrollador: ALAMARTE Ingeniería Web (Andrés Restrepo)
Sitio: https://alamarte.com
Compatible: Joomla 5.x / 6.x | PHP 8.1-8.4 | jDownloads

ALAMARTE - OPEN GRAPH PARA JDOWNLOADS v2.1
REQUERIMIENTOS TÉCNICOS

REQUISITOS DEL SISTEMA

SERVIDOR WEB
------------
✓ Apache 2.4+ (con mod_rewrite)
✓ Nginx 1.18+
✓ LiteSpeed 5.4+

REQUISITOS OBLIGATORIOS

1. JOOMLA! CMS

Versión mínima: 5.0.0
Versiones soportadas:

✓ Joomla 5.0.x
✓ Joomla 5.1.x
✓ Joomla 5.2.x
✓ Joomla 5.3.x
✓ Joomla 5.4.x (probado)
✓ Joomla 6.0.x (compatible)

API utilizadas:

• JoomlaCMSPluginCMSPlugin
• JoomlaCMSFactory
• JoomlaCMSUriUri
• JoomlaDatabaseDatabaseDriver

Compatibilidad:

• Namespace API estable entre J5/J6
• Sin funciones deprecadas
• Compatible con modo STRICT de base de datos

2. PHP

Versión mínima: 8.1.0
Versiones soportadas:

✓ PHP 8.1.x
✓ PHP 8.2.x
✓ PHP 8.3.x
✓ PHP 8.4.x (recomendado)

Extensiones PHP requeridas:

• json (para parseo de parámetros)
• mbstring (para truncado multibyte-safe)
• PDO (para acceso a base de datos)

Configuración PHP recomendada:

memory_limit = 256M (mínimo 128M)
max_execution_time = 60
upload_max_filesize = 10M

3. JDOWNLOADS

Versión: Cualquier versión con tablas estándar

Tablas requeridas:
✓ #__jdownloads_categories
✓ #__jdownloads_files

Campos utilizados (si existen):
• image, cat_image, cat_pic, picture
• description, cat_description, metadesc
• cat_id (en archivos)

⚠️ Nota: El plugin es tolerante a diferentes versiones de jDownloads.
Si las tablas/campos no existen, usa fallbacks sin errores.

4. BASE DE DATOS

Motor soportado:
✓ MySQL 5.7+ (recomendado 8.0+)
✓ MariaDB 10.3+

Configuración:
• InnoDB como motor de almacenamiento
• utf8mb4 / utf8mb4_unicode_ci (collation)

Modos SQL compatibles:
✓ STRICT_TRANS_TABLES
✓ NO_ZERO_DATE
✓ Modo tradicional

Permisos necesarios:
• SELECT en tablas #__jdownloads_*
• SELECT en tabla #__categories
• SELECT en tabla #__extensions (para parámetros)

REQUISITOS OPCIONALES (RECOMENDADOS)

1. CACHÉ

Sstema de caché de Joomla:
• Recomendado: Habilitado
• Tipo: File, Memcached, Redis

⚠️ Nota: El plugin respeta la caché de Joomla.
Purgar caché después de cambios de configuración.

2. CDN / CLOUDFLARE

Si usas CDN:
• Purgar caché después de cambios en imágenes
• Asegurar que imágenes sean accesibles públicamente
• No bloquear scrapers de redes sociales

robots.txt debe permitir:
• Facebookexternalhit/*
• Twitterbot/*
• LinkedInBot/*

3. OPTIMIZACIÓN

Extensiones compatibles:
✓ JCH Optimize (probado)
✓ Akeeba Admin Tools
✓ Regular Labs extensions
✓ Cualquier extensión SEO

El plugin es compatible con:
• URLs canónicas
• Redirects 301/302
• Extensiones de metadatos SEO

COMPATIBILIDAD DE EXTENSIONES

COMPATIBLE CON

✓ SP Page Builder Pro
✓ Helix Ultimate Framework
✓ JCH Optimize
✓ Akeeba Backup
✓ Admin Tools
✓ Regular Labs extensions
✓ Extensiones SEO (SEOSimple, etc.)
✓ Cualquier template responsive

NO COMPATIBLE / NO NECESARIO CON

✗ Otros plugins de Open Graph (conflicto - elegir uno)
✗ Plugins que modifiquen <head> de forma invasiva

RECURSOS DEL SERVIDOR

CONSUMO DE RECURSOS

CPU:
• Overhead: < 0.01s por request
• Sin procesamiento pesado

Memoria:
• Adicional: < 2 MB por request
• No mantiene datos en memoria

Base de datos:
• Queries por página:
- 0 queries si discoverCategoryImage = No
- 1 query si discoverCategoryImage = Sí
• Tipo: SELECT simple con índices
• Sin writes/updates

Ancho de banda:
• Metadata adicional: ~2-5 KB en HTML <head>
• Sin carga de archivos externos

IMPACTO EN RENDIMIENTO

Page Speed:
✓ Sin impacto en Core Web Vitals
✓ Sin JavaScript adicional
✓ Sin CSS adicional
✓ Sin requests HTTP externos

Lighthouse Score:
✓ No afecta Performance
✓ No afecta Accessibility
✓ Mejora Best Practices (metadatos correctos)
✓ Mejora SEO (estructura de datos)

SEGURIDAD

BUENAS PRÁCTICAS

✓ Sin eval() o exec()
✓ Sin include/require dinámicos
✓ Sanitización de todas las salidas
✓ Prepared statements en queries
✓ No almacena datos de usuario
✓ No crea archivos en servidor
✓ Silent fail (nunca rompe la página)

VALIDACIÓN DE DATOS

• Entrada de usuario → Escapado con Joomla API
• URLs → Validadas y normalizadas
• Imágenes → Solo rutas permitidas
• SQL → Prepared statements con placeholders

PERMISOS

El plugin NO requiere:
• Escritura en filesystem
• Acceso a archivos fuera de Joomla
• Conexiones externas
• Permisos elevados

MANTENIMIENTO

ACTUALIZACIONES

Método de actualización:
1. Descargar nueva versión
2. Instalar sobre versión existente
3. Joomla detecta upgrade automáticamente
4. Configuración se mantiene

Frecuencia recomendada:
• Verificar actualizaciones: Mensual
• Actualizar versiones menores: Opcional
• Actualizar versiones mayores: Recomendado

RESPALDO

Antes de actualizar, respaldar:
✓ Base de datos (tabla #__extensions)
✓ Archivo: /plugins/system/alamarteogjd/

Comando SQL para backup de config:
SELECT * FROM #__extensions WHERE element = 'alamarteogjd' AND folder = 'system';

DESINSTALACIÓN

El plugin NO deja:

• Tablas en base de datos
• Archivos huérfanos
• Configuraciones globales

Desinstalación limpia:

1. Sistema → Extensiones → Gestionar
2. Buscar "ALAMARTE OpenGraph"
3. Marcar checkbox
4. Click "Desinstalar"
5. Joomla elimina todo automáticamente

ENTORNOS DE DESARROLLO

DESARROLLO LOCAL

Probado en:
✓ XAMPP 8.2
✓ MAMP Pro 6.8
✓ Laravel Valet
✓ Docker (joomla:5-php8.2-apache)
✓ Local by Flywheel

STAGING

Recomendaciones:
• Probar actualizaciones en staging primero
• Validar con Facebook Debugger antes de producción
• Verificar imágenes accesibles desde staging

PRODUCCIÓN

Antes de deployment:
✓ Verificar PHP >= 8.1
✓ Confirmar Joomla >= 5.0
✓ Probar una categoría de prueba
✓ Validar con herramientas externas
✓ Documentar configuración

HERRAMIENTAS DE VALIDACIÓN

OBLIGATORIAS

1. Facebook Sharing Debugger
https://developers.facebook.com/tools/debug/

Qué valida:
• Tags Open Graph detectados
• Imagen cargando correctamente
• Tamaño de imagen válido
• Preview card completo

2. OpenGraph.xyz
https://www.opengraph.xyz/

Qué muestra:
• Preview Facebook + Twitter lado a lado
• Todos los tags detectados
• Problemas de validación
• Recomendaciones de mejora

OPCIONALES

3. Meta Tags Inspector
https://metatags.io/

4. LinkedIn Post Inspector
https://www.linkedin.com/post-inspector/

5. Twitter Card Validator
(Deprecado - usar OpenGraph.xyz)

CONFIGURACIÓN DEL NAVEGADOR

EXTENSIONES ÚTILES

Chrome/Edge:
• Open Graph Preview (extensión)
• Meta SEO Inspector
• Web Developer Toolbar

Firefox:
• Open Graph Preview Plus
• SEO Meta 1-Click

VERSIONES DE NAVEGADORES

Cualquier navegador moderno:
✓ Chrome 90+
✓ Firefox 88+
✓ Safari 14+
✓ Edge 90+

VERIFICACIÓN DE REQUISITOS

CHECKLIST PRE-INSTALACIÓN

[ ] Joomla 5.0+ instalado
[ ] PHP 8.1+ configurado
[ ] jDownloads instalado y funcionando
[ ] Acceso al panel de administración
[ ] Al menos una categoría jDownloads creada
[ ] Permisos de escritura en /tmp/ para instalación
[ ] Extensión mbstring habilitada en PHP
[ ] MySQL 5.7+ o MariaDB 10.3+

Si todos los checks = ✓ → LISTO PARA INSTALAR