Drupal 8

Esta página recoge los contenidos del taller de Drupal 8 que se hizo en el hacklab de Calafou. La intención es que quede como documentación que nos permita encarar mejor el proceso de desarrollo de la web nueva de Calafou.

Instalación y configuración del server

Requerimientos de PHP

Lo primero es comprobar que cumplimos los requerimientos de PHP en el servidor. Drupal 8 es un software reciente y necesita una versión de PHP actual que soporte las nuevas características del lenguaje.

Ver: https://www.drupal.org/requirements/php#8

Drush

Lo segundo a hacer es instalar drush. Drush es una especie de navaja suiza, un asistente para drupal 8 que permite hacer una cantidad importante de operaciones de mantenimiento y configuración desde línea de comando. Una vez empiezas a usarlo no hay marcha atrás:

#http://docs.drush.org/en/master/install/
wget http://files.drush.org/drush.phar
php drush.phar core-status
chmod +x drush.phar
sudo mv drush.phar /usr/local/bin/drush
drush init

Descargar drupal 8

Usamos drush para ello. 'dl' es el comando de drush que sirve para descargar el core y módulos de drupal. Las buenas prácticas aconsejan que la raíz del proyecto no sea la raíz de la web. Sino que ésta última sea una subcarpeta llamada public_html. De esta manera tenemos la web y una carpeta raíz inaccesible desde fuera, donde podemos guardar backups, archivos temporales, archivos de configuración, etc. Nos vamos a /var/www, creamos una carpeta para nuestro proyecto (por ejemplo d8 y descargamos el core dentro):

mkdir d8 && cd d8
drush dl drupal-8

Renombramos la carpeta que hemos descargado a public_html y ya tenemos el esqueleto de la web.

Configuración previa a la instalación y política de permisos

Previo a ejecutar el script de instalación hemos de hacer unos pasos previos: 0- Ajustamos permisos para que el drupal sea seguro. Para ello tenemos que poner como propietario de todos los archivos a nuestro user y como grupo a www-data (apache). Una vez hecho eso quitamos permisos de escritura a apache sobre todos los archivos:

sudo chown mi-usuario:www-data /var/www/d8/public_html -R
sudo chmod g-w /var/www/d8/public_html -R

Nos vamos a sites/default y copiamos el archivo default.settings.php a settings.php. En la misma carpeta creamos la carpeta files y añadimos permisos de escritura sobre files y settings a apache. Si vamos a hacer la instalación en un idioma distinto al inglés, creamos también la carpeta translations dentro de files:

cd /var/www/d8/public_html/sites/default/
cp default.settings.php settings.php
mkdir files
mkdir files/translations
sudo chown mi-usuario:www-data -R files settings.php
sudo chmod g+w -R files settings.php

Configurar el virtual host

Lo primero es añadir un nombre de dominio para trabajar cómodamente:

#vi, gedit, sublime, nano, atom, brackets... lo que sea
#Añadimos esta línea: 127.0.0.1 d8.local 
sudo vi /etc/hosts 

Y ahora tenemos que añadir la configuración del virtual host a apache: Nos vamos a /etc/apache2/sites-available y copiamos el archivo que viene de ejemplo:

cd /etc/apache2/sites-available
sudo cp 000-default.conf d8.local.conf  #no es mala idea poner la ruta como nombre para evitar equívocos

Una vez allí configuramos para que la ruta d8.local apunte a la carpeta que hemos creado y ponemos un nombre correcto a los logs de apache (en /var/log/apache2):

sudo vi d8.local.conf

Editamos el archivo y ponemos esto:

<VirtualHost *:80>
  ServerName d8.local
  DocumentRoot /var/www/d8/public_html
  ErrorLog ${APACHE_LOG_DIR}/d8.error.log
  CustomLog ${APACHE_LOG_DIR}/d8.access.log combined
</VirtualHost>

Configurar htaccess

.htaccess es un archivo que permite la sobreescritura local de las configuraciones de apache. Tenemos dos opciones:

1. Dejamos el archivo que viene con drupal y damos permiso desde el archivo de configuración anterior para que este pueda sobreescribirlo.
2. Incluimos todos los contenidos del archivo anterior en la conf y borramos el .htaccess.

La aconsejable es la segunda porque quitamos un poquito de sobrecarga al servidor, pero los dos enfoques son idénticos en la pŕactica:

sudo vi /etc/apache2/sites-available/d8.local.conf

Opción 1:

<VirtualHost *:80>
  ServerName d8.local
  DocumentRoot /var/www/d8/public_html
   
  #Añadimos esto:
  <Directory /var/www/d8/public_html>
    order allow, deny
    AllowOverride all
  </Directory>
  ErrorLog ${APACHE_LOG_DIR}/d8.error.log
  CustomLog ${APACHE_LOG_DIR}/d8.access.log combined
