Trabajando con datos, activos y plantillas en Middleman

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Este segundo tutorial sobre la creación de sitios web estáticos con Middleman profundiza un poco más en el marco. Al final, debe saber lo suficiente como para construir su propio proyecto desde cero. Cubriremos temas como archivos de datos, URL bonitas, plantillas de proyectos y la canalización de activos, ¡así que estancados!

Archivos de información

Por lo tanto, después de haber seguido el primer tutorial, ya habrá aprendido a jugar con los datos; Materia frontal almacenada en las secciones delimitadas por tres guiones de páginas individuales. También puede escribir archivos de datos separados en YAML o JSON y colocarlos en un directorio "/ data". Esto es útil si tiene sitios más complejos con datos que rara vez cambian, y donde no desea mantener esos datos directamente en su HTML.

Digamos que tienes los derechos para vender todas las películas de James Bond. Podríamos poner una lista de ellos en un archivo de datos e iterarlos en nuestra vista. Si necesitaríamos cambiar o actualizar esos datos cuando haya una nueva película disponible, solo tendría que aplicar ese cambio en su archivo de datos .yaml o .json. No recomendaría hacerlo para datos que sean complejos de alguna manera; es factible, pero se siente muy dudoso y equivocado.

Por ejemplo, aquí está el aspecto que podría tener un archivo /data/bond.yaml:

movies:
- title: "Dr. No"
  year:  "1962"
  text:  "John Strangways, the British Intelligence (SIS) Station Chief in Jamaica, is killed. In response, British agent James Bond—also known as 007—is sent to Jamaica to investigate the circumstances. During his investigation Bond meets Quarrel, a Cayman fisherman, who had been working with Strangways around the nearby islands to collect mineral samples. One of the islands was Crab Key, home to the reclusive Dr. No."
  image: "bond_movie_01.png"
- title: "From Russia with Love"
  year:  "1963"
  text:  "SPECTRE's expert planner Kronsteen devises a plot to steal a Lektor cryptographic device from the Soviets and sell it back to them while exacting revenge on Bond for killing their agent Dr. No; ex-SMERSH operative Rosa Klebb is in charge of the mission. She recruits Donald "Red" Grant as an assassin and Tatiana Romanova, a cipher clerk at the Soviet consulate in Istanbul, as the unwitting bait."
  image: "bond_movie_02.png"
- title: "Goldfinger"
  year:  "1964"
  text:  "Bond is ordered to observe bullion dealer Auric Goldfinger: he sees Goldfinger cheating at cards and stops him by distracting his employee, who is subsequently killed by Goldfinger's Korean manservant Oddjob. Bond is then instructed to investigate Goldfinger's gold smuggling and he follows the dealer to Switzerland. Bond is captured when he reconnoitres Goldfinger's plant and is drugged; he is taken to Goldfinger's Kentucky stud farm and is imprisoned. He escapes briefly to witness Goldfinger's meeting with U.S. mafiosi, who have brought the materials he needs for an operation to rob Fort Knox."
  image: "bond_movie_03.png"
...

Luego muestre como está en source/bond-movies.html.erb:

1	<h2>Bond movies</h2>
2	<ol>
3	<% data.bond.movies.each do \|movie\| %>
4	<li>
5	<%= image_tag movie.image %>
6	<h3><%= movie.title %></h3>
7	<h6><%= movie.year %></h6>
8	<p> <%= movie.text %></p>
9	</li>
10	<% end %>
11	</ol>

Una de las ventajas de estos archivos de datos es que son seguros. Aún mejor, su directorio /data con todos los datos YAML o JSON no se enviará a su servidor en linea. Durante la fase de compilación, sus datos se inyectan en sus plantillas localmente antes de que se implementen. Después de eso, los datos en tus vistas son simplemente HTML estático. ¡Genial!

Convenciones de nombres

Una palabra sobre convenciones de nombres aquí. Cuando tiene archivos de datos en un directorio de "datos", obtiene acceso a un objeto data. Middleman luego crea "objetos" para cada archivo .yml, .yaml o .json a los que puede acceder a través del objeto data iniciales encadenándolo. A continuación, tendrá acceso a los atributos que ha almacenado. En nuestro caso, tenemos un “objeto” movies YAML con los atributos title, year, text y image.

