4.3. Las hojas de estilo, imágenes y archivos JavaScript (El tutorial Jobeet)

Como este tutorial no trata sobre el diseño web, hemos preparado todos los archivos que utilizan las páginas de Jobeet: descarga el archivo ZIP con todas las imágenes y descomprímelo en el directorio web/images/, descarga el archivo ZIP con todas las hojas de estilos CSS y descomprímelo en el directorio web/css/.

Nota En el layout también hemos incluido un favicon. Si quieres, puedes descargar el favicon de Jobeet y guardarlo en el directorio web/.

Figura 4.4 El módulo job con el layout y las imágenes y hojas de estilos

Nota La tarea generate:project crea por defecto tres directorios para guardar los archivos relacionados con la web: web/images/ para las imágenes, web/css/ para las hojas de estilos y web/js/ para los archivos de JavaScript. Se trata de otra de las convenciones que sigue Symfony, pero si lo deseas, puedes guardar tus archivos en cualquier otro directorio dentro del directorio web/.

Si has investigado el código HTML de las páginas del módulo job, habrás visto que aunque el archivo main.css no se incluye en el layout, está presente en todas las páginas. ¿Cómo es posible que se incluya un archivo CSS que no se encuentra en el layout?

La respuesta es que la hoja de estilos se ha incluido mediante la llamada a la función include_stylesheets() que se realiza dentro de la sección <head> del layout. La función include_stylesheets() se conoce con el nombre de helper. Un helper es una función de Symfony a la que se le pueden pasar parámetros y que devuelve código HTML. Los helpers se utilizan casi siempre para mejorar la productividad en el desarrollo, ya que suelen generar fragmentos de código que se utilizan habitualmente en las plantillas. El helper include_stylesheets() genera las etiquetas <link> necesarias para enlazar las hojas de estilo. Pero, ¿cómo sabe el helper los archivos CSS que tiene que incluir?

La capa de la vista se puede configurar mediante el archivo de configuración view.yml de la aplicación. A continuación se muestra el archivo que genera por defecto la tarea generate:app:

# apps/frontend/config/view.yml
default:
  http_metas:
    content-type:  text/html

  metas:
    #title:        symfony project
    #description:  symfony project
    #keywords:     symfony, project
    #language:     en
    #robots:       index, follow

  stylesheets:    [main.css]

  javascripts:    []

  has_layout:     on
  layout:         layout

El archivo view.yml se emplea para configurar las opciones por defecto (default) de todas las plantillas de la aplicación. La opción stylesheets por ejemplo define un array que contiene el nombre de las hojas de estilo que se incluyen en cada página de la aplicación (esta información es la que utiliza el helper include_stylesheets() para incluir los archivos CSS en las páginas).

Nota En el archivo view.yml por defecto, la referencia de la hoja de estilos es main.css y no /css/main.css. En realidad, las dos referencias anteriores son equivalentes, ya que Symfony añade automáticamente el prefijo /css a las rutas relativas.

Si se indican varios archivos, Symfony los incluye en el mismo orden en el que se han indicado:

stylesheets:    [main.css, jobs.css, job.css]

También es posible añadir el atributo media para cada archivo y también se puede omitir el sufijo .css:

stylesheets:    [main.css, jobs.css, job.css, print: { media: print }]

La configuración anterior se convierte en el siguiente código HTML:

<link rel="stylesheet" type="text/css" media="screen" href="/css/main.css" />
<link rel="stylesheet" type="text/css" media="screen" href="/css/jobs.css" />
<link rel="stylesheet" type="text/css" media="screen" href="/css/job.css" />
<link rel="stylesheet" type="text/css" media="print" href="/css/print.css" />

Nota El archivo de configuración view.yml también establece el layout por defecto que utilizan las páginas de la aplicación. Inicialmente su nombre es layout, por lo que Symfony decora todas las páginas con el archivo layout.php. También es posible deshabilitar la decoración de las páginas indicando un valor false en la opción has_layout.

Aunque la configuración actual funciona correctamente, el archivo jobs.css sólo es necesario en la portada del sitio y el archivo job.css sólo debe incluirse en la página que muestra cada oferta de trabajo. Cada módulo de la aplicación puede definir su propio archivo de configuración view.yml, por lo que modifica el archivo view.yml de la aplicación para que sólo incluya el archivo main.css:

# apps/frontend/config/view.yml
stylesheets:    [main.css]

Para modificar la parte de la vista del módulo job, crea un nuevo archivo view.yml en el directorio apps/frontend/modules/job/config/ y añade el siguiente contenido:

# apps/frontend/modules/job/config/view.yml
indexSuccess:
  stylesheets: [jobs.css]

showSuccess:
  stylesheets: [job.css]

Como se verá más adelante, indexSuccess y showSuccess son los nombres de las plantillas asociadas con las acciones index y show. El archivo view.yml del módulo utiliza estos nombres para crear las secciones que modifican el aspecto de cada acción. En cada sección se pueden establecer las mismas opciones que se encuentran en la sección default del archivo view.yml de la aplicación. Cuando no se define el valor de alguna opción en el archivo view.yml del módulo, Symfony lo toma directamente del archivo view.yml de la aplicación. Si quieres establecer una misma opción para todas las acciones del módulo, debes hacerlo bajo una sección especial llamada all.

Cómo funcionan los archivos de configuración en Symfony En la mayoría de archivos de configuración de Symfony, se puede establecer la misma opción en diferentes niveles:

La configuración por defecto, que se encuentra en los propios archivos del framework
La configuración global del proyecto, que se encuentra en config/
La configuración local de la aplicación, que se encuentra en apps/[nombre_de_aplicacion]/config/
La configuración local del módulo, que se encuentra en apps/[nombre_de_aplicacion]/modules/[nombre_de_modulo]/config/

Cuando se ejecuta la aplicación, el sistema de configuración de Symfony junta todos los valores de todas las opciones de todos los archivos de configuración y los guarda en la cache para mejorar el rendimiento.

Como regla general, cualquier opción que se puede configurar en un archivo de configuración también se puede configurar mediante código PHP. En el ejemplo anterior, en vez de crear un archivo view.yml para el módulo job, se podría utilizar el helper use_stylesheet() para incluir una hoja de estilos directamente desde la plantilla:

<?php use_stylesheet('main.css') ?>

Este helper también se puede utilizar en el layout para incluir una hoja de estilos específica en todas las páginas de la aplicación.

Elegir un método u otro para configurar la parte de la vista es una cuestión de preferencias personales. Realizar la configuración con un archivo view.yml permite definir opciones para todas las acciones del módulo, algo que no es posible desde una plantilla, pero la configuración es bastante estática. Por otra parte, realizar la configuración con el helper use_stylesheet() es más flexible y además permite disponer en el mismo lugar del código HTML y de la definición de los archivos CSS. Jobeet va a hacer uso del helper use_stylesheet(), por lo que puedes borrar el archivo view.yml que acabamos de crear y puedes actualizar las plantillas con las llamadas al helper use_stylesheet():

<!-- apps/frontend/modules/job/templates/indexSuccess.php -->
<?php use_stylesheet('jobs.css') ?>

<!-- apps/frontend/modules/job/templates/showSuccess.php -->
<?php use_stylesheet('job.css') ?>

Nota De la misma forma, la configuración de los archivos JavaScript se realiza mediante la opción javascripts del archivo de configuración view.yml o mediante llamadas al helper use_javascript() desde una plantilla.