Sass, el manual oficial

Capítulo 3. Usando Sass

Sass se puede utilizar de tres maneras diferentes: 1) en la consola de comandos, 2) como módulo de Ruby, 3) como plugin de cualquier framework compatible con Rack (como por ejemplo Ruby on Rails y Merb).

Independientemente de cómo lo utilices, el primer paso siempre consiste en instalar Sass con el siguiente comando:

$ gem install sass

Si utilizas Windows, es posible que primero tengas que instalar Ruby.

Para utilizar Sass en la línea de comandos, simplemente ejecuta el comando sass:

$ sass hoja_estilos.scss archivo_generado.css

Si lo prefieres, también puedes añadir la opción --watch para decirle a Sass que vuelva a generar el archivo CSS cada vez que se cambie la hoja de estilos original:

$ sass --watch hoja_estilos.scss:archivo_generado.css

Si dispones de un directorio con muchos archivos Sass, también puedes vigilarlos todos por si se producen cambios en alguno de ellos:

$ sass --watch app/sass:public/stylesheets

Para obtener toda la documentación sobre las opciones disponibles en este comando, ejecuta lo siguiente:

$ sass --help

Usage: sass [options] [INPUT] [OUTPUT]

Description:
  Converts SCSS or Sass files to CSS.

Options:
    --stdin          Read input from standard input instead of an input file
    --trace          Show a full traceback on error
    --unix-newlines  Use Unix-style newlines in written files.
    --scss           Use the CSS-superset SCSS syntax.
    --watch          Watch files or directories for changes.
    ...

Por otra parte, si quieres utilizar Sass directamente en tu aplicación Ruby, sólo debes instalar la gema, añadirla en tu aplicación con require "sass" y después utilizar Sass mediante el Sass::Engine:

engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss)
engine.render #=> "#main { background-color: #0000ff; }\n"

3.1. Plugin para Rack, Rails y Merb

Para activar Sass en las versiones de Rails anteriores a la 3, añade la siguiente línea en el archivo environment.rb:

config.gem "sass"

Si utilizas Rails 3 o superior, añade la siguiente línea en el archivo Gemfile:

gem "sass"

Para activar Sass en Merb, añade la siguiente línea en el archivo config/dependencies.rb:

dependency "merb-haml"

Para activar Sass en cualquier otra aplicación compatible con Rack, añade lo siguiente en el archivo config.ru:

require 'sass/plugin/rack'
use Sass::Plugin::Rack

Las hojas de estilos Sass funcionan de manera muy diferente a las vistas. Como no incluyen contenidos dinámicos, el archivo CSS generado sólo debe actualizarse cuando se modifica el archivo Sass original.

Por defecto los archivos .sass y .scss se guardan en el directorio public/stylesheets/sass (para modificarlo, utiliza la opción :template_location). Después, siempre que es necesario, se compilan como archivos CSS en el directorio public/stylesheets/. Así que por ejemplo, el archivo public/stylesheets/sass/main.scss se compila en el archivo public/stylesheets/main.css.

3.2. Cacheando los archivos compilados

Por defecto Sass guarda en la caché la compilación de las hojas de estilos y de los partials. Esto hace que la recompilación de los estilos en las aplicaciones complejas sea mucho más rápida. Para obtener los mejores resultados, divide las hojas de estilos grandes en varios archivos pequeños e impórtalos después con la directiva @import.

Si no utilizas un framework, Sass guarda los archivos cacheados en el directorio oculto .sass-cache. En Rails y Merb, estos archivos se guardan en tmp/sass-cache. Para modificar este directorio, utiliza la opción :cache_location. Si quieres deshabilitar la caché de Sass, establece el valor false en la opción :cache.

3.3. Opciones de configuración

Las opciones de configuración de Sass se establecen mediante el hash Sass::Plugin#options en Rails (archivo environment.rb) y Rack (archivo config.ru):

