Docs Documentación

Historias y paneles

Las historias son narrativas que se leen desplazándose y se construyen en torno a los objetos. Cada historia lleva al público por una secuencia de pasos — que enfocan regiones concretas de las imágenes, momentos de los videos o segmentos de las grabaciones de audio — con pares de pregunta y respuesta y paneles de detalle expandibles.

El editor de historias del Compositor te permite hacer lo mismo sin editar las hojas de cálculo a mano: 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. El objeto — ya sea una imagen en el visor IIIF, un reproductor de video o uno de audio — ocupa todo el fondo. A medida que se avanza en la historia, las tarjetas de texto pasan por encima una tras otra, en lugar de quedar apiladas.

El desplazamiento es continuo con puntos de anclaje magnético. En lugar de saltar de un paso a otro, el público se desplaza con naturalidad por la historia. La vista se ancla magnéticamente a cada paso, de modo que la tarjeta de texto y la posición del objeto se mantienen sincronizadas.

En los teléfonos y las tabletas en orientación vertical, la tarjeta de texto va anclada al borde inferior de la pantalla, encima de la parte baja del objeto.

Página de una historia con una tarjeta de texto sobre el visor IIIF

Cada paso:

  1. Enfoca una parte 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. Puede ofrecer 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} (p. ej., story-1.csv si order es 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 le indican al visor dónde enfocar en cada paso. Los valores de x y y van 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. Las tarjetas de título no admiten paneles de capas — las columnas de capa se ignoran, igual que x, y y zoom.

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. Al hacer clic en uno 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 de 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 entra desde 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

Puedes escribir el contenido de los paneles de tres maneras. Elige según la complejidad del contenido:

Los tres métodos que siguen son para quien trabaja en una hoja de cálculo. En el Compositor, el título del panel tiene su propio campo, y todo lo que pegues en el campo Contenido —incluido un bloque ---— se publica como parte del texto del panel, no como título.

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."

Puedes 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. Así puedes usar todas las funciones de Markdown: encabezados, widgets (acordeón, carrusel, pestañas), control del tamaño de las imágenes y un título de panel propio con frontmatter YAML.

Si copias y pegas desde Microsoft Word, Google Docs o aplicaciones similares, el formato no se conservará. Escribe directamente en sintaxis Markdown — 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 — sobre todo los que llevan 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 el valor termina en .md y ese archivo existe, Telar carga el archivo; si no, trata el valor 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 omites el frontmatter, el panel no tiene título — el contenido comienza de inmediato.

Esto vale para los paneles que se escriben en una hoja de cálculo o en un archivo Markdown. En el Compositor, el título del panel tiene su propio campo, y un bloque --- que pegues en el campo Contenido se publica como parte del texto del panel, no como título.

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 apunta a un objeto de video o audio, en lugar del visor de imágenes aparece el reproductor correspondiente.

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

Control de clips

En los pasos de video y audio puedes fijar un tiempo de inicio, un tiempo de fin y la repetición en 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 (p. 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.

También puedes fijar los tiempos del clip de forma visual en el 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. Los lectores de pantalla y otras tecnologías de asistencia usan este texto.

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 como con la navegación por botones.

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 a las historias se llegue por 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 Paso 1, Paso 2 de la esquina superior izquierda de la página de la historia se pueden ocultar para una vista más despejada:

story_interface:
  show_story_steps: false

Quien lee puede seguir navegando por los pasos con normalidad.

Véase también