</VirtualHost>

Opción 2:

<VirtualHost *:80>
   ServerName d8.local
   DocumentRoot /var/www/d8/public_html

   #Añadimos esto:
   <Directory /var/www/d8/public_html>
     # Contenidos del archivo .htaccess
   </Directory>
   ErrorLog ${APACHE_LOG_DIR}/d8.error.log
   CustomLog ${APACHE_LOG_DIR}/d8.access.log combined
</VirtualHost>

Una vez hecho todo, activamos la configuración y reiniciamos apache.

sudo a2ensite d8.local
sudo service apache2 reload

MySQL

El último paso es crear una base de datos y un usuario para que el drupal pueda escribir y leer en ella. Ambas cosas nos serán requeridas en el proceso de instalación. Necesitaremos una contraseña para la base de datos, en este caso pondré como ejemplo mypassword:

sudo mysql
#Una vez en el mysql
create database d8_local;
grant all on d8_local.* to 'd8'@'localhost' identified by 'mypassword';
exit

Instalar

Ya sólo queda seguir el proceso de instalación dando a drupal los datos que nos pide:

firefox d8.local

Nos pedirá que elijamos un perfil de instalación. Nota: Si elegimos el perfil mínimo hay que recordar de ajustar la ruta de la home en la sección de configuración porque si no tendrá un comportamiento bastante inexplicable.

Instalación de un tema

Una de las dificultades de drupal 8 es que no hay muchos temas desarrollados todavía. Ha cambiado todo sustancialmente desde la versión anterior. Los dos cambios principales son:

• Aparecen archivos de configuración en YML (un tipo de documento que anida mediante tabulados)
• Se cambia el sistema de plantillas de PHPTemplate a Twig. Twig es un motor de php que viene de Symphony.

Así que casi lo mejor es crear un tema de cero: no es complicado y el sistema nuevo es muy flexible, con lo que podemos crear un tema 'blanco' con SASS y Bootstrap con poco esfuerzo, creando una base limpia y sencilla desde la que empezar a trabajar.

Crear el tema. Primeros pasos

Para crear el tema nos vamos a la carpeta de la raíz 'themes'. Aquí tenemos que poner la carpeta que contenga nuestro tema. Tenemos dos opciones, en ambas drupal sabrá localizar el tema y leerlo. La primera es ponerla en 'themes' directamente. La segunda y recomendada, tanto para módulos como temas, es separar el código propio del ajeno. Para ello creamos dos carpetas, una 'contrib' y otra 'custom'. En la primera pondremos temas y módulos que descarguemos de la web de drupal. En la segunda nuestros propios módulos y temas. Ponemos como ejemplo de nombre a nuestro tema 'calafou'. Por último creamos el único archivo estrictamente necesario en el tema 'calafou.info.yml'. El nombre ha de ser el mismo (calafou).

cd themes
mkdir custom
mkdir contrib
mkdir contrib/calafou
cd contrib/calafou
vi calafou.info.yml

El archivo info

La estructura básica sería, por ejemplo:

name: 'Tema de Calafou'
type: theme
description: "Tema de Calafou. Lorem ipsum."
libraries:
  - calafou/styling
  # ...
regions:
  messages: 'Messages'
  header: 'Header'
  preface: 'Preface'
  content: 'Main content'
  # ...
  footer: 'Footer'
features:
  - favicon
  - logo
  # ...
version: 8.0.x
core: 8.x 

No es complicado. Primero vemos como funciona un yml. Es una estructura anidada de datos, con elementos que contienen a otros elementos. La relación madre-hijo o entre hermanas se da por indentado. Creo que no es necesario que el indentado sea coherente en todo el documento (dos espacios por ejemplo), sino que sólo tiene que serlo en todo el elemento madre. Aún así no es mala idea que sea coherente porque ayuda a leer. Las listas se crean con guiones.

