Maquetación Ágil con Ruby: nanoc y heel: como funciona nanoc

5. Cómo funciona nanoc

Cuando creas un sitio usando

$ nanoc create_site nombre_del_proyecto

nanoc crea una serie de carpetas:

nombre_del_proyecto
- assets (imágenes, css, javascripts, etc...)
- content (donde guardaremos el contenido de cada página)
- layouts (aquí estarán los distintos layouts de nuestro site)
- lib (aquí guardaremos los plugins y extensiones que creemos)
- output (directorio de salida donde se generará nuestro HTML)
- tasks (para guardar tareas de Rake)
- templates (plantillas para el contenido del site)

La idea fundamental de nanoc es separar el diseño del contenido.

Cuando compilas el site, nanoc incrusta el contenido de cada página en su layout correspondiente, genera el HTML y lo copia a la carpeta de salida (por defecto es 'output')

Vamos a verlo con un ejemplo.

Nuestra primera página

Vamos a empezar creando un proyecto nanoc de pruebas:

$ nanoc create_site nanoc_ejemplo
    create  nanoc_ejemplo
    create  nanoc_ejemplo/assets
    create  nanoc_ejemplo/output
    create  nanoc_ejemplo/config.yaml
    create  nanoc_ejemplo/meta.yaml
    create  nanoc_ejemplo/Rakefile
    create  nanoc_ejemplo/layouts
    create  nanoc_ejemplo/layouts/default.erb
    create  nanoc_ejemplo/lib
    create  nanoc_ejemplo/lib/default.rb
    create  nanoc_ejemplo/tasks
    create  nanoc_ejemplo/tasks/default.rake
    create  nanoc_ejemplo/templates
    create  nanoc_ejemplo/templates/default
    create  nanoc_ejemplo/templates/default/default.txt
    create  nanoc_ejemplo/templates/default/meta.yaml
    create  nanoc_ejemplo/content
    create  nanoc_ejemplo/content/content.txt
    create  nanoc_ejemplo/content/meta.yaml
$ cd nanoc_ejemplo
$

Ya tenemos listo el esqueleto de nuestro primer site con nanoc. Podemos compilar el contenido por defecto usando

$ nanoc compile
    create  output/index.html
$

Para ver qué ha generado nanoc, podemos arrancar heel en el directorio 'output'

$ cd output
$ heel
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
** heel running at http://127.0.0.1:4331
** Use Ctrl-C to stop.
** Launching your browser...

y se abrirá nuestro navegador por defecto, mostrándonos nuestra glamourosa página por defecto.

Muy interesante... ¿cómo cambio el contenido de la página?

Si abres el directorio nanoc_ejemplo/content verás un fichero content.txt y un fichero meta.yaml

Estos dos ficheros definen el contenido (content.txt) y los metadatos de una página (meta.yaml).

Edita el contenido de content.txt y escribe lo siguiente:

Este es mi nuevo contenido :)

Repetimos la operación anterior para visualizar los cambios:

$ nanoc compile
$ cd output
$ heel

Muy bien... ya sabemos cómo cambiar el contenido de la página de inicio...

¿Y de dónde sale el resto del código?

Si has mirado el fuente de la página de inicio, habrá visto algo como esto:

<html>
  <head>
    <title>My New Homepage</title>
  </head>
  <body>
Este es mi nuevo contenido :)
  </body>
</html>

¿De dónde sale el resto del HTML?

Si miras en nanoc_ejemplo/layouts, encontrarás un fichero default.erb que contiene este código:

<html>
  <head>
    <title><%= @page.title %></title>
  </head>
  <body>
<%= @page.content %>
  </body>
</html>

Los bloques de <%= ... %> son marcas de ERB que sirven para incrustar el contenido de la página en la plantilla. @page.title y @page.content son dos variables de Ruby que contienen los datos de la página. Al compilar la plantilla, nanoc reemplaza las variables por el contenido de cada página.

¡Pero yo no he puesto ningún título de página!

Efectivamente... si abres el fichero nanoc_ejemplo/content/meta.yaml verás lo siguiente:

# Built-in

# Custom
title: My New Homepage

Prueba a cambiar el campo title, recompila y previsualiza...

¿Y qué metadatos puedo usar en la página?

Por defecto, nanoc "entiende" los siguientes campos en una página:

custom_path: Ruta que tendrá el fichero una vez se compile, añadiéndole un / al inicio. Por ejemplo, la página feed.xml puede tener como ruta /feed.xml
extension: La extensión del fichero compilado. Muy útil para crear ficheros .css, .js o .xml
haml_options: Opciones para el filtro Haml, si lo usas.
filename: Nombre del fichero una vez compilado. Por defecto es index
filters: Una lista de filtros que quieras aplicar al contenido. Por defecto no se usa ninguno (texto plano)
is_draft: Si es "true", la página no se compilará. Muy útil para no enviarle páginas a medio terminar a tu cliente :)
layout: Nombre del layout que usaremos para esta página. Te vendrá de maravilla para los sitios que tienen varios diseños dependiendo de la sección.
skip_output: Determina si quieres exportar esta página. Por defecto es "true".

Además de los campos por defecto, puedes usar cualquier atributo que se te ocurra. Por ejemplo, el campo title no está en la lista de los atributos que entiende nanoc :)

Para usar un atributo propio, usa <%= @page.nombre_de_atributo %>.

Por ejemplo, si quisieras usar un atributo "sección", pondrías en meta.yaml

seccion: "Sobre Nosotros"

y estaría disponible en tus plantillas como

<%= @page.seccion %>

Sigamos

Paso siguiente, tuneando nanoc

changed September 24, 2007