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:
- Dejamos el archivo que viene con drupal y damos permiso desde el archivo de configuración anterior para que este pueda sobreescribirlo.
- 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 que 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 haciendo:
screen -r calafou-sass
Y cerramos haciendo Ctrl+C.