<%= data.data_file_name.yaml_or_json_object.attribute %>

<%= data.bond.movies.image %>
<%= data.bond.movies.title %>
<%= data.bond.movies.year %>
<%= data.bond.movies.text %>

Si tiene subdirectorios, solo tiene que pegarlos. Supongamos que tiene el archivo de datos de sus películas bond en un directorio spy_movies (por ejemplo: /data/spy_movies/bond.yaml) Ahora debería acceder a él de la siguiente manera:

1	<%= data.spy_movies.bond.movies.title %>

Por último, debo agregar que el almacenamiento en JSON podría ser preferible a algunas personas, pero todas las comas, corchetes y llaves en exceso me desaniman para ser honesto. No solo en los archivos de datos sino también en las secciones frontales. Depende de usted lo que más le convenga, por supuesto, vealo usted mismo:

some_file.yaml:

1	bond_girls:
2	- Strawberry Fields
3	- Jill Masterson
4	- Tiffany Case

some_file.json:

{
  "bond_girls": [
    "Strawberry Fields",
    "Jill Masterson",
    "Tiffany Case"
  ]
}

URL bonitas

Si tiene un archivo como source/bond-movies.html.erb, terminará como https://appname.com/bond-movies.html. Durante el proceso de compilación perdemos la extensión de archivo ".erb" y terminamos con la versión final ".html" de esa página, que se refleja en la URL. Eso está bien, cosas normales. Para URLs más sofisticadas como http://appname.com/bond-movies tenemos que trabajar un poco.

Debe activar la extensión Directory Indexes en su config.rb. Esto crea una carpeta para cada archivo .html. Durante middleman build, la página terminada termina como el archivo de índice de esa carpeta, lo que significa que, como archivo de índice, su extensión no tendrá que aparecer en la URL. Si prestó atención, es posible que ya haya visto esto en funcionamiento con el archivo index.html estándar que se crea para cada proyecto de Middleman como una página de destino. Enciende tu servidor y compruébalo por ti mismo.

En config.rb:

1	activate :directory_indexes

Veamos qué sucedió después de middleman build en tu archivo bond-movies.html.erb si has activado esa extensión. Middleman habrá creado una carpeta de "build/bond-movies" y su nombre de archivo original habrá sido cambiado a index.html (build/bond-movies/index.html).

Aquí está la salida de Shell:

1	create build/bond-movies/index.html

Sin embargo, hay una pequeña advertencia. Antes de activar URL bonitas, puede confiar en el uso de la ruta de los activos. Ahora, con los índices de directorio en su lugar, debe suministrar activos con su ruta completa y absoluta. Por lo tanto, llamar a una imagen solo por su nombre, por ejemplo, ya no funcionara.

Si, por algún motivo, desea anular el comportamiento de esa extensión para un archivo en particular, puede hacerlo.

En config.rb:

1	page "/bond-movies.html", :directory_index => false

Aquí está la salida de Shell si la cambia de nuevo para bond-movies.html.erb:

1	create build/bond-movies.html
2	remove build/bond-movies/index.html
3	remove build/bond-movies

