From 1e23b67c7fc075d74224ad4653d3ad617c8f2724 Mon Sep 17 00:00:00 2001 From: f Date: Thu, 17 May 2018 15:56:06 -0300 Subject: [PATCH] documentacion de plantillas --- doc/plantillas.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 doc/plantillas.md diff --git a/doc/plantillas.md b/doc/plantillas.md new file mode 100644 index 00000000..3ad9356e --- /dev/null +++ b/doc/plantillas.md @@ -0,0 +1,180 @@ +# Plantillas de artículos + +Las plantillas de artículos son archivos YML con la estructura de campos +a utilizar en la creación de un artículo. Dependiendo del tipo de +artículo que elijamos, el editor del artículo cargará los campos +necesarios. + +Las plantillas residen en la colección `_templates` como archivos +markdown. Esto permite que Jekyll los cargue como una colección a +través de esa feature ya implementada, reciclando código. + +Además, permite que las plantillas tengan, además de una estructura de +datos YAML por defecto, un cuerpo por defecto, si quisiéramos tener una +estructura del documento también. + +## Estructura del documento + +``` +--- +title: "" +categories: [] +tags: [] +related_articles: [] +destacado: false +resumen: "" +descripcion_detallada: "" +--- + +# Título de primer nivel + +Un resumen que quieras poner aquí. Esto irá en el editor de texto. + +``` + +Entonces, en un primer momento, el formulario se arma en base a los +tipos de datos que se espera en un campo. Si el valor es `""`, se +espera un campo de texto, si es `[]`, se espera un array y así. + +Pero: + +* Cómo distinguir entre un campo de texto largo y uno más corto? + +* El campo `related_articles` debería ser autocompletado a partir de los + títulos de otros artículos cargados, entonces cómo indicar esto? + +La conversión de cyber-women.com debería ser así: + +``` +--- +categories: [] +cover: "" +lang: + es: "" + en: "" + ar: "" +layout: "" +title: "" +objetivos: "" +tags: [] +permalink: "" +dir: "" +--- +``` + +Pero acá no se puede distinguir que en realidad en `cover` y en +`permalink` van paths, que los idiomas se autocompletan con titulos de +otra colección, que `tags` y `categories` se autocompletan con valores +que hay en otros artículos y que `dir` es uno de `ltr` o `rtl`. + +`dir` es fácil, se pone un array con los valores que van: + +``` +--- +categories: [] +cover: "" +lang: + es: "" + en: "" + ar: "" +layout: "" +title: "" +objetivos: "" +tags: [] +permalink: "" +dir: [ ltr, rtl ] +--- +``` + +La otra opción es hacer una lista de las propiedades que se +autocompletan, por ejemplo, los campos estándar: + +* `categories` +* `tags` +* `cover` +* `layout` +* `dir` + +Ya tienen programáticamente sus valores. Pero sería laburo doble porque +el editor de plantillas tiene que poder crear campos arbitrarios con +valores predeterminados. + +Aunque el editor de plantillas todavía no lo necesitamos hacer? + + +``` +--- +categories: [site/categories] +cover: string +lang: + es: en/title:en/slug + en: es/title:es/slug + ar: ar/title:ar/slug +layout: site/layouts +title: string +objetivos: text +tags: [site/tags] +permalink: string +dir: [ ltr, rtl ] +--- +``` + +Donde `site/categories` equivale a `@site.everything_of('categories')` y +`en/slug` a `@site.everything_of('slug', lang: 'en')`. + +Al separar con `:`, estamos diciendo qué valores mostrar y a cuáles +mapearlos, entonces `en/slug:en/title` muestra un selector de todos los +títulos, pero almacena el slug correspondiente. + +Para saber si un valor es un array, encontramos un array y miramos +dentro qué tipos de valores vamos a rellenar. + +luego, el editor de plantillas de posts permite crear estos tipos de +campos con un formulario dinamico + +Las plantillas tienen un layout correspondiente. Luego se puede sugerir +y que las usuarias lo cambian. + +No es necesario definir los campos estandar `categories`, `lang`, +`layout`, `title`, `tags`, `slug`, `permalink` y `dir`. + + +Finalmente, solo es necesario definir los campos extra: + +``` +--- +cover: string +objetivos: text +habilidades: 'posts/habilidades' +conocimientos: ['posts/conocimientos'] +sesiones_ejercicios_relacionados: ['posts/slug:posts/title'] +destacado: false +--- +``` + +Donde `string` y `text` indican valores de texto de distintos largos +(`text` y `textarea` en el formulario), `false` un valor binario (un +`checkbox`) y `coleccion/valor` y +`coleccion/valor:coleccion/valor_a_mostrar` en valores tomados de otras +colecciones. Cuando están entre `[]`, permite múltiples valores. + +Entonces, para resumir: + +* La plantilla se coloca en `_templates/nombre_de_la_plantilla.markdown` +* Es un documento Jekyll con _frontmatter_ y contenido +* El _frontmatter_ trae los campos extra a completar desde la carga de + artículos +* El `slug` de la plantilla se convierte en el `layout` sugerido del + post, es decir que debería existir un + `_layouts/nombre_de_la_plantilla.html` correspondiente. +* El `_config.yml` del sitio debe contener: + +```yaml +collections: + - templates +``` + + Para poder cargar la colección de plantillas. + + TODO: agregarlo especificamente en `app/models/site.rb` al cargar el + sitio.