Plantillas

🎨 Cómo crear un nuevo Template en Turnero

Este documento explica la estructura básica de un template dentro de Turnito, cómo integrarlo en index.php y cómo abrirlo en el navegador.

📁 Estructura de carpetas

Cada template tiene su propia carpeta dentro de /turnero/template/ con al menos estos archivos:

/turnero/template/

├─ screen.php ← Router que carga el template según tpl=...
├─ index.php ← [ACTUALIZADO] Menú con botones para elegir cada template
└─ <nombre-template>/
├─ layout.php ← Código PHP + HTML del template
└─ style.css ← Estilos propios (independiente, sin dependencias)

📄 Archivo layout.php

El layout.php de un template debe:

1. Recibir variables globales de screen.php:

código PHP

/** @var array $TEMPLATE_VARS */
extract($TEMPLATE_VARS, EXTR_SKIP);

(Variables disponibles: $title, $logo, $API, $PUBLIC, $queueId, $marquee, $TPL_STYLE, etc.)

2. Implementar el HTML y CSS del template:

• Incluir su propio CSS: <link rel="stylesheet" href="<?= htmlspecialchars($TPL_STYLE) ?>">
• [NUEVO] Dependencias Externas: Si un template requiere un framework como Tailwind CSS, debe ser cargado aquí, usualmente desde un CDN. Esto puede hacer que el template no funcione offline.
  html <!-- Ejemplo para un template que usa Tailwind CSS --> <script src="https://cdn.tailwindcss.com"></script>

3. Cargar datos en vivo desde la API usando JavaScript:

• queues_state.php → Turno actual, historial y siguientes.
• ads.php → Publicidad.
• marquee.php → Texto de marquesina.

⚙️ Entendiendo la API queues_state.php

Para construir un template funcional, es crítico entender la estructura del JSON que devuelve la API.

Ejemplo de respuesta de la API:

código JSON

{
  "ok": true,
  "queue_id": 1,
  "prefix": "C",
  "pad": 3,
  "current": 7,
  "next": [8, 9, 10],
  "last_calls": [
    {"number": 7, "counter": 1},
    {"number": 6, "counter": 3}
  ],
  "updated_at": 1759612278
}

Lógica recomendada en JavaScript para procesar los turnos:

La forma más robusta de mostrar los turnos es seguir esta prioridad, ya que no todos los campos están siempre presentes:

1. Priorizar el historial (last_calls): Si el array last_calls (o recent, served) existe y tiene elementos, úsalo como la fuente principal de verdad. El primer elemento es el más reciente (el turno actual).
2. Fallback a current y next: Si no hay historial, construye la lista combinando:
   • El turno current.
   • El historial de prev (si existe).
   • Los siguientes turnos de next.

codeJavaScript

// Ejemplo de la lógica de procesamiento en JavaScript
function processApiData(j) {
    const PAD = j.pad || 3;
    const pre = j.prefix || 'C';
    const MAX_ITEMS = 7; // 1 actual + 6 en lista
    
    // 1. Prioridad al historial
    const hist = j.last_calls || j.recent || [];
    if (Array.isArray(hist) && hist.length > 0) {
        return hist.slice(0, MAX_ITEMS).map(h => ({
            ticket: `${pre}${String(h.number).padStart(PAD, '0')}`
        }));
    }

    // 2. Fallback
    if (j.current === null) return [];
    const base = [{ ticket: `${pre}${String(j.current).padStart(PAD, '0')}` }];
    const nx = (j.next || []).map(n => ({ ticket: `${pre}${String(n).padStart(PAD, '0')}` }));
    return base.concat(nx).slice(0, MAX_ITEMS);
}

🎨 Archivo style.css

Cada template tiene su CSS autónomo. Si el template usa un framework externo (ej. Tailwind), este archivo se usa para definir variables globales (:root) y estilos personalizados o sobreescrituras.

🔘 Integración en index.php

El archivo /turnero/template/index.php muestra el menú de templates. Cada entrada se define en el array $templates:

codePHP

[
  'key'   => 'tailwindshop',           // Nombre de la carpeta
  'label' => 'Tailwind Shop',          // Texto del botón
  'desc'  => 'Diseño moderno con carrusel de ofertas.',
  'color' => '#D52B1E',                 
  'icon'  => 'store',                  // Ícono SVG (definido en el mismo archivo)
],

🌐 Estructura de URLs

Todos los templates se acceden mediante screen.php:

http://localhost/turnero/template/screen.php?tpl=<nombre-template>&queue_id=<id>

Parámetros:

• tpl: Carpeta del template.
• queue_id: ID de la cola.
• title: Título mostrado en pantalla.
• next_limit: (Opcional) Número máximo de turnos "siguientes" que se piden a la API. &next_limit=10.

✅ Notas de Desarrollo y Depuración

• La API falla silenciosamente: Por diseño, los scripts de la API (/api/*.php) tienen los errores de PHP desactivados (error_reporting(0)). Si un template no carga datos y la consola de JavaScript está vacía, es muy probable que haya un error de PHP en el servidor (ej. fallo de conexión a la base de datos).
• Mejor forma de depurar:
  1. Abre la URL de la API directamente en el navegador (ej: http://localhost/turnero/api/queues_state.php?queue_id=1). Si ves una página en blanco, hay un error de PHP.
  2. Para ver el error, comenta temporalmente error_reporting(0) en el script de la API.
  3. Usa la pestaña "Red" (Network) de las herramientas de desarrollador (F12) para inspeccionar la respuesta de la API.