Ahora su URL vuelve a la normalidad para ese archivo de nuevo. (http://appname.com/bond-movies.html)

Además, puede optar por excluirse del esquema de denominación de índice del directorio localmente en el frente de su página individual:

---
directory_index: false
---

<h1>Bond movies</h1>
...

Si quieres construir esa estructura con carpetas y sus respectivos archivos de índice, Middleman no te va a molestar. Funciona de la misma manera y los intermediarios los ignoran si se mezclan y combinan ese enfoque.

Pipleline del activo

Me gustaría ir al grano con este y solo mostrarte las piezas que creo que son realmente relevantes.

El "pipleline de activos" es la jerga de Rails importada a Middleman. Bajo el capó, una gema llamada Sprockets hace todo el trabajo pesado. Le ayuda a manejar la administración de dependencias, combinando y minimizando los activos, lo que ayuda a reducir significativamente sus activos. También se encuentran a su disposición algunos métodos de ayuda para hacer referencia de manera concisa a los activos. Más allá de eso, también se le proporcionan los medios para escribir código Sass y CoffeeScript, de manera inmediata.

Concatenación

La concatenación es una de las características más importantes de la línea de activos. En lugar de tener muchas solicitudes HTML separadas para cada archivo CSS y JS, puede reducirlas drásticamente concatenándolas en uno o en un puñado de archivos. Cuantas menos solicitudes hagas, más rápido se cargará tu aplicación.

Concatenacion de JavaScript

De forma predeterminada, Sprockets presionará todos los archivos JavaScript en un solo archivo .js. Después de middleman build, este archivo se encontrará en /build/javascripts/all.js. Lo mismo ocurre con tu CSS. Después del proceso de compilación, tendrá todos los archivos Sass concatenados juntos en la build/stylesheets/all.css.

Combina sus recursos de JavaScript utilizando parciales (cuyos nombres de archivo comienzan con un guión bajo) y luego require en la parte superior de su archivo source/javascripts/all.js. Los archivos con una extensión .coffee agregada funcionan exactamente igual. La orden sí importa para este proceso.

Aquí, por ejemplo, está la parte superior de source/javascript/all.js:

1	//= require "_jquery"
2	//= require "_lib_code"
3	//= require "_animations"

Cuando eche un vistazo a su nuevo directorio /build, solo encontrará un archivo .js en /javascripts.

Concatenación de CSS

Para su código Sass, la historia es básicamente la misma, pero debe usar la importación de Sass para @import sus parciales, en lugar de require de Sprockets. Nuevamente, coloque los archivos "requeridos" en la parte superior, esta vez prestando atención al pedido. A diferencia de requerir los parciales de JavaScript, deja fuera el guión bajo cuando importa parciales de Sass. Por ejemplo

1	@import 'normalize';
2	@import 'header';
3	@import 'navigation';
4	@import 'footer';

Compresión (minificación)

Otra característica interesante de las ruedas dentadas es la compresión, también llamada minificación. Este proceso reduce mucho la grasa, como deshacerse de espacios en blanco y comentarios innecesarios. La gente también llama a este proceso uglifying (y, por supuesto, hay una gema llamada uglifier que hace un hermoso trabajo). En comparación con la minificación de activos de JavaScript, la uglificación de CSS no es tan complicada.

Para comenzar, deberá agregar lo siguiente a su archivo config.rb:

1	configure :build do
2	activate :minify_css
3	activate :minify_javascript
4	end

En realidad, solo necesitas descomentar estas líneas debajo de tu :build block. La próxima vez que use middleman build, compile los recursos en su carpeta / build, todo estará uglificado y delgado. A continuación se muestran dos pequeños ejemplos de cómo este código termina apareciendo:

CSS reducido en /build/stylesheets/all.css:

1	body{background-color:#d0e4fe}h1{color:orange;text-align:center}p{font-family:"Times New Roman";font-size:20px}

JS reducido en /build/javascripts/all.js:

switch((new Date).getDay()){case 0:day="Sunday";break;case 1:day="Monday";break;case 2:day="Tuesday";break;case 3:day="Wednesday";break;case 4:day="Thursday";break;case 5:day="Friday";break;case 6:day="Saturday"}

Sin el pipeline de activos, tendría que configurar su propio objeto para escribir su JavaScript y CSS a través de lenguajes de nivel superior como CoffeeScript y Sass.

Ayudantes de tubería de activos

Para tus archivos Sass tienes cuatro ayudantes a tu disposición:

image_path()
font_path()
image_url()
font_url()

Como ha seguido las convenciones hasta el momento, puede usar estos ayudantes para anteponer la ruta de directorio correcta a sus activos.

En un archivo Sass, por ejemplo:

image_path('logo.png')
# => images/logo.png

image_path('nested_folder/some.png')
# => images/nested_folder/some.png

Ruta de importación

La canalización de activos utiliza rutas de importación a través de Sprockets para sus activos. Por defecto :js_dir y :css_dir ya están agregados a esa ruta. Eso significa que los archivos colocados en /source/javascripts y /source/stylesheets están disponibles e importados automáticamente. Por otro lado, si tiene recursos que desea conservar en otros directorios, también puede agregarlos a la ruta de importación editando config.rb:

1	sprockets.append_path '/some/other/assets_folder/'

En este ejemplo, otros activos en source/some/other/assets_folder/other.css también están a disposición de Middleman a través de esta ruta. Lo mismo ocurre con los archivos .js también.

Plantillas de proyectos

Middleman viene con un par de plantillas de proyectos útiles que al menos debes conocer. Estas plantillas le brindan un buen punto de partida cuando inicia una nueva aplicación Middleman. También puede agregar estas plantillas en cualquier momento más tarde:

Plantilla SMACSS
Plantilla Base de móviles
Plantilla Base HTML5
Plantilla Blog (necesita gema extra)

Puedes usarlos así, a través de la línea de comando:

1	middleman init your_fancy_app --template=smacss

La plantilla le proporcionará todos los archivos y carpetas que necesita. Si ya tiene una aplicación y desea agregar una plantilla, use el mismo comando sin mencionar el nombre de la aplicación. Lo mismo:

1	middleman init --template=smacss

Ahora viene mi parte favorita de Middleman. Es muy sencillo crear sus propias plantillas y reutilizarlas cuando lo desee. Comience por crear una carpeta ~/.middleman en su directorio raíz (no olvide el punto delante del nombre). Dentro de ese directorio creas nuevas carpetas para tus plantillas. Por ejemplo, /.middleman/podcast sería una plantilla podcast. Luego llene este directorio de podcasts con todos los archivos y carpetas que necesita. Por ejemplo, si desea tener disponibles hojas de estilo adicionales para su aplicación Middleman, entonces necesita simular la ruta de archivo de Middleman para que sea muy fácil de usar.

En la captura de pantalla a continuación, preparé un ejemplo ficticio que contiene un par de archivos que podría necesitar para cada proyecto ubicado en una carpeta "bourbon". Ahora tengo una plantilla de bourbon.

Desde que simulé la estructura de archivos de Middleman, estas hojas de estilo se mostrarán exactamente donde las necesito después de que inicie esa plantilla. Mis archivos ahora están en /source/stylesheets y también están listos para ser importados en mi /source/stylesheets/all.css.scss.

Como ya hice los parciales de mis estilos de plantilla, es como siempre. Aquí está mi source/stylesheets/all.css.scss:

1	@import 'bourbon_mixins/mixins';
2	@import 'bourbon_neat/grids';
3	@import 'bourbon_refills/cards';
4	...

¡Terminado! Sin embargo, debe tener cuidado con una cosa: cuando usamos middleman build para crear nuestro nuevo directorio build, all.css absorberá estos archivos y ninguna de las carpetas de plantillas bourbon aparecerá allí. Sin embargo, si olvida tener un guión bajo en sus nombres de archivo para estos estilos, la carpeta completa se transferirá a /build, junto con los respectivos archivos .css. Las declaraciones de @import en all.css.scss tampoco harán una diferencia en ese caso.

Comprobación de plantillas

Si tiene un montón de plantillas y solo quiere buscar un nombre en la lista, puede usar el siguiente comando:

1	middleman init --help
2
3	# => # Use a project template: default, html5, mobile, smacss, bourbon

En caso de que quiera reinventar la rueda, eche un vistazo a estas plantillas de código abierto. Si nunca has jugado mucho con las plantillas, te recomiendo que inicies una aplicación ficticia y las pruebes. Vea qué archivos se crean o se sobrescriben. Juegue un poco. Luego, cree una carpeta ficticia con un par de archivos Sass para una plantilla en ~/.middleman y vea qué sucede cuando inicia esa plantilla. ¡Nada mejor que aprender haciendo estos pequeños experimentos en el camino!

Pensamientos finales

Creo que ahora estás más que listo para comenzar a construir una pequeña aplicación con Middleman. Te quedan algunas cosas por aprender por tu cuenta, pero te he presentado las piezas más importantes del rompecabezas.

Middleman es muy divertido y una buena opción en cuanto a tecnología. Es potente, fácil de usar y tiene una API sencilla y amigable para los principiantes; eso es todo lo que importa por ahora. ¡Que te diviertas!