#298 Getting Started with Spree

Spree es una solución completa de e-commerce que se puede integrar fácilmente en una aplicación Rails, para convertirla en una tienda que venda productos. En este episodio configuraremos Spree sobre una aplicación Rails nueva y ajustaremos algunas de sus funcionalidades para hacernos una idea de cómo funciona y ver si encaja con las necesidades de nuestras aplicaciones.

Instalación de Spree

Spree depende de ImageMagick para gestionar el procesamiento de imágenes, por lo que lo tenemos que instalarla antes que Spree. La forma más sencilla es usar HomeBrew.

$ brew install imagemagick

Tras la instalación de ImageMagick crearemos una nueva aplicación Rails 3.1 que llamaremos store. Spree se puede integrar en una aplicación Rails ya existente, pero es buena idea empezar con una aplicación nueva para ver las cosas que añade.

$ rails new store

Para instalar Spree y sus dependencias tenemos que añadirlo al Gemfile de nuestra aplicación y luego ejecutar bundle. Spree se actualiza con mucha frecuencia, por lo que hemos especificado el número de versión. La versión más reciente en el momento de escribir este episodio es la 0.70.1.

source 'http://rubygems.org'

gem 'rails', '3.1.1'

gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.1.4'
  gem 'coffee-rails', '~> 3.1.1'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'

group :test do
  gem 'turn', :require => false
  # Pretty printed test output
end

gem 'spree', '0.70.1'

Tras la instalación de las gemas tenemos que ejecutar un generador para añadir Spree a nuestra aplicación.

$ rails g spree:site

Esta orden hace varias cosas. Copia los ficheros de migración que crea las tablas de la base de datos necesarias para Spree y cambia algunos de los archivos de configuración de nuestra aplicación, la mayoría dentro de app/assets. El generador también eliminará los archivos application.js y application.css por lo que si los hemos personalizado tendremos que integrar nuestros cambios a la manera que Spree organiza los recursos de la aplicación.

Veremos que en los subdirectorios de app/assets de nuestra aplicación (images, javascripts y stylesheets) ahora aparecen nuevos directorios llamados admin y store. Esto se hace así para que podamos tener separados los recursos de la tienda de cara al público y su panel de administración. En el fichero all.css (o application.js) podremos ver que se hace require de varios archivos que se encuentran dentro de Spree.

/*
 * This is a manifest file that'll automatically include all the stylesheets available in this directory
 * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
 * the top of the compiled file, but it's generally better to create a new file per style scope.
 *

 *= require store/spree_core
 *= require store/spree_auth
 *= require store/spree_api
 *= require store/spree_promo
 *= require store/spree_dash

 *= require_self
 *= require_tree .
*/

Antes de dar por concluida nuestra etapa de configuración aún nos queda una orden por lanzar que ejecutará las migraciones copiadas anteriormente. Nótese que nos preguntará si queremos destruir los contenidos que ya existen en la base de datos.

$ rake db:bootstrap
This task will destroy any data in the database. Are you sure you want to 
continue? [y/n] y
db/development.sqlite3 already exists
...

La orden también nos preguntará por una dirección de correo y una clave para el usuario de administración. Utilizaremos los valores que nos dan por defecto. Por último se nos preguntará si queremos cargar ciertos datos de ejemplo y diremos que sí para tener algo que ver en la tienda.

Email [spree@example.com]: 
Password [spree123]: 
Load Sample Data? [y/n]: y

Ya podemos empezar con el servidor de nuestra aplicación y echarle un vistazo.

Un vistazo rápido a Spree

Este es el aspecto de nuestra tienda. Por defecto no se aplica ningún tema, por lo que todo tiene un aspecto bastante plano, pero de todas formas tenemos una tienda completa de e-commerce en nuestro sitio, con todos los productos de ejemplo generados anteriormente, incluyendo además un carrito de la compra y un proceso de checkout.

Hay también una sección de administración a la que se puede acceder por http://localhost:3000/admin, y podremos verla una vez que hayamos iniciado la sesión utilizando la dirección de correo y la clave que nos proporcionó el generador. Se trata de una interfaz de administración bastante completa donde podremos ver los pedidos procesados, y varias gráficas que nos muestran cuáles son los productos más vendidos. También podemos ver y editar los productos y pedidos en otras secciones.

La sección de administración también dispone de varias opciones de configuración, incluyendo la posibilidad de cambiar los métodos de pago de la tienda (diferentes para cada entorno) siendo configurables las distintas credenciales para cada pasarela de pago.

Personalización

Con todo esto ya tenemos una solución de e-commerce bastante completa en nuestra aplicación Rails, pero ¿y si queremos tener más control sobre el aspecto exacto de la tienda? La plantilla por defecto de la tienda es bastante sosa, porque no se ha aplicado ningún tema. Dedicaremos el resto de este episodio a ver varias maneras de personalizar el comportamiento y el aspecto de la tienda.

Spree soporta temas y extensiones, y el tema Blue Theme sirve como ejemplo de cómo podemos persoanlizar Spree. Este tema, como la mayoría de extensiones de Spree, es un engine de Rails, por lo que podemos usarlo para redefinir diversos contenidos de los directorios app/assets y app/overrides. Para instalar el tema, tan sólo tenemos que añadir el siguiente archivo al Gemfile, y ejecutar bundle.