Especificamos un nombre, una descripción, indicamos que es un módulo de tipo 'theme' y especificamos las regiones que vamos a usar, las librerías de javascript o css que vamos a necesitar y algunos aspectos más. Las regiones son contenedores abstractos de bloques. Es decir aquí sólo especificamos un nombre de manera que en la interfaz de bloques de drupal podemos asociar bloques de contenido (por ejemplo una caja de login o un texto informativo o una vista de nodos) con dichos nombres. Posteriormente en los archivos de plantilla decimos qué regiones se renderizan y con la css le damos el aspecto, forma y posición final. Las librerías en este archivo (css y js), funcionan de manera similar, como simples etiquetas, de manera que se concretan en otro archivo de configuración llamado 'calafou.libraries.info' (que veremos ahora). Como vemos es importante prefijar todos estos archivos con el nombre de máquina del tema (el de la carpeta, no el que ponemos en el archivo info y que sólo se ve --como la descripción-- en la interfaz gráfica administrativa de drupal.

Es importante empezar a pensar qué regiones y librerías necesitamos. ¿Necesitaremos leaflet, angular, bootstrap, masonry...? ¿Cómo es la maqueta? ¿Cuántas regiones necesitamos para definirla?

El archivo libraries

En el archivo libraries (calafou.libraries.yml) digamos que se especifican todas las librerías disponibles por el tema, de manera que en el archivo info simplemente se especifican cuáles están activas de todas éstas. Ahora mismo sólo tenemos activada en el archivo info la librería 'calafou/libraries' que sería la única casi obligatoria que enumera los archivos css que vamos a emplear. Así que creamos el archivo 'calafou.libraries.yml' y ponemos lo siguiente:

styling:
  version: 1.0
  css:
    theme:
      css/global.css: {}

Vemos que el nombre no necesita contener al tema (antes calafou/libraries, aquí calafou), porque drupal prefija los nombres de las librerías de los módulos con sus propios nombres. Tan sólo definimos un archivo CSS, 'global.css' porque vamos a usar un enfoque basado en SASS (ahora vamos a eso) y vamos a usar un único punto de compilación, 'global.sass' que se encargara tan sólo de importar todas las subhojas y parciales que necesitemos.

Configurar SASS

Partimos de la base que hemos instalado SASS y Compass en el server. Ésto excede a esta documentación y requeriría otro documento aparte. Resumiendo, son gemas de ruby, por lo que hay que instalar primero ruby en el server (normalmente vendrá de fábrca si es una distribución basada en debian), ruby-dev (para la compilación de código nativo) y las gemas sass, compass y sass-globbing que a su vez instalarán otras. Una vez con todo instalado creamos un proyecto de compass en la carpeta 'calafou':

compass create --bare --syntax sass --css-folder css --sass-folder sass 

Si todo va bien ésto no es creará dos carpetas, 'css' y 'sass' y un archivo de configuración en ruby 'config.rb'. Éste archivo es donde podemos cambiar la configuración. Todos los archivos que estén la carpeta sass serán compilados a css cada vez que hagamos un 'compass build' o un 'compass watch'. Como única cosa añadimos al config.rb la dependencia 'sass-globbing' para que podamos usar esta característica en nuestro tema. Ésta permite usar wildcards para importar parciales, lo que nos ahorra bastante trabajo (lo vemos más adelante). Editamos config.rb y añadimos arriba la línea 'require sass-globbing' de manera que quedará así:

require 'compass/import-once/activate'
require 'sass-globbing'
# Require any additional compass plugins here.
# Set this to the root of your project when deployed:
http_path = "/" 
css_dir = "css"
sass_dir = "sass"
images_dir = "images"
javascripts_dir = "javascripts"
# You can select your preferred output style here (can be overridden via the command line):
# output_style = :expanded or :nested or :compact or :compressed
# To enable relative paths to assets via compass helper functions. Uncomment:
# relative_assets = true
# To disable debugging comments that display the original location of your selectors. Uncomment:
# line_comments = false
preferred_syntax = :sass

Para estructurar la css vamos a usar un enfoque derivado SMACSS (de J. Snook). Este enfoque separa las hojas de estilo atendiendo a una estructura lógica. En una carpeta tenemos variables, en otra una base del tema y en la otra 'componentes'. Y las cargamos en ese orden en un punto de compilación global, global.sass, que es la única hoja que se compilará a css. La ventaja de este sistema es que encapsulamos el estilo en elementos pequeños y fáciles de mantener y que se sobreescriben en un orden lógico. Primero variables, luego la base y luego los componentes finales, elementos que tienen la mayor flexibilidad ya que sobreescriben de manera natural a los anteriores:

cd sass
mkdir variables base components
vi global.sass

Y en global.sass:

@import compass/css3
@import sass-globbing
@import variables/*
@import base/*
@import components/*

Pues listo, ya tenemos la base. Es cuestión de añadir parciales a cada carpeta. Si por ejemplo queremos dar estilo a un bloque de login de drupal podemos crear el archivo _block-login.sass en la carpeta components y dentro poner el estilo a nuestro gusto. El archivo global.sass reconocerá que hemos añadido un archivo --gracias a sass-globbing y al *-- y lo importará y se compilará finalmente dentro de global.css. Para activar compass y que nos mire los cambios yo suelo usar screen para que no me bloquee la consola. Le añadimos un parámetro -S para darle un nombre por si tenemos más procesos corriendo en segundo plano en screen saber reconocerlo a la primera:

screen -S calafou-sass compass watch

Hacemos Control+D y volvemos a la terminal original y podemos seguir trabajando tranquilamente con compass compilando en segundo plano cualquier cambio sobre el estilo. Screen seguirá funcionando aunque nos vayamos del servidor, lo cual puede ser cómodo aunque hay que controlarlo. Es un consumo de recursos. Si queremos quitar el proceso podemos comprobar las screens abiertas con sus nombres haciendo un:

screen -ls

Nos saldrá algo parecido a:

There is a screen on:
15581.calafou-sass	(02/03/16 22:26:44)	(Detached)
1 Socket in...

'Reatachamos' la screen llamándola por su nombre de sesión:

screen -r calafou-sass

Y cerramos haciendo Ctrl+C.

Por último, si hemos instalado el perfil normal, el drupal vendrá configurado para agregar y comprimir los archivos 'css'. Ésto es muy conveniente en producción pero en desarrollo evitará que veamos los cambios en la css hasta que limpiemos la caché y se reconstruyan los estilos del drupal. Para desactivarlo usamos drush:

drush config-edit system.performance

y ponemos la propiedad 'preprocess' de 'css' en 'false'. Si queremos podemos hacerlo por interfaz gráfica en '/admin/config/development/performance' desactivando el checkbox donde pone 'Combinar archivos CSS'.

El sistema de plantillas

Éste es uno de los cambios más destacados de drupal 8. Pasamos de PHPTemplate a Twig. Twig es un sistema de plantillas con una sintaxis idéntica a la de Django. Tiene la ventaja de seguridad de que no permite llamar a código PHP arbitrariamente desde la plantilla, sino tan sólo a determinadas funciones, fundamentalmente a través del sistema de filtros. Lo mejor a la hora de crear plantillas es no comenzar de cero, sino copiarlas de otro tema, por ejemplo 'classy', que es uno de los temas base que viene en el core. La estructura de nombres se mantiene aunque se sufija con 'html.twig'. Por ejemplo el archivo 'page.html.twig' define la maquetación de la página por defecto. 'front.html.twig' define la home y sobreescribe a la anterior, etc. 'node.html.twig' definiría cómo se ve un nodo de drupal por defecto y 'node--article.html.twig' definiría la maquetación de un nodo de tipo 'article' y sobreescribiría a la anterior, etc.Estos archivos han de estar en una carpeta llamada 'templates'.

Modo debug

Las plantillas se agarran a la caché que da gusto obligando a reconstruirla con un:

drush cr

cada vez que hacemos cambios, lo que es un auténtico tedio en desarrollo porque enlentece mucho el proceso. Podemos activar el modo 'debug' del drupal lo que agilizará mucho el desarrollo de plantillas, lo único que hay que recordar es desactivar esta configuración en producción, porque mete sobrecarga y es más insegura. Para ello tenemos que copiar el archivo de configuración por defecto y editarlo para activar el modo debug de las plantillas twig:

cd /var/www/d8/public_html/sites/default
cp default.services.yml services.yml
vi services.yml

Buscamos la línea twig.config (línea 39) y ponemos a sus propiedades 'debug' y 'auto_reload' el valor 'true' y a 'cache' el valor 'false' y limpiamos la caché de drupal:

drush cr

Twig

Por ejemplo podemos copiar de classy 'page.html.twig':

mkdir templates
cd /var/www/d8/public_html/
cp core/themes/classy/templates/layout/page.html.twig themes/custom/calafou/templates

Y editarlo para ver cómo funciona:

 <header role="banner">
   \{\{ page.header \}\}
 </header>
 Template:Page.primary menu
 Template:Page.secondary menu
 Template:Page.breadcrumb
 Template:Page.highlighted
 Template:Page.help
 <main role="main">
   <a id="main-content" tabindex="-1"></a>{# link is in html.html.twig #}

     Template:Page.content

{# /.layout-content #}

   {% if page.sidebar_first %}
     <aside class="layout-sidebar-first" role="complementary">
       Template:Page.sidebar first
     </aside>
   {% endif %}
   {% if page.sidebar_second %}
     <aside class="layout-sidebar-second" role="complementary">
       Template:Page.sidebar second
     </aside>
   {% endif %}
 </main>
 {% if page.footer %}
   <footer role="contentinfo">
     Template:Page.footer
   </footer>
 {% endif %}

{# /.layout-container #}