OmbuShop: Liquid API
Esta es una guía para modificar el diseño de una tienda sobre OmbuShop.
Gracias a la avanzada tecnología de templates que utiliza OmbuShop, cada diseñador web puede modificar por completo el diseño de sus tiendas.
Se puede personalizar el código HTML, CSS y JavaScript de cada uno de los shops.
Cómo modificar el diseño de una tienda
La estructuración del contenido, el diseño y el comportamiento de una tienda se logra modificando los archivos HTML, CSS y JavaScript que la componen.
HTML
El HTML que genera OmbuShop para la muestra de los contenidos puede modificarse ingresando a la sección Diseño > Templates, dentro del panel de administración de la tienda.
Son estos templares los que se modifican utilizando Liquid. Sigue leyendo para saber cómo funciona. ¡Es muy fácil!
CSS
El CSS que describe el diseño de la tienda puede modificarse ingresando a la sección Diseño > Hojas de Estilo, dentro del panel de administración de la tienda.
JS
Pueden agregarse archivos JavaScript que generen nuevos comportamientos para la tienda subiendo archivos en la sección Diseño > Archivos, dentro del panel de administración de la tienda. Luego será necesario agregarlo con la etiqueta <script> en el head del HTML.
Introducción a Liquid
OmbuShop utiliza Liquid para la creación y modificación de los templates que definen el HTML de las tiendas online; se trata de un lenguaje de templating que combina los tags tradicionales de HTML con otros que le son propios, llamados tags especiales.
Liquid nos permite generar código HTML de forma dinámica, aún con conocimientos básicos de programación.
Tags Especiales
Tags De Texto
Estos tags generan texto en base a una variable. Se abren con {{ y se cierran con }}
Ejemplo:
{{ product.title }}
Por lo general, las tags de texto imprimen cierta información dentro de una etiqueta de HTML. Por ejemplo:
<h1>{{ product.title }}</h1>
De esa manera, el título del producto aparecerá dentro de una etiqueta de tipo <h1>.
Tags Lógicos
A diferencia de los anteriores, estos tags no generan texto. Se abren con {% y se cierran con %}
Se utilizan para controlar la salida de HTML y construir estructuras lógicas.
Pueden emplearse para chequear condiciones, iterar sobre colecciones (por ejemplo: colecciones de productos) y manejar variables.
Ejemplo:
{% if current_order.item_count == 0 %}
<a href="/cart" class="empty" title="Cart">Carrito Vacío</a>
{% else %}
<a href="/cart" class="full" title="Cart">Carrito: {{ current_order.item_count }}</a>
{% endif %}
El HTML mostrará <a href="/cart" class="empty" title="Cart">Carrito Vacío</a> si no hay items en la ordain, o <a href="/cart" class="full" title="Cart">Carrito: {{ current_order.item_count }}</a> si existen elements agregados al carrot.
Más Información sobre tags especiales de Liquid
Aquí podrán encontrar más información sobre Liquid:
Filtros de Texto
Cada variable puede ser filtrada para producir una salida de texto específica.
Existen filtros útiles para generar tags de <script>, <link> y código HTML de paginación.
Para ver todos los filtros disponibles: LiquidFilters
Ejemplo de un Template
En este ejemplo recorremos una colección de productos, mostramos el nombre de cada producto, su precio y una breve descripción.
<ul id="products">
{% for product in products %}
<li>
<h2>{{ product.name }}</h2>
Only {{ product.price }}
<p>{{ product.description | truncate: 200 }}</p>
</li>
{% endfor %}
</ul>
Podemos ver los tags de texto, la aplicación de un filtro y el tag lógico para recorrer la colección.
Por lo general, la lista de productos se incluye en el template llamado index.liquid, que puede ser modificado desde Diseño > Templates, en el administrador de la tienda.
Introducción a OmbuShop
OmbuShop te permite crear tiendas online de una forma simple, rápida y flexible.
Actualmente la plataforma te permite modificar el HTML de las siguientes páginas:
Índice de Productos (Por ejemplo: http://demo.ombushop.com)
Página de Producto (Por ejemplo: http://demo.ombushop.com/products/mountain-sweater)
Y las partes de código que son comunes a todo el sitio, como las que arman el layout, las botoneras, la lista de categorías, etc.
Además, te permite modificar el CSS de todo tu sitio, pero para esto no es necesario saber Liquid!
Shop Themes
Cada shop tiene un theme para el estilo de su sitio. Cada tienda puede cambiar su theme en cualquier momento.
Cada theme de OmbuShop tiene la siguiente estructura:
- Layout
- Templates
- Snippets
- CSS
- Archivos extra (archivos de tipo JavaScript, JPEG, GIF, PNG, etc.)
Layout
theme.liquid
Este template es el contenedor de todas las páginas. Arma el marco que tendrá el contenido en cada una de las secciones de tu tienda.
El código definido en este template estará visible en todas las páginas del sitio: define código común a todas las secciones, como el encabezado del HTML, el layout general de la página y pie.
Para su correcto funcionamiento, este template debe incluir el tag {{ content_for_layout }} que indica dónde irá el contenido específico de la página correspondiente (según el path que esté viendo el usuario).
Templates
index.liquid
Muestra la lista de productos de tu tienda (paginados o no). Salvo que una página estática esté seleccionada para funcionar como home, este listado de productos se verá como portada de tu tienda.
show.liquid
Este template es el que se encarga de mostrar el detalle de un producto, armando su página específica. Muestra un producto en particular por vez: sus fotos, descripción, precio, botón de comprar, etc.
Snippets
Se trata de templates parciales que tienen una función específica. Se incluyen desde los templates principales: index.liquid, show.liquid o theme.liquid.
El objetivo es evitar la repetición de código. Entonces, cada vez que —por ejemplo— sea necesario insertar las categorías de producto de una tienda, bastará con escribir {% include 'sidebar' %}.
Existen dos snippets que pueden ser modificados e incluidos en los templates donde se los vaya a necesitar: _flash.liquid y _sidebar.liquid.
_flash.liquid
Este snippet se utiliza para mostrar notificaciones del sistema: Mensajes de éxito o error en base a las acciones del visitante.
_sidebar.liquid
Este snippet se utiliza normalmente para mostrar la lista de categorías de la página index.liquid.
También se podría incluir en otra página, para mostrar búsquedas realizadas o categorías disponibles en la tienda.
Ejemplos de Código en Liquid
A continuación veremos una serie de ejemplos que te ayudarán a generar código en Liquid.
Mostrar la imagen principal de un producto
Si el producto tiene una imagen principal, este código mostrará la imagen con el título alternativo de la imagen.
Si el producto no tiene imagen, mostrará un archivo de imagen por defecto, indicando que dicho producto no tiene imagen.
{% if product.featured_image %}
<img src="{{ product.featured_image.src }}" title="{{ product.featured_image.alt | capitalize }}"></img>
{% else %}
<img alt="No image" src="/images/noimage/product.jpg"></img>
{% endif %}
Además de src y alt, las imágenes tienen otras propiedades disponibles. Para ver más información sobre los objetos de tipo imagen: Image
Mostrar un listado de productos con paginación
El siguiente código se encarga de paginar los productos de a 12 ítems y muestra el paginado al final, dentro del div con clase pagination.
Además, se pregunta de cuáles productos hay stock, y muestra únicamente los que estén disponibles.
{% paginate products by 12 %}
{% if products.size > 0 %}
<ul class="product-listing">
{% for product in products %}
{% if product.has_stock? %}
<li id="product_{{ product.id }}" class="{% cycle 'one', 'two', 'three' %}">
{% assign image = product.featured_image %}
<a href="/products/{{ product.to_param }}"><img alt="{{ image.alt }}" src="{{ image.src }}"></img></a>
<a href="/products/{{ product.to_param }}" class="info">{{ product.name }} <span class="price selling">{{ product.price_with_currency }}</span></a>
</li>
{% endif %}
{% endfor %}
</ul>
{% else %}
No se encontraron productos.
{% endif %}
<hr class="space" />
<div class="pagination">
{{ paginate | default_pagination }}
</div>
{% endpaginate %}
Para ver más información sobre los objetos de tipo producto: Product
Mostrar todas las categorías del shop
Muestra a todas las categorías del shop.
Si el usuario está viendo productos de una de las categorías, le agrega al atributo clase "current root".
{% for category in categories %}
<li {% if current_category.id == category.id %} class="current root" {% else %} class="root" {% endif %}>
<a href="{{ category.url }}" title="Categoría: {{ category.name }}">{{category.name}}</a>
<ul class="">
{% for child in category.children %}
<li {% if current_category.id == child.id %} class="current" {% endif %}>
<a href="{{ child.url }}" title="Categoría: {{ child.name }}">{{child.name}}</a>
</li>
{% endfor %}
</ul>
</li>
{% endfor %}
Para ver más información sobre los objetos de tipo categoría: Category
Variables Disponibles por Template
Cada template tiene acceso a diferentes variables, que pueden ser de utilidad para la generación del código HTML.
Globales
Las variables globales pueden ser accedidas desde cualquier template:
categories
Devuelve un Array con objetos de tipo categoría. Ver: Category
content_for_footer
Imprime el contenido para el footer de la tienda. Debe ir dentro de la etiqueta <body>, generalmente hacia el final, justo antes del cierre </body>. String
Por ejemplo:
{{ content_for_footer }}
Si el usuario ingresó su código de Google Analytics, genera:
<div id="ombu-footer" style="display: block !important; text-align: left; clear: both; margin-top:
30px; float: left; width: 120px; font-size: 12px; font-family: Helvetica,sans-serif; margin-bottom: -14px;">
<div style="text-align: left; float: left; padding-right: 2px; font-size: 11px; color: #787878">
<a target="_blank" title="OmbuShop, Tu Tienda Online en Minutos" href="http://www.ombushop.com">
<img style="float: none; margin-bottom: 6px; margin-right: -2px;" src="/images/ombu-logo-gris.png" alt="OmbuShop">
</a>
<span style="font-size: 9px; float: right; margin-right: 15px; margin-top: -8px;">Tu Tienda Online</span>
</div>
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-19743638-1']);
_gaq.push(['_setDomainName', 'tutienda.ombushop.com']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
content_for_header
Imprime el contenido necesario para el header. Debe estar dentro del tag <head>. String
Por ejemplo:
{{ content_for_header }}
Si el producto tiene palabras clave (keywords) "lámpara decoración psicodélica" y la descripción (description) "Lampara de decoración psicodélica de los 70", generará el código:
<meta content="lámpara decoración psicodélica" name="keywords">
<meta content="Lámpara de decoración psicodélica de los 70" name="description">
current_user
Usuario que está viendo la tienda. Ver: User
current_order
El pedido actual del usuario: su orden. Devuelve el carrito de compras del usuario. Ver: Order
current_path
Dirección relativa actual. String
Por ejemplo:
{{ current_path }}
Si estamos viendo la página estática "Quiénes somos", genera:
/quienes-somos
notification
Objeto de tipo Notification con mensajes de sistema.
Por ejemplo:
{{ notification.error }}
Si el cliente quiere iniciar sesión con una contraseña errónea:
La combinación de email y contraseña es inválida.
pages
Devuelve un Array con las páginas autoadministrables de la tienda. Ver: Page
parameters
Parámetros presentes en la URL de la página que se está visitando.
Por ejemplo:
{{ parameters['Color'] }}<br/>
{{ parameters['Tamaño'] }}
Va a mostrar:
Verde<br/>
Mediano
Si la URL que estamos viendo es:
http://demo.ombushop.com/products/mountain-sweater?Color=Verde&Tamaño=Mediano
shop
Tienda que se está viendo. Ver: Seller
Por ejemplo, el siguiente código devuelve el nombre de la tienda:
{{ shop.name }}
Se trata la propiedad name de shop (objeto de tipo Seller).
template
Nombre del template que se está mostrando. Ver: String
Por ejemplo:
{% if template == 'show' %}
Estamos usando el template de Producto!
{% endif %}
Si estamos viendo la página de un producto, mostrará:
Estamos usando el template de Producto!
También puede utilizarse simplemente {{ template }}, código que imprimirá shop, si de ese template se trata.
index.liquid
Desde index.liquid se tiene acceso a las variables:
keywords
Provenientes de una búsqueda. String
Por ejemplo:
{{ keywords }}
Si el usuario buscó "decoración paredes" genera:
decoración paredes
products
Array con objetos de tipo producto. Ver: Product
products_count
Cantidad total de productos. Numeric
Por ejemplo:
{{ products_count }}
Si la cantidad de productos es 7 para la consulta, genera: 7.
current_page
Nombre de la página seleccionada por el usuario. String
Por ejemplo:
{{ current_page }}
Si el usuario está viendo la página 2, genera:
2
current_category
Categoría seleccionada por el usuario. Ver: Category
page.liquid
Desde page.liquid se tiene acceso a las variables:
page
Página que se está viendo. Ver: Page
show.liquid
Desde show.liquid se tiene acceso a las variables:
product
Producto que se está viendo. Ver: Product
current_variant
Variant que se está viendo. Puede no estar disponible. @see Variant#url
Ver Variant
Feedback
Cada shop creado sobre la plataforma tiene su propio theme con Liquid y CSS por default.
Cada diseñador puede modificar por completo el contenido de los archivos .liquid o .css a través del administrador (http://www.ombushop.com/admin).
Estamos mejorando la interfaz de Liquid constantemente. Si tienes alguna idea para mejorarla, por favor contactanos aquí: liquid@ombushop.com!