roi-theme/wp-content/themes/apus-theme/inc/README-RELATED-POSTS.md

Related Posts - Documentación Técnica

Descripción General

Sistema de posts relacionados completamente configurable que muestra automáticamente posts similares al final de cada artículo individual basándose en categorías compartidas.

Archivos Creados

1. inc/related-posts.php (294 líneas)

Archivo principal con toda la lógica de posts relacionados:

Funciones Principales:

• apus_get_related_posts($post_id)

  • Obtiene posts relacionados por categoría
  • Retorna: WP_Query|false
  • Parámetros configurables vía get_option()
  • Optimizado con no_found_rows y desactivación de cache

• apus_display_related_posts($post_id = null)

  • Renderiza el HTML completo de posts relacionados
  • Grid responsive con Bootstrap 5
  • Soporte para posts con y sin imagen destacada
  • Fondos de color para posts sin imagen

• apus_get_column_class($columns)

  • Calcula clases de columna de Bootstrap según configuración
  • Soporta: 1, 2, 3 o 4 columnas
  • Retorna clases responsive (col-12, col-md-6, etc.)

• apus_hook_related_posts()

  • Hook automático en apus_after_post_content
  • Se ejecuta solo en single posts

• apus_enqueue_related_posts_styles()

  • Carga el CSS solo cuando es necesario
  • Dependencia: apus-bootstrap

• apus_related_posts_default_options()

  • Configura opciones por defecto en la base de datos
  • Se ejecuta en after_setup_theme

2. assets/css/related-posts.css (460 líneas)

Estilos completos para el sistema de posts relacionados:

Secciones Principales:

• Related Posts Section: Contenedor principal y título con línea decorativa
• Card Base: Estructura de tarjetas con sombras y transiciones
• Card with Thumbnail: Tarjetas con imagen destacada (aspect ratio 4:3)
• Card without Image: Tarjetas con fondo de color y título centrado
• Category Badge: Badge flotante con backdrop-filter
• Card Content: Título, excerpt y metadata
• Responsive: Breakpoints para tablet, mobile y small mobile
• Print Styles: Optimización para impresión
• Dark Mode: Soporte para prefers-color-scheme: dark
• Accessibility: Focus states y reduced motion

3. inc/admin/related-posts-options.php (220+ líneas)

Helpers y documentación para configuración:

• apus_get_related_posts_options(): Obtiene todas las opciones disponibles
• apus_update_related_posts_option(): Actualiza una opción específica
• apus_reset_related_posts_options(): Resetea a valores por defecto
• apus_get_related_posts_documentation(): Documentación estructurada

Opciones Configurables

Opciones Disponibles (WordPress Options API)

// Habilitar/deshabilitar
'apus_related_posts_enabled' => true|false (default: true)

// Título de la sección
'apus_related_posts_title' => string (default: 'Related Posts')

// Cantidad de posts
'apus_related_posts_count' => int (default: 3, min: 1, max: 12)

// Columnas en el grid
'apus_related_posts_columns' => int (default: 3, options: 1-4)

// Mostrar excerpt
'apus_related_posts_show_excerpt' => true|false (default: true)

// Longitud del excerpt
'apus_related_posts_excerpt_length' => int (default: 20, min: 5, max: 100)

// Mostrar fecha
'apus_related_posts_show_date' => true|false (default: true)

// Mostrar categoría
'apus_related_posts_show_category' => true|false (default: true)

// Colores de fondo para posts sin imagen
'apus_related_posts_bg_colors' => array (default: 6 colores)

Ejemplos de Configuración

Ejemplo 1: Cambiar título y cantidad

update_option('apus_related_posts_title', 'También te puede interesar');
update_option('apus_related_posts_count', 4);

Ejemplo 2: Layout de 2 columnas sin excerpt

update_option('apus_related_posts_columns', 2);
update_option('apus_related_posts_show_excerpt', false);

Ejemplo 3: Colores personalizados

update_option('apus_related_posts_bg_colors', array(
    '#FF6B6B', // Rojo
    '#4ECDC4', // Teal
    '#45B7D1', // Azul
    '#FFA07A', // Coral
    '#98D8C8', // Menta
    '#F7DC6F', // Amarillo
));

Ejemplo 4: Deshabilitar temporalmente

update_option('apus_related_posts_enabled', false);

Hooks y Filtros

Filter: apus_related_posts_args

Modifica los argumentos de WP_Query para posts relacionados:

add_filter('apus_related_posts_args', function($args, $post_id) {
    // Ordenar por fecha en vez de aleatorio
    $args['orderby'] = 'date';
    $args['order'] = 'DESC';

    // Solo posts de los últimos 6 meses
    $args['date_query'] = array(
        array('after' => '6 months ago')
    );

    // Excluir categoría específica
    $args['category__not_in'] = array(5);

    return $args;
}, 10, 2);

Action: apus_after_post_content

Hook donde se renderiza el contenido relacionado (ya implementado en single.php):

// En single.php (línea 210)
do_action('apus_after_post_content');

Características Técnicas

Performance

• ✅ Query optimizado con no_found_rows
• ✅ Cache desactivado para posts relacionados
• ✅ CSS cargado solo en single posts
• ✅ Lazy loading de imágenes
• ✅ Aspect ratio CSS nativo

Responsive Design

