Telar: Docs Telar: Documentación

Referencia de columnas CSV

Referencia completa para todas las columnas CSV en Telar con soporte de nombres de columnas bilingües.

Descripción general

Telar v0.6.0+ admite columnas CSV en inglés y español. Puedes usar cualquier idioma de forma consistente, mezclarlos, o incluir encabezados duales para referencia bilingüe.

Normalización de columnas

Todos los nombres de columna se normalizan durante el procesamiento:

Soporte de encabezados duales

Incluye encabezados en inglés y español para equipos bilingües:

order,story_id,title,subtitle,byline
orden,id_historia,titulo,subtitulo,firma
1,colonial-textiles,Colonial Textiles,Weaving traditions,by Dr. Smith
2,textiles-coloniales,Textiles Coloniales,Tradiciones textiles,por Dra. García

Telar detecta automáticamente y omite la segunda fila de encabezado.

CSV de proyecto (project.csv / proyecto.csv)

Define historias y su orden de visualización en la página de inicio.

Ubicación: components/structures/project.csv o components/structures/proyecto.csv

Columnas

Inglés Español Requerido Descripción
order orden Sí Orden de visualización en la página de inicio (1, 2, 3…)
story_id id_historia No Identificador semántico (ej., textiles-coloniales). Si se omite, usa story-{orden}
title titulo Sí Título de historia mostrado en la página de inicio y página de historia
subtitle subtitulo Sí Descripción breve mostrada en tarjetas de historia
byline firma No Atribución de autoría; admite markdown para enlaces y formato

Ejemplo

Inglés:

