Docs Documentación

Historias y paneles

Las historias son narrativas desplazables construidas alrededor de tus objetos. Cada historia guía al público a través de una secuencia de pasos — enfocando regiones específicas de imágenes, momentos en videos o segmentos de grabaciones de audio — con pares de pregunta-respuesta y paneles de detalle expandibles.

El editor de historias del Compositor ofrece una alternativa visual a editar las hojas de cálculo directamente. Permite construir y reordenar pasos, configurar coordenadas y previsualizar la historia sin salir del navegador.

Cómo funciona la experiencia de desplazamiento

Una historia llena la ventana del navegador con un diseño de tarjetas apiladas. El objeto — ya sea una imagen en el visor IIIF, un reproductor de video o un reproductor de audio — ocupa todo el fondo. Las tarjetas de texto se superponen encima y, al desplazarse, cada tarjeta nueva se desliza sobre la anterior.

El desplazamiento es continuo con puntos de anclaje magnético. En lugar de avanzar discretamente de paso en paso, el desplazamiento es natural. La vista se ancla magnéticamente a cada paso, asegurando que la tarjeta de texto y la posición del objeto se mantengan sincronizadas.

En dispositivos móviles, las tarjetas de texto se anclan en la parte inferior de la pantalla con un efecto de vidrio esmerilado, superponiéndose sobre la parte inferior del visor.

Visor de historia con diseño de tarjetas apiladas y tarjeta de texto sobre el visor IIIF

Cada paso:

  1. Enfoca el visor en una región específica de un objeto (usando coordenadas x, y y zoom para imágenes, o tiempos de clip para video y audio)
  2. Muestra una pregunta y una breve respuesta en la tarjeta de texto
  3. Opcionalmente ofrece hasta dos capas adicionales de detalle mediante botones expandibles

Registrar historias

Antes de construir los pasos de una historia, regístrala en project.csv:

order,story_id,title,subtitle,byline
1,textiles-coloniales,Textiles Coloniales,Tradiciones de tejido de las Américas,por Dra. María García

El story_id determina el nombre del archivo CSV de la historia y su URL. Con story_id: textiles-coloniales, Telar busca telar-content/spreadsheets/textiles-coloniales.csv y sirve la historia en /stories/textiles-coloniales/.

Si se omite story_id, Telar usa story-{order} (ej., story-1.csv para order 1).

Consulta la Referencia CSV: Proyecto para todas las columnas de project.csv.

Construir los pasos de la historia

Cada historia tiene su propio archivo CSV en telar-content/spreadsheets/. El archivo define los pasos en secuencia:

step,object,x,y,zoom,question,answer,layer1_content
1,textile-001,0.5,0.3,0.8,¿Qué es este textil?,Un fragmento colonial con patrones complejos de tejido,Este fragmento data de mediados del siglo XVII...
2,textile-001,0.2,0.7,0.4,¿Qué significa este patrón?,Un diseño de urdimbre entrelazada usado en telas ceremoniales,El patrón ha sido identificado como...
3,map-lima,0.5,0.5,1.0,¿Dónde se encontraron estos textiles?,En el centro histórico de Lima,Las excavaciones arqueológicas de los años 1990...

Campos requeridos

Cada paso necesita:

Coordenadas

Las coordenadas indican al visor dónde enfocar en cada paso. Todos los valores están normalizados de 0 a 1:

Para encontrar coordenadas, usa el selector de coordenadas en cualquier página de objeto: amplía y desplázate hasta la región que deseas, luego haz clic en los botones Copy para copiar los valores x, y y zoom directamente a tu hoja de cálculo.

Selector de coordenadas mostrando valores X, Y y Zoom debajo del visor de imágenes

Tarjetas de título

Las tarjetas de título son pasos de solo texto, sin objeto asociado. Funcionan bien como encabezados de capítulo, separadores de sección o transiciones temáticas dentro de una historia.

Para crear una tarjeta de título, deja vacía la columna objeto. Las columnas x, y y zoom se ignoran. El campo pregunta se convierte en el encabezado de la tarjeta y respuesta en el subtítulo.

paso,objeto,x,y,zoom,pregunta,respuesta
1,textile-001,0.5,0.3,0.8,¿Qué es este textil?,Un fragmento colonial con patrones complejos de tejido.
2,,,,,Capítulo 2: Rutas comerciales,El movimiento de textiles a través de las Américas.
3,map-lima,0.5,0.5,1.0,¿Dónde se encontraron?,En el centro histórico de Lima.

Las tarjetas de título participan plenamente en la navegación — el desplazamiento, el teclado y los enlaces profundos funcionan como se espera. También pueden tener capas de paneles, igual que cualquier otro paso.