Sass::Plugin.options[:style] = :compact

Si utilizas Merb, añade el hash Merb::Plugin.config[:sass] en el archivo init.rb o pasa un hash de opciones a {Sass::Engine#initialize}:

Merb::Plugin.config[:sass][:style] = :compact

Las opciones de configuración más importantes también están disponibles mediante opciones de los comandos sass y scss: A continuación se muestran todas las opciones disponibles:

:style, establece el estilo del archivo CSS generado, tal y como se explica en los siguientes capítulos.

:syntax, indica la sintaxis utilizada en la hoja de estilos. Sus valores pueden ser :sass (sintaxis tabulada) y :scss (sintaxis compatible con CSS3). Esta opción sólo es útil cuando creas instancias de {Sass::Engine} a mano. Si no, el valor se establece automáticamente al utilizar {Sass::Plugin}. Su valor por defecto es :sass.

:property_syntax, obliga a las hojas de estilo tabuladas a utilizar un único formato para las propiedades CSS. Si se utiliza al menos una vez cualquier otro formato, se produce un error:

  • :new, obliga a añadir dos puntos después del nombre de la propiedad (ejemplo color: #0f3 o width: $main_width).
  • :old, obliga a utilizar los dos puntos por delante del nombre de la propiedad (ejemplo :color #0f3 o :width $main_width).

Por defecto se permite el uso de los dos formatos indistintamente. Obviamente esta opción no tiene ningún efecto en las hojas de estilo con la sintaxis SCSS.

:cache, indica si las hojas de estilo compiladas se debe guarda en la caché o no. Si se cachean, el tiempo de compilación se reduce drásticamente. El valor por defecto es true.

:read_cache, si se establece esta opción pero no la opción :cache, Sass utiliza (si existe) la caché para leer sus contenidos, pero no trata de escribir en la caché si no existe.

:cache_store, indica la caché que se utiliza para leer y escribir los archivos compilados. Su valor debe ser una instancia de una subclase de {Sass::CacheStores::Base}. El valor por defecto es {Sass::CacheStores::Filesystem}, que a su vez utiliza la opción :cache_location para inicializar la caché.

:never_update, indica que los archivos CSS no deben actualizarse nunca, incluso aunque las hojas de estilo originales hayan cambiado. Si estableces su valor a true, mejorará ligeramente el rendimiento de la aplicación. Su valor por defecto obviamente es false. Esta opción solamente tiene sentido cuando utilizas Sass dentro de Rack, Ruby on Rails o Merb.

:always_update, indica que los archivos CSS deben actualizarse siempre que algún controlador acceda a ellos, incluso aunque las hojas de estilo originales no hayan cambiado. Su valor por defecto es false y solamente tiene sentido utilizarla dentro de Rack, Ruby on Rails o Merb.

:always_check, indica que cada vez que un controlador acceda a las hojas de estilos, estas deben comprobarse para ver si se han actualizado. Su valor por defecto en producción es false, por lo que las hojas de estilos sólo se comprueban al arrancar el servidor. Fuera del entorno de producción su valor es siempre true. Esta opción solamente tiene sentido dentro de Rack, Ruby on Rails o Merb.

:poll, si vale true se utiliza el sistema de polling del backend en vez del sistema de archivos del backend para comprobar si han cambiado las hojas de estilos mediante {Sass::Plugin::Compiler#watch}.

:full_exception, indica si los errores en el código Sass deben proporcionar información detallada dentro del propio archivo CSS. Si su valor es true, los errores muestran el número de línea donde se han producido y un pequeño extracto del código original. Esta información se añade como comentarios dentro del propio archivo CSS. Si su valor es false, se lanza una excepción a nivel de código Ruby. En producción su valor por defecto es false y en el resto de entornos su valor es true. Esta opción sólo tiene sentido en Rack, Ruby on Rails o Merb.

:template_location, indica la ruta al directorio donde se encuentran las hojas de estilo Sass de la aplicación. Si este valor es un hash, se ignora la opción :css_location y se utiliza el valor del hash para asociar cada directorio origen con su directorio destino.

Esta opción también puede ser una lista de pares de elementos en vez de un hash. Su valor por defecto es css_location + "/sass". Solamente tiene sentido en Rack, Ruby on Rails o Merb. Si especificas varios directorios, todos ellos se incluyen dentro de las rutas importadas con import, lo que significa que puedes importar cualquier archivo desde cualquier otro, sin importar donde se encuentre.

Como el valor de esta opción puede establecerse de muchas maneras diferentes, esta opción solamente debería configurarse directamente, sin que después se acceda o modifique su valor. Como alternativa puedes utilizar los métodos Sass::Plugin#template_location_array, Sass::Plugin#add_template_location y Sass::Plugin#remove_template_location.

:css_location, indica la ruta al directorio donde se guardan los archivos CSS compilados a partir de las hojas de estilo Sass. Si el valor de la opción :template_location es un hash, esta opción se ignora. Su valor por defecto es "./public/stylesheets" y sólo tiene sentido cuando se utiliza Rack, Ruby on Rails o Merb.

:cache_location, indica la ruta al directorio donde se guardan las hojas de estilo cacheadas (que son archivos con formato sassc). Su valor por defecto es "./tmp/sass-cache" en Rails y Merb, y "./.sass-cache" en cualquier otra aplicación. Si utilizas la opción :cache_store, esta opción se ignora.

:unix_newlines, si su valor es true, las nuevas líneas de los archivos generados siguen el formato Unix. Esta opción sólo es útil cuando empleas Windows y Sass genera los archivos directamente (en otras palabras, cuando utilizas la consola de comandos o el plugin {Sass::Plugin} en Rack, Rails o Merb).

:filename, establece el nombre del archivo que se está renderizando. Solamente se utiliza para generar informes de Sass y su valor se establece automáticamente cuando utilizas Rack, Rails o Merb.

:line, establece el número de la primera línea del archivo Sass. Esta opción solamente se utiliza para indicar el número de línea donde se ha producido un error. Esta opción es necesaria cuando el código Sass se encuentra embebido dentro de un archivo Ruby.

:load_paths, se trata de un array de rutas a directorios que deben utilizarse para buscar archivos Sass cuando se importan hojas de estilos con la directiva @import. Puedes indicar estas rutas mediante cadenas de texto, objetos de tipo Pathname o subclases de {Sass::Importers::Base}. Su valor por defecto es el directorio de trabajo y en Rack, Rails o Merb, también se utiliza la ruta de la opción :template_location. Otra forma de obtener estas rutas es mediante {Sass.load_paths} y mediante la variable de entorno SASS_PATH.

:filesystem_importer, es una subclase de {Sass::Importers::Base} que se emplea importar hojas de estilos almacenadas del sistema de archivos. Su valor debe ser una clase que herede de {Sass::Importers::Base} y cuyo constructor tome como argumento una única cadena de texto que indica la ruta al directorio en el que se encuentran las hojas de estilos. Su valor por defecto es {Sass::Importers::Filesystem}.

:sourcemap, si su valor es true, Sass genera los source maps estándar de JSON para los archivos CSS compilados. Estos source maps le dicen al navegador dónde puede encontrar los archivos Sass originales utilizados para generar los archivos CSS. Sass supone que las hojas de estilo originales estarán disponibles en cualquier servidor que utilices y que se encontrarán (de manera relativa) en el mismo directorio que en el sistema de archivos local. Si este no es tu caso, debes crear una clase que extienda de {Sass::Importers::Base} o {Sass::Importers::Filesystem} y redefinir en ellas el método public_url.

:line_numbers, si vale true los archivos CSS compilados incluyen en cada selector un comentario con la línea y el nombre del archivo original donde se define ese selector. Esta opción es útil para depurar la compilación de archivos, especialmente cuando importas archivos o utilizas mixins. Esta opción también se puede utilizas a través del nombre :line_comments. Esta opción no se tiene en cuenta si utilizas el formato de salida :compressed o las opciones :debug_info y :trace_selectors.

:trace_selectors, si vale true, cada selector incluye la lista completa de archivos importados y mixins que lo han generado. Esto es útil para depurar la hoja de estilos dentro del propio navegador. Esta opción tiene más prioridad que la opción :line_comments pero a la vez tiene menos prioridad que la opción :debug_info. Además, esta opción se deshabilita automáticamente si utilizas el formato de salida :compressed.

:debug_info, si vale true, el archivo CSS compilado incluye para cada selector la línea y el nombre del archivo donde se define. Además, la información se define en un formato que pueden entender los navegadores. Esta opción es especialmente útil cuando se utiliza la extensión FireSass para Firebug. Si utilizas el formato de salida :compressed, esta opción se deshabilita.

:custom, opción que permite establecer opciones para las funciones propias definidas en tus hojas de estilos.

:quiet, si su valor es true, se desactivan todos los mensajes de aviso.

3.4. Selección de la sintaxis

Los comandos de Sass utilizan la extensión de cada archivo para determinar la sintaxis que estás utilizando. No obstante, en ocasiones el código Sass no está definido en ningún archivo y por tanto no es posible determinar la sintaxis automáticamente.

En estos casos, el comando sass siempre utiliza por defecto la sintaxis tabulada, pero puedes utilizar la opción --scss para forzar a que el comando utilice la sintaxis SCSS. Si lo prefieres, tienes disponible otro comando llamado scss que funciona exactamente igual que el comando sass pero que considera que la sintaxis por defecto es SCSS.

3.5. Codificación

Si utilizas Ruby 1.9 o superior, Sass es capaz de determinar automáticamente la codificación de cada hoja de estilos. Si no, Sass considera por defecto que la codificación de los archivos es la misma que la codificación por defecto del sistema operativo.

En la mayoría de los casos esto supone que la codificación por defecto es UTF-8, que a su vez es la codificación más utilizada en la web. En cualquier caso, para algunos usuarios la codificación de sus sistemas operativos puede no ser la más correcta.

Para indicar explícitamente la codificación de las hojas de estilos, añade en ellas una directiva @charset, tal y como se hace en los archivos CSS normales. Esta directiva tiene que ser el primer contenido de la hoja de estilos, por lo que debes añadirla antes que cualquier selector e incluso antes que cualquier comentario.

Ten en cuenta que utilices la codificación que utilices, esta debe ser convertible a Unicode. Además, Sass no modifica el BOM y cualquier otra codificación Unicode no compatible con ASCII que puedan contener los archivos. Sass no soporta las codificaciones UTF-32-2143, UTF-32-3412, EBCDIC, IBM1026 y GSM 03.38 porque Ruby tampoco las soporta y apenas se utilizan en el mundo real.

3.5.1. Codificación de los archivos compilados

Sass siempre trata de codificar los archivos CSS compilados con la misma codificación que las hojas de estilo originales. Para que esto sea posible, las hojas de estilo deben contener la directiva @charset. Además, a menos que la codificación sea ASCII, a los archivos CSS compilados también se les añade la directiva @charset.

Si en un archivo importas otras hojas de estilo que incluyen la directiva @charset, Sass convierte todas esas hojas de estilo a la codificación del archivo principal.

Ten en cuenta que Ruby 1.8 y las versiones anteriores no tienen un buen soporte para la codificación de caracteres. Por eso Sass puede comportarse un poco diferente si se ejecuta con Ruby 1.8 o 1.9. En las versiones de Ruby 1.8, Sass simplemente utiliza la primera directiva @charset que encuentre en cualquier hoja de estilos, sea la principal o alguna que se ha importado mediante la directiva @import.