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)

```php
// 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
```php
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
```php
update_option('apus_related_posts_columns', 2);
update_option('apus_related_posts_show_excerpt', false);
```

#### Ejemplo 3: Colores personalizados
```php
update_option('apus_related_posts_bg_colors', array(
    '#FF6B6B', // Rojo
    '#4ECDC4', // Teal
    '#45B7D1', // Azul
    '#FFA07A', // Coral
    '#98D8C8', // Menta
    '#F7DC6F', // Amarillo
));
```

#### Ejemplo 4: Deshabilitar temporalmente
```php
update_option('apus_related_posts_enabled', false);
```

## Hooks y Filtros

### Filter: `apus_related_posts_args`
Modifica los argumentos de WP_Query para posts relacionados:

```php
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`):

```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`
```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`
```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:

```php
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

```bash
# 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**:
   ```php
   var_dump(get_option('apus_related_posts_enabled'));
   ```

2. **Verificar que el post tiene categorías**:
   ```php
   var_dump(wp_get_post_categories(get_the_ID()));
   ```

3. **Verificar que hay posts en la misma categoría**:
   ```php
   $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**:
   ```php
   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**:
   ```php
   var_dump(is_single() && !is_attachment());
   ```

### Los colores no cambian

1. **Verificar array de colores**:
   ```php
   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)