Tabla de contenidos de secciones

Si la historia usa tarjetas de título como encabezados de capítulo, se puede mostrar una tabla de contenidos navegable en la tarjeta de inicio. Actívala agregando mostrar_secciones: si (o show_sections: yes) en la fila de la historia en project.csv.

Cuando está activada, la tarjeta de inicio recorre la historia en busca de tarjetas de título y las lista como enlaces clicables. Al hacer clic en un enlace se salta directamente a esa sección. La tarjeta de inicio también cambia a un fondo más oscuro (el color del panel de nivel 2) para distinguirla visualmente.

Si el primer capítulo comienza inmediatamente después de la tarjeta de inicio, crea también una tarjeta de título para ese capítulo. La tabla de contenidos solo lista las tarjetas de título que existan en el CSV de la historia — si el capítulo 1 no tiene tarjeta de título, no aparecerá en la tabla de contenidos.

Consulta Columnas del proyecto para la referencia de la columna mostrar_secciones.

Botón de volver al comienzo

Cuando se avanza más allá de la tarjeta de inicio, el botón “Volver al inicio” en la esquina superior izquierda cambia a “Comienzo”. Al hacer clic regresa a la tarjeta de inicio. En la tarjeta de inicio, el botón vuelve a mostrar “Volver al inicio” y enlaza a la página principal.

Esto es automático — no requiere configuración.

Capas de los paneles

Cada paso puede tener hasta dos capas de detalle adicional, siguiendo el patrón QAI (pregunta, respuesta, invitación). La pregunta y la respuesta aparecen en la tarjeta de texto. La invitación es el conjunto de botones que abren paneles expandibles con contenido más profundo:

Capa Texto predeterminado del botón Propósito
Capa 1 “Saber más” Panel de detalle principal
Capa 2 “Profundizar más” Panel de detalle secundario, que se abre sobre la Capa 1

Para cada capa, agrega dos columnas a la hoja de cálculo de tu historia:

Si una capa no tiene contenido, su botón se oculta automáticamente. A la Capa 2 se accede desde dentro de la Capa 1: su botón aparece al final del panel de la Capa 1, no en la tarjeta de texto principal.

Escribir contenido para los paneles

El contenido de los paneles se puede proporcionar de tres maneras. La elección depende de la complejidad:

Método 1: introducir texto directamente

Escribe el texto directamente en la celda de la hoja de cálculo. Ideal para paneles cortos (1–2 párrafos).

layer1_content
"Este fragmento muestra **técnicas avanzadas de tejido** del periodo colonial."

Se puede usar formato básico: **negrita**, *cursiva*, [texto del enlace](url) y enlaces de glosario ([[term-id]]).

Para saltos de línea dentro de una celda:

Método 2: pegar texto markdown

Pega texto escrito en un editor de texto plano. Esto admite la gama completa de características markdown, incluyendo encabezados, widgets (acordeón, carrusel, pestañas), controles de tamaño de imagen y un título de panel personalizado usando frontmatter YAML.

Si se copia y pega desde Microsoft Word, Google Docs o aplicaciones similares, el formato no se preservará. Escribe con sintaxis markdown en su lugar — consulta la Guía de sintaxis markdown.

Método 3: indicar un archivo markdown

Indica la ruta a un archivo markdown en el repositorio. Ideal para paneles complejos — especialmente aquellos con widgets o contenido que se quiera reutilizar en varios pasos.

layer1_content
textiles-coloniales/step1-layer1.md

Guarda los archivos markdown en telar-content/texts/stories/. En la hoja de cálculo, ingresa solo el nombre del archivo — o si los archivos están organizados en subcarpetas, incluye el nombre de la subcarpeta.

Cómo decide Telar: Si lo ingresado termina en .md y el archivo existe, se carga el archivo. De lo contrario, el valor se trata como contenido.

Elegir el método correcto

Escenario Método recomendado
Explicación corta (1–2 párrafos) Método 1: Introducir directamente
Panel con título personalizado o widgets Método 2: Pegar, o Método 3: Archivo
Contenido con widgets (acordeón, pestañas, carrusel) Método 3: Archivo
Mismo contenido usado en varios lugares Método 3: Archivo
Ediciones rápidas sin salir de la hoja de cálculo Método 1 o 2

Archivos markdown de las historias

Al usar el Método 3 (archivos), los archivos markdown de las historias se ubican en telar-content/texts/stories/:

telar-content/texts/stories/
├── textiles-coloniales/
│   ├── step1-layer1.md
│   ├── step1-layer2.md
│   ├── step2-layer1.md
│   └── step2-layer2.md
└── rutas-comerciales/
    ├── step1-layer1.md
    └── step1-layer2.md