order,story_id,title,subtitle,byline
1,colonial-textiles,Colonial Textiles,Weaving traditions of the Americas,by Dr. Jane Smith
2,trade-routes,Trade Routes,Following the threads of commerce,based on [original research](https://example.com)

Español:

orden,id_historia,titulo,subtitulo,firma
1,textiles-coloniales,Textiles Coloniales,Tradiciones de tejido de las Américas,por Dra. María García
2,rutas-comerciales,Rutas Comerciales,Siguiendo los hilos del comercio,basado en [investigación original](https://ejemplo.com)

Notas de campo

order / orden

story_id / id_historia

title / titulo

subtitle / subtitulo

byline / firma

CSV de objetos (objects.csv / objetos.csv)

Cataloga todos los objetos usados en historias.

Ubicación: components/structures/objects.csv o components/structures/objetos.csv

Columnas

Inglés Español Requerido Descripción
object_id objeto Sí Identificador único (minúsculas, guiones, guiones bajos)
title titulo Sí Título del objeto
description descripcion No Descripción de formato largo (se admite markdown)
creator creador No Nombre del creador o artista
date fecha / periodo No Fecha de creación o período
medium medio No Material o medio
dimensions dimensiones No Dimensiones físicas
location ubicacion / locacion No Ubicación actual o repositorio
credit credito No Atribución o línea de crédito
thumbnail miniatura No Ruta a imagen en miniatura
iiif_manifest manifiesto_iiif No URL a manifiesto IIIF externo
source_url url_fuente No URL de info.json de imagen IIIF

Ejemplo

Inglés:

object_id,title,description,creator,date,medium,dimensions,location,credit,thumbnail,source_url
textile-001,Colonial Textile,A woven fragment showing complex patterns...,Unknown,circa 1650,Wool,45 x 60 cm,National Museum,Public Domain,,
map-lima,Map of Lima,Early colonial map showing city layout,Juan de Cuellar,1685,Ink on paper,30 x 40 cm,,,map-thumb.jpg,https://example.org/iiif/map/info.json

Español:

objeto,titulo,descripcion,creador,periodo,medio,dimensiones,ubicacion,credito,miniatura,url_fuente
textil-001,Textil Colonial,Un fragmento tejido con patrones complejos...,Desconocido,circa 1650,Lana,45 x 60 cm,Museo Nacional,Dominio Público,,
mapa-lima,Mapa de Lima,Mapa colonial temprano mostrando el diseño de la ciudad,Juan de Cuellar,1685,Tinta sobre papel,30 x 40 cm,,,mapa-miniatura.jpg,https://ejemplo.org/iiif/mapa/info.json

Notas de campo

object_id / objeto

description / descripcion

date / fecha / periodo

credit / credito

iiif_manifest / manifiesto_iiif

source_url / url_fuente

CSV de historia (story-{id}.csv / historia-{id}.csv)

Define navegación paso a paso y contenido de panel para cada historia.

Ubicación: components/structures/{story_id}.csv o components/structures/historia-{story_id}.csv

Nomenclatura:

Columnas

Inglés Español Requerido Descripción
step paso Sí Número de paso (1, 2, 3…)
object objeto Sí ID de objeto de objects.csv
x x Sí Coordenada horizontal (0-1 normalizado)
y y Sí Coordenada vertical (0-1 normalizado)
zoom zoom Sí Nivel de zoom (0-1 normalizado)
question pregunta Sí Encabezado mostrado en panel de historia
answer respuesta Sí Texto de respuesta breve
layer1_button boton_capa1 No Texto de botón personalizado (vacío = “Saber más”)
layer1_file archivo_capa1 Sí Ruta a archivo markdown de capa 1
layer2_button boton_capa2 No Texto de botón personalizado (vacío = “Profundizar más”)
layer2_file archivo_capa2 No Ruta a archivo markdown de capa 2
layer3_button boton_capa3 No Texto de botón personalizado (vacío = predeterminado)
layer3_file archivo_capa3 No Ruta a archivo markdown de capa 3

Ejemplo

Inglés:

step,object,x,y,zoom,question,answer,layer1_button,layer1_file,layer2_button,layer2_file
1,textile-001,0.5,0.5,1.0,What is this?,A colonial textile fragment,"",colonial-textiles/step1-layer1.md,"Learn More",colonial-textiles/step1-layer2.md
2,textile-001,0.3,0.7,0.5,What is this pattern?,An interlocking warp design,"",colonial-textiles/step2-layer1.md,"",colonial-textiles/step2-layer2.md

Español:

paso,objeto,x,y,zoom,pregunta,respuesta,boton_capa1,archivo_capa1,boton_capa2,archivo_capa2
1,textil-001,0.5,0.5,1.0,¿Qué es esto?,Un fragmento de textil colonial,"",textiles-coloniales/paso1-capa1.md,"Saber más",textiles-coloniales/paso1-capa2.md
2,textil-001,0.3,0.7,0.5,¿Qué es este patrón?,Un diseño de urdimbre entrelazada,"",textiles-coloniales/paso2-capa1.md,"",textiles-coloniales/paso2-capa2.md

Notas de campo

step / paso

object / objeto

x, y, zoom

question / pregunta

answer / respuesta

layer buttons / botones de capa

layer files / archivos de capa

Nombres de columnas alternativos

Mapeos completos de todos los nombres de columna aceptados.

Alias de CSV de proyecto

Normalizado Acepta
order order, orden, number, numero, num
story_id story_id, id_historia, story-id, story
title title, titulo, name, nombre
subtitle subtitle, subtitulo, description, descripcion, desc
byline byline, firma, author, autor, attribution, atribucion

Alias de CSV de objetos

Normalizado Acepta
object_id object_id, objeto, object, id
title title, titulo, name, nombre
description description, descripcion, desc
creator creator, creador, artist, artista, author, autor
date date, fecha, period, periodo
medium medium, medio, material
dimensions dimensions, dimensiones, size, tamaño
location location, ubicacion, locacion, repository, repositorio
credit credit, credito, attribution, atribucion
thumbnail thumbnail, miniatura, thumb
iiif_manifest iiif_manifest, manifiesto_iiif, manifest, manifiesto
source_url source_url, url_fuente, iiif_source_url, iiif_url

Alias de CSV de historia

Normalizado Acepta
step step, paso, number, numero, num
object object, objeto, object_id
x x, horizontal, left
y y, vertical, top
zoom zoom, z, scale
question question, pregunta, heading, encabezado
answer answer, respuesta, response
layer1_button layer1_button, boton_capa1, button1, btn1
layer1_file layer1_file, archivo_capa1, file1, layer1
layer2_button layer2_button, boton_capa2, button2, btn2
layer2_file layer2_file, archivo_capa2, file2, layer2
layer3_button layer3_button, boton_capa3, button3, btn3
layer3_file layer3_file, archivo_capa3, file3, layer3

Mejores prácticas

Elegir nombres de columnas

Sitios monolingües: Usa tu idioma preferido de forma consistente

# Sitio en inglés
order,story_id,title,subtitle,byline

# Sitio en español
orden,id_historia,titulo,subtitulo,firma

Equipos bilingües: Usa encabezados duales

order,story_id,title,subtitle,byline
orden,id_historia,titulo,subtitulo,firma

Entornos mixtos: Se admite mezcla pero no se recomienda

order,id_historia,title,subtitulo,byline  # Funciona pero confuso

Organización de archivos

Estructura recomendada:

components/structures/
├── project.csv              # Inglés
├── objects.csv
├── colonial-textiles.csv    # Usando story_id
└── trade-routes.csv

# O

components/structures/
├── proyecto.csv             # Español
├── objetos.csv
├── textiles-coloniales.csv
└── rutas-comerciales.csv

Nomenclatura de story_id:

Consejos de entrada de datos

Coordenadas:

  1. Usar herramienta de coordenadas en páginas de objetos
  2. Hacer clic para identificar valores de x, y, zoom
  3. Copiar valores directamente en CSV
  4. Probar en visor de historia

Markdown en campos:

Referencias de archivo:

Validación

Telar valida datos CSV durante la compilación:

Errores (falla la compilación):

Advertencias (compilación exitosa):

Verificar salida de compilación para mensajes de validación.

Migración de versiones anteriores

De v0.5.x a v0.6.0

Nuevas funcionalidades:

Cambios incompatibles: Ninguno. Todos los CSVs de v0.5.x funcionan sin modificación.

Actualizaciones recomendadas:

  1. Agregar story_id a project.csv para nomenclatura semántica
  2. Renombrar CSVs de historia para coincidir con story_id
  3. Considerar usar nombres de columna en español si es apropiado
  4. Agregar enlaces markdown a bylines si se desea

De v0.4.x a v0.6.0

Cambios adicionales:

Solución de problemas

Errores “Column not found”

Causa: Nombre de columna no reconocido Solución: Verificar ortografía, usar nombres de la referencia anterior

Errores “Duplicate object_id”

Causa: Mismo object_id usado dos veces en objects.csv Solución: Hacer cada object_id único

Errores “Invalid step sequence”

Causa: Pasos no secuenciales (1, 2, 4) o pasos duplicados Solución: Asegurar que los pasos sean 1, 2, 3, 4… sin brechas

Errores “File not found”

Causa: Archivo markdown referenciado pero no existe Solución: Crear archivo o eliminar referencia de archivo del CSV

Las coordenadas no funcionan

Causa: Valores fuera del rango 0-1 o object_id incorrecto Solución: Usar herramienta de coordenadas, verificar que el objeto existe

Ver también

Nuevo en v0.6.0: Soporte de CSV bilingüe con nombres de columna en español y encabezados duales.