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 archivos aparte, como veremos ahora.

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?