Organizar los archivos en subcarpetas por historia facilita el manejo a medida que crece el sitio.

Título del panel

Agrega un título de panel personalizado usando frontmatter YAML:

---
title: "Técnicas de tejido"
---

El patrón de urdimbre entrelazada visible aquí indica una técnica
de tejido compleja que era común en el periodo colonial.

Si se omite el frontmatter, el panel no tiene título — el contenido comienza de inmediato.

Qué se puede usar en los paneles

Los paneles de las historias admiten:

Pasos multimedia

Los pasos de una historia pueden hacer referencia a cualquier tipo de objeto — no solo imágenes. Cuando un paso referencia un objeto de video o audio, el área del visor cambia automáticamente al reproductor correspondiente.

No se necesita configuración adicional. Telar detecta el tipo de objeto desde la hoja de cálculo de objetos y carga el reproductor correcto.

Control de clips

Para pasos de video y audio se puede especificar un tiempo de inicio, un tiempo de fin y un ajuste de bucle. Agrega estas columnas a la hoja de cálculo de la historia:

Columna (inglés) Columna (español) Descripción
clip_start inicio_clip Tiempo de inicio en segundos (ej. 12.5)
clip_end fin_clip Tiempo de fin en segundos
loop bucle Repetir el clip (true, yes o sí)

Las tres columnas son opcionales. Si se omiten, el medio se reproduce desde el inicio sin repetición.

step,object,clip_start,clip_end,loop,question,answer
1,interview-01,45,78,false,¿Qué describe ella?,La técnica de tejido utilizada en su comunidad.
2,field-recording,0,30,true,¿Qué sonidos rodean el taller?,El golpeteo rítmico del telar llena el espacio.

Los tiempos de clip también se pueden configurar visualmente con la interfaz de captura del Compositor. Consulta Video y audio en el Compositor para más detalles.

Consulta la Referencia CSV: Historias para la referencia completa de columnas incluyendo las columnas de clip.

Texto alternativo

Cada paso puede incluir una columna alt_text con una descripción de lo que se ve o se escucha en ese punto de la historia. Este texto es utilizado por lectores de pantalla y otras tecnologías de asistencia.

step,object,x,y,zoom,alt_text,question,answer
1,textile-001,0.5,0.3,0.8,Primer plano de hilos de urdimbre entrelazados en rojo y dorado,¿Qué es este textil?,Un fragmento colonial con patrones complejos de tejido.

El texto alternativo de cada paso también se puede configurar en el editor de pasos del Compositor.

Las historias admiten navegación por teclado. Las teclas de flecha, la barra espaciadora y Page Up/Page Down desplazan la historia, y los puntos de anclaje magnético aseguran que cada pulsación llegue al paso siguiente o anterior.

Cuando un panel está abierto, el comportamiento del teclado cambia: Flecha Arriba/Abajo y Page Up/Page Down desplazan el contenido del panel en lugar de navegar entre pasos. La barra espaciadora desplaza el panel hacia adelante y Shift+Espacio lo desplaza hacia atrás.

Compartir y enlaces profundos

Telar actualiza automáticamente la URL en la barra de direcciones del navegador a medida que se avanza por la historia. La URL codifica el paso actual y cualquier capa de panel abierta, de modo que se puede copiar y compartir un enlace que abra directamente un punto específico de la historia.

El fragmento de la URL usa un formato compacto:

Fragmento Significado
#s3 Paso 3
#s3l1 Paso 3 con el primer panel de detalle abierto

Al abrir un enlace profundo, la historia salta directamente al paso codificado y abre el panel si se especificó uno. Esto funciona tanto con la navegación por desplazamiento en escritorio como con la navegación por botones en dispositivos móviles.

El botón de retroceso del navegador regresa a la página anterior — no al paso anterior. Los enlaces profundos están diseñados para compartir posiciones, no para navegar dentro de una historia.

Controlar la visualización de las historias

Ocultar historias de la página principal

Si deseas tener objetos en la página principal pero prefieres que las historias se accedan a través de la navegación o enlaces directos:

story_interface:
  show_on_homepage: false

Las historias siguen accesibles en sus URL — solo se ocultan las tarjetas de la página principal.

Ocultar indicadores de paso

Los indicadores “Step 1”, “Step 2” en la esquina superior izquierda del visor de la historia se pueden ocultar para una experiencia más limpia:

story_interface:
  show_story_steps: false

Quienes visitan pueden seguir navegando por los pasos normalmente.

Véase también