• ✅ Bootstrap 5 grid system
• ✅ Breakpoints: mobile (575px), tablet (768px), desktop (992px)
• ✅ Aspect ratio adaptativo (60% mobile, 75% desktop)
• ✅ Tamaños de fuente escalables

Accesibilidad

• ✅ Focus states visibles
• ✅ prefers-reduced-motion support
• ✅ Semantic HTML
• ✅ Alt text en imágenes
• ✅ Contraste de colores adecuado

SEO

• ✅ Estructura semántica con <article> y <section>
• ✅ Uso de <time> con datetime
• ✅ Enlaces con rel attributes
• ✅ Metadata estructurada

Print Styles

• ✅ Bordes en vez de sombras
• ✅ Oculta imágenes para ahorrar tinta
• ✅ Optimización de espacios
• ✅ Evita page breaks dentro de cards

Integración en el Tema

En functions.php

// Líneas 189-192
if (file_exists(get_template_directory() . '/inc/related-posts.php')) {
    require_once get_template_directory() . '/inc/related-posts.php';
}

En single.php

// Línea 210 - Hook existente
do_action('apus_after_post_content');

Enqueue de Estilos

El CSS se carga automáticamente via wp_enqueue_scripts solo en single posts:

wp_enqueue_style(
    'apus-related-posts',
    get_template_directory_uri() . '/assets/css/related-posts.css',
    array('apus-bootstrap'),
    APUS_VERSION,
    'all'
);

Comportamiento de Posts sin Imagen

Cuando un post relacionado no tiene imagen destacada:

1. Se genera un fondo de color usando la paleta configurada
2. El título se muestra centrado sobre el fondo de color
3. Se rota el color usando módulo sobre el array de colores
4. Category badge tiene estilo especial con backdrop-filter

Ejemplo Visual

┌─────────────────────────┐
│   ╔═══════════════╗    │
│   ║ [Categoría]   ║    │
│   ╚═══════════════╝    │
│                         │
│   Título del Post       │
│   Relacionado Aquí      │
│                         │
└─────────────────────────┘
  (Fondo de color sólido)

Testing

Casos de Prueba Recomendados

1. Post con 3+ posts relacionados: Verificar grid y layout
2. Post con 1-2 posts relacionados: Verificar responsive
3. Post sin posts relacionados: No debe mostrar sección
4. Posts sin categorías: No debe mostrar sección
5. Mix de posts con/sin imagen: Verificar colores rotatorios
6. Diferentes configuraciones de columnas: 1, 2, 3, 4
7. Diferentes viewport sizes: Mobile, tablet, desktop
8. Print preview: Verificar estilos de impresión
9. Dark mode: Si el navegador lo soporta
10. Reduced motion: Verificar que no haya animaciones

Comandos de Verificación

# Verificar archivos creados
ls -la wp-content/themes/apus-theme/inc/related-posts.php
ls -la wp-content/themes/apus-theme/assets/css/related-posts.css
ls -la wp-content/themes/apus-theme/inc/admin/related-posts-options.php

# Contar líneas
wc -l wp-content/themes/apus-theme/inc/related-posts.php
wc -l wp-content/themes/apus-theme/assets/css/related-posts.css

# Verificar funciones
grep "^function apus_" wp-content/themes/apus-theme/inc/related-posts.php

# Verificar inclusión en functions.php
grep "related-posts" wp-content/themes/apus-theme/functions.php

Troubleshooting

Los posts relacionados no aparecen

1. Verificar que está habilitado:

   var_dump(get_option('apus_related_posts_enabled'));
   

2. Verificar que el post tiene categorías:

   var_dump(wp_get_post_categories(get_the_ID()));
   

3. Verificar que hay posts en la misma categoría:

   $query = apus_get_related_posts(get_the_ID());
   var_dump($query ? $query->post_count : 'No query');
   

El CSS no se carga

1. Verificar ruta del archivo:

   var_dump(file_exists(get_template_directory() . '/assets/css/related-posts.css'));
   

2. Limpiar cache del navegador

3. Verificar que estás en single post:

   var_dump(is_single() && !is_attachment());
   

Los colores no cambian

1. Verificar array de colores:

   var_dump(get_option('apus_related_posts_bg_colors'));
   

2. Verificar que hay posts sin imagen en los relacionados

Compatibilidad

• ✅ WordPress 5.0+
• ✅ PHP 7.4+
• ✅ Bootstrap 5.3.8
• ✅ Navegadores modernos (últimas 2 versiones)
• ✅ IE11 con degradación graceful

Mantenimiento Futuro

Posibles Mejoras

1. Panel de administración: Interfaz visual en el admin de WordPress
2. Más criterios de relación: Tags, autor, custom taxonomies
3. Cache inteligente: Transients API para queries
4. Shortcode: Para mostrar relacionados en cualquier lugar
5. Widget: Para sidebar
6. AJAX loading: Carga asíncrona de posts
7. Infinite scroll: Para móvil
8. A/B testing: Diferentes layouts

Consideraciones de Actualización

• Mantener retrocompatibilidad con opciones existentes
• Documentar cambios en CHANGELOG
• Probar con diferentes configuraciones
• Verificar performance en sitios grandes

Issue Relacionado

Issue #13: Posts relacionados configurables - ✅ COMPLETADO

Fecha de Implementación: 2025-11-03

Desarrollador: Claude Code (Anthropic)