gem 'spree_blue_theme', :git => 'git://github.com/spree/spree_blue_theme.git'

Para que el tema funcione es necesario cambiar una hoja de estilos y cambiar los estilos por defecto (los que empiezan por require store/) por el que se suministra con el tema.

/*
 * This is a manifest file that'll automatically include all the stylesheets available in this directory
 * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
 * the top of the compiled file, but it's generally better to create a new file per style scope.
 *

 *= require store/screen
 *= require_self
 *= require_tree .
*/

La tienda queda tras esto con un aspecto totalmente diferente. El uso de temas sirve como ejemplo de cómo se puede personalizar el aspecto de una aplicación basada en Spree.

Cómo personalizar partes individuales del sitio

A continuación veremos cómo personalizar secciones individuales del sitio. Si, por ejemplo, queremos cambiar el logotipo de la parte superior de la página por el nuestro, por supuesto podemos hacerlo. La imagen por defecto está en /assets/admin/bg/spree_50.png, y la instala el engine de Spree, pero en nuestra aplicación podemos redefinirla.

Hay dos formas de hacerlo. Una es crear el directorio /app/assets/images/admin/bg en nuestra aplicación y copiar otra imagen, por ejemplo la imagen por defecto rails.png, cambiándole el nombre a spree_50.png. La imagen tendrá precedencia sobre la imagen por defecto, y lo veremos al recargar la página (aunque probablemente tengamos que reiniciar el servidor para que se detecten los cambios).

Otra forma de modificar el logo es redefiniendo parte de la configuración de Spree. La configuración por defecto se encuentra en un fichero que contiene un gran número de opciones de configuración, que incluye una opción que dice a dónde apunta el logotipo por defecto. Spree contiene un completo sistema de preferencias que nos permite configurar estas opciones de varias maneras. Podemos hacerlo mediante la base de datos, mediante el panel de administración o podemos crear un inicializador y hacer los cambios mediante Ruby. Escogeremos esta última opción y crearemos un nuevo fichero de configuración spree.rb.

Spree::Config.set(logo: "store/rails.png")

Se usa Spree::Config.set para establecer opciones de configuración, y habiendo configurado el logotipo podemos mover nuestra imagen a /app/assets/images/store y llamarla rails.png. Cuando volvamos a cargar la página veremos que la imagen se encuentra en http://localhost:3000/assets/store/rails.png.

También se puede personalizar Spree redefiniendo partes de una plantilla. Para hacer esto tenemos que encontrar la plantilla en el código fuente de Spree. Esto no es muy difícil pero tendremos que tener cuidado de examinar el código fuente de la misma versión de Spree que hayamos instalado como gema. En nuestro caso tendremos que ver la versión 0.70.1. Tras esto podemos navegar hasta core/app/views/layouts, que es la plantilla que debemos redefinir porque contiene el código que muestra el logotipo.

<div id="logo" data-hook>
  <%= logo %>
</div>

Hay dos formas de hacer este cambio. Podríamos copiar el layout al mismo sitio en nuestra aplicación, y Spree usará esta nueva plantilla en lugar de la de por defecto, reflejándose en nuestra aplicación cualquier cambio que hagamos en ella.

Otra forma de hacerlo es usar una gema llamada Deface. No tenemos por qué instalar esta gema porque ya es una dependencia de Spree, y podemos usarla en el directorio /app/overrides que generó la instalación de Spree para poder redefinir parte de las plantillas de Spree. La información del README de la página del proyecto contiene varios ejemplos que muestran su fucnionamiento. Copiaremos el primer ejemplo a un nuevo fichero en este directorio llamado logo.rb y lo modificaremos para la parte de la página que queramos cambiar.

Deface::Override.new(:virtual_path => "layouts/spree_application", 
                     :name => "logo", 
                     :replace_contents => "#logo", 
                     :text => "Store")

Aquí podemos usar cuatro opciones. El virtual_path es la ruta a la plantilla erb que deseamos modificar, mientras que el name puede ser cualquier cosa. Queremos reemplazar los contenidos de un div que tiene un id igual a logo, por lo que utilizaremos la opción replace_contents y le pasaremos un selector CSS que selecciona dicho div. La opción final especifica con qué queremos cambiar dicho contenidos; por ahora cambiaremos el logotipo por el texto “Store”.

Si recargamos la página veremos que ha desaparecido el logo y que en su lugar aparece un texto.

Aunque hemos cambiar la imagen por texto, tenemos que darle algo de estilos, que podremos añadir en el directorio stylesheets/store. Es buena práctica hacerlo con un nuevo archivo. Haremos que el texto sea un poco más grande y el color sea blanco.

#logo {
  font-size: 32px;
  color: #FFF;
}

Si ahora visitamos la aplicación veremos los nuevos estilos.

Con esto terminamos este episodio. Spree ofrece mucha más funcionalidad que no hemos visto hoy aquí, por lo que se recomienda leer las Guías de Spree donde hay mucha más información: hay un apartado dedicado a prácticamente cualquier cosa que necesitemos saber acerca de Spree.