Masify

Manual de integración de templates

Integración

Detalle de un producto (Ítem)

El tipo de contenido Item, corresponde al detalle de un producto del catálogo.
En este detalle se presentan todos los datos de un producto, un inventario de stocks, sus atributos y propiedades, y las imágenes que se hayan cargado.

Además posee acceso a los datos comunes a todos los tipos de contenido (menús, diccionario, opciones de diseño y configuración, etc.), y puede presentar contenidos relacionados, del tipo Item, del tipo Article y del tipo Page, así como banners que se hayan asignado a este tipo de contenido desde el panel de control.

El archivo item.xsl


El detalle de un producto se representa a través de un archivo llamado item.xsl , ubicado en la carpeta xsl del directorio correspondiente al template en desarrollo.
Este archivo es requerido.

Para descargar un archivo xslt de ejemplo para el tipo de contenido "item" haga click aquí.

Descargar archivo item.xsl

Para descargar el archivo item.js de ejemplo que se utiliza en este capítulo, haga click aquí.

Descargar archivo item.js

Si la descarga provoca un error, haga click con el botón derecho y seleccione la opción "guardar enlace como...".

Datos del producto


Los productos poseen una serie de datos propios, algunos cargados por el administrador del sitio desde el panel de control, y otros provistos por el sistema, que permiten presentar una descripción del mismo.
Todos los datos de un producto están englobados en el nodo xml/item.

Este nodo posee los siguientes elementos:
@Id: Valor numérico, representa el id del producto (Ítem) en la base de datos.
@Code: Código del producto.
@DefaultImageCode: Código de imagen asignada como principial desde el panel de control.
@ItemTypeId: Valor numérico que representa el ID del Tipo de Producto al que pertenece.
Los Tipos de Producto son formatos predefinidos en el sistema Masify que permiten configurar los productos de acuerdo a una serie de atributos y propiedades propios.
ItemTypeDescription: Nombre del Tipo de Producto.
Title: Nombre del producto.
Description: Descripción del producto, en formato HTML.
URLTitle: Slug del nombre del producto, utilizado en la URL. Con este valor, el id de producto y el id de portal al que pertenece, se puede conformar la URL del mismo.
Ej: http://miportal.masify.com/item/details/[id de producto]/[id de portal]/slug
Portal: Nodo con información del sitio web al que pertenece el producto. Estos datos siempre serán iguales a los datos presentes en el nodo xml/Portal presente en todos los tipos de contenidos, salvo cuando los productos se muestren en un portal concentrador o Hub.
El nodo Portal posee los siguientes elementos:
@Id: Valor numérico, representa el id del sitio web (portal) en la base de datos.
@Url: URL completa del sitio web.
@Tenant_Logo_Code: Código de imagen del logo del portal.
Name: Nombre del portal.
UrlName: Nombre del subdominio del portal, en caso de que no utilice una dirección web propia (es igual al valor de Name).


Mostrar los datos básicos de un producto

Datos XML (fragmento)
Implementación XSLT (en item.xsl)

Tags


Los tags son una serie de etiquetas asignadas a un producto que permiten crear identificaciones o grupos de productos más alla de los Tipos de Producto, atributos y propiedades predefinidos en el sistema Masify.
Son útiles a la hora de crear líneas de productos propias que engloben distintos tipos de productos, o condiciones de venta personalizadas, como por ejemplo, "ofertas de fin de temporada", etc.

Los tags de un producto se encuentran en el nodo xml/item/itemTags.
Cada tag está representado por un nodo Tag que posee los siguientes elementos:
@Id: Valor numérico, corresponde al ID del tag en la base de datos.
@Url: URL del listado de productos filtrados por el tag.
Description: Nombre del tag.

Mostrar los tags de un producto

Datos XML (fragmento)
Implementación XSLT (en item.xsl)

Atributos y Propiedades


Los atributos y propiedades son una serie de parámetros predefinidos en el Tipo de Producto al que pertenece un producto, y que permiten configurar y describir de una forma homogénea productos similares.
Pueden también ser utilizados para presentar opciones de configuración en la compra de un producto, o distintas precios en los catálogos que no posean compra.

Atributos - Generalidades

Los atributos poseen una serie valores predeterminados, llamados definiciones, de las cuales el producto puede poseer alguna, ninguna, o todas, de acuerdo a las características de dicha opción.

Por ejemplo, en el Tipo de Producto Indumentaria, el atributo género presenta las siguientes opciones:
Hombre - Mujer - Unisex
Un producto que pertenezca a ese tipo de producto, o a uno de sus derivados (ej.: Indumentaria > Pantalones) , podrá seleccionar la opción que más se ajuste a sus características.
En este caso, el atributo género permite una única opción seleccionada.

Atributos que generan opciones de compra / precios

De acuerdo al Tipo de Producto, uno o más de sus atributos pueden generar las opciones de compra / precios.
Por ejemplo, en una prenda de vestir ( tipo de producto Indumentaria o alguno de sus derivados), los atributos Talle y Color pueden denfir las opciones de compra.

Un ejemplo de productos con distinto precio de acuerdo a un atributo puede ser un departamento que se encuentre en venta y en alquiler, el cual necesita mostrar ambas tarifas (aunque la operación no se realice vía web). El atributo sería "operación", y las opciones, "venta", "alquiler", "alquiler diario", y se podría cargar un precio para una o más de esas opciones.

Los atributos que generan opciones de compra / precios aparecen en el nodo de stocks (en los datos XML), como partes constitutivas de cada uno de los registros de stock.
Sólo aparecerán en un nodo independiente en caso de generar galerías de imágenes.
Para un ejemplo de cómo mostrar los atributos que generan opciones de compra haga click aquí


Atributos que generan galerías de imágenes

También de acuerdo al tipo de producto al que pertenezca el producto, puede poseer un atributo (sólo uno) que genere grupos de imágenes asociadas al mismo a través de sus valores.
(Este atributo puede también ser uno de los que genera opciones de compra.)

Siguiendo el ejemplo anterior, el producto que tiene un atributo "color", podría generar una galería de fotos por cada uno de los colores que posea.

Los atributos que generan grupos de imágenes están listados en el nodo xml/Item/ImageAttributeDefinitionValues, con las imágenes perteniecientes a cada uno.

Cada opción del atributo está representada por un nodo AttributeDefinitionValue que posee los siguientes elementos:
@DefinitionId: Valor numérico, no se utiliza.
@DefinitionType: Valor numérico, Tipo de atributo. Si el valor es 1, se trata de un atributo genérico. Si es 3, de un atributo de color. Si es 4, un atributo de medida.
AttributeValue / Color / AttributeSizeValue: Nodo descriptivo de la opción, que varía de acuerdo a su tipo:
Si la opción pertenece a un atributo genérico (tipo 1), el nodo descriptivo se llamará AttributeValue, con los siguientes elementos:
@Id: Valor numérico, no se utiliza.
@AttributeId: Valor numérico, ID del atributo al que pertenece la opción. No se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Text: El nombre de la opción. Si la opción pertenece a un atributo de color (tipo 3), el nodo descriptivo se llamará Color, con los siguientes elementos:
@HexCode: Valor hexadecimal del color en formato RRGGBB (No incluye el caracter # al comienzo).
@Link: No se utiliza.
@ID: No se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Name: El nombre del color. Si la opción pertenece a un atributo de medidas (tipo 4), el nodo descriptivo se llamará AttributeSizeValue, con los siguientes elementos:
@Id: Valor numérico, no se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Value: El valor de la opción.
 Un listado de nodos ItemImage, uno por cada imágen asociada a la opción. Posee los siguientes elementos:
@Id: Valor numérico, no se utiliza.
@DisplayOrder: Posición de ordenamiento de la imagen dentro del listado.
@IsValueDefault: Valor booleano (True / False). Indica si la imagen es la que debe mostrarse por defecto para el grupo de imágenes al cual pertence (hay una imágen con valor True por grupo de imágenes).
@IsSearchDefault: Valor booleano (True / False). Indica si la imagen es la que debe mostrarse por defecto para el producto. (hay una única imágen con valor True entre todos los grupos de imágenes).
FileImage: Nodo con información de la imágen. Posee los siguientes elementos:
@Code: Código de la imagen a partir del cual se genera la URL de la misma. Ver cómo instanciar imágenes a partir de su código.
@UploadDate: Fecha de subida al servidor.
Para un ejemplo de cómo integrar galerías de imágenes asociadas a un atributo haga click aquí


Otros Atributos descriptivos

Los atributos descriptivos son opciones (y valores para las mismas) que definen a un producto de acuerdo a su tipo, pero que no generan opciones de compra ni galerías de imágenes.

Se listan en el nodo xml/Item/OtherAttributeDefinitionValues.
Cada atributo está representado por un nodo OtherAttributeDefinitionValue que posee los siguientes elementos:
@DefinitionId: Valor numérico, no se utiliza.
DefinitionText: Nombre del atributo.
AttributeDefinitionValues: Nodo que contiene todas las opciones seleccionadas para el atributo.
Cada opción está reperesentada por un nodo AttributeDefinitionValue que posee los siguientes elementos:
@DefinitionId: Valor numérico, no se utiliza.
@DefinitionType: Valor numérico, Tipo de atributo. Si el valor es 1, se trata de un atributo genérico. Si es 3, de un atributo de color. Si es 4, un atributo de medida.
AttributeValue / Color / AttributeSizeValue: Nodo descriptivo de la opción, que varía de acuerdo a su tipo:
Si la opción pertenece a un atributo genérico (tipo 1), el nodo descriptivo se llamará AttributeValue, con los siguientes elementos:
@Id: Valor numérico, no se utiliza.
@AttributeId: Valor numérico, ID del atributo al que pertenece la opción. No se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Text: El nombre de la opción. Si la opción pertenece a un atributo de color (tipo 3), el nodo descriptivo se llamará Color, con los siguientes elementos:
@HexCode: Valor hexadecimal del color en formato RRGGBB (No incluye el caracter # al comienzo).
@Link: No se utiliza.
@ID: No se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Name: El nombre del color. Si la opción pertenece a un atributo de medidas (tipo 4), el nodo descriptivo se llamará AttributeSizeValue, con los siguientes elementos:
@Id: Valor numérico, no se utiliza.
@AttributeDefinitionValueId: ID de la opción. Este valor es el que debe utilizarse para identificar la opción y para realizar interacciones con otros elementos.
Value: El valor de la opción.


Propiedades

Las propiedades son opciones de texto o numéricas predefinidas que pueden o no poseer un valor.
Son valores descriptivos, es decir que no se utilizan para la configuración del producto en el momento de la compra.

Las propiedades están listadas en el nodo xml/Item/Properties, con las imágenes perteniecientes a cada uno.

Cada propiedad está representada por un nodo Property que posee los siguientes elementos:
Id: Valor numérico, no se utiliza.
Name: Nombre de la propiedad.
Value: Valor cargado para la propiedad.


Listar atributos y propiedades

Datos XML (fragmento)
Implementación XSLT (en item.xsl)

Ubicación geográfica (opcional)

Algunos productos por sus características o su forma de venta poseen datos de ubicación, consistentes en una dirección, una ubicación geográfica del tipo País > Provincia o Distrito > Ciudad o Barrio, y datos de geolocalización del tipo latitud-longitud.

Estos datos, que pueden o no estar presentes, se localizan en el nodo xml/Item/Address, que posee los siguientes elementos:
@Id: Valor numérico, no se utiliza.
Street: Nombre de la calle.
@Number: Número de puerta de la dirección.
@Floor: Número de piso.
@Apartment: Departamento.
@PostalCode: Código postal.
@Latitude: Latitud de la dirección, en formato de seis decimales. Puede presentar valores negativos.
@Longitude: Longitud de la dirección, en formato de seis decimales. Puede presentar valores negativos.
Country: País al que pertenece la dirección.
LocationAndParents: Listado de divisiones geográficas a las que pertenece la dirección.
Puede ser del Tipo Provincia > Partido o Departamento > Ciudad o del tipo Distrito > Barrio.
Cada nivel está reperesentado por un nodo Location, ordenados en forma ascentente (el primer nodo corresponde la división geográfica menor, ya sea barrio o ciudad).
Cada nodo posee los siguientes elementos:
@Id: Valor numérico, representa el ID de la división geográfica en Base de Datos.
Name: Nombre de la división geográfica.

Mostrar datos de Ubicación

Datos XML (fragmento)
Función que instancia el mapa (en archivo /js/item.js)
Implementación XSLT (en item.xsl)
            
/**** MAPA GOOGLE ****/

//variable asignada al mapa, que permite modificarlo (por ejemplo para agregarle un marcador)
var map;

//funcion que instancia el mapa (se llama una vez cargada la API mediante la invicación al evento addDomListener que aparece luego de esta función 						
function initialize(lat, lon)
{
	//Reemplaza el caracter decimal de coma por un punto para hacerlo compatible con el formato Google.
	lat = lat.replace(/\,/g, '.');
	lon = lon.replace(/\,/g, '.');
	//crea un objeto de posición con los datos de latitud y longitud
	var latlng = new google.maps.LatLng(lat,lon);
	
	//setea las opciones para el mapa
	var mapProp = {
		center:latlng,
		zoom:15,
		mapTypeId:google.maps.MapTypeId.ROADMAP
	};
	
	//instancia el mapa en el elemento indicado (en este caso el div con id 'map')
	map = new google.maps.Map(document.getElementById("map"),mapProp);
	
	//agrega el marcador
	var marker = new google.maps.Marker({
		map:map,
		position:  latlng,
	});								
}

/**** MAPA GOOGLE - FIN ****/

Imágenes asociadas


Los productos pueden poseer imágenes en un número ilimitado.
Estas imágenes pueden estar asociadas (por grupos) a alguno de los atributos que generan opciones de compra/precios, en caso de que el Tipo de Producto posea estas características.
Esto permite presentar un producto de diferente forma de acuerdo a la opción a las que estén asociadas las imágenes.
Por ejemplo, cargar un grupo de imágenes diferentes para cada opción de color de un producto.

Los grupos de imágenes asociados a atributos utilizados como opciones de compra están listados en el nodo xml/Item/AttributeDefinitionValues dentro de cada nodo AttributeDefinitionValue

En los productos que no poseen imágenes asociadas a un atributo, las mismas se presentan en un único grupo, disponible en el nodo xml/Item/Images.

Listar imágenes asociadas a un atributo

Datos XML (fragmento)
Implementación XSLT (en item.xsl)


Listar imágenes no asociadas a ningún atributo

Datos XML (fragmento)
Implementación XSLT (en item.xsl)

Inventario (stocks)


El inventario de un producto es un listado de sus opciones de compra / precios disponibles, de acuerdo a la configuración del Tipo de Producto al que pertencen.
Cada opción es denominada stock.
Estas opciones pueden utilizarse para configurar el producto para su venta, o simplemente para mostrar distintos precios de acuerdo a dicha configuración.

En los productos que no poseen opciones de compra / precio, existe un sólo registro de inventario.

En los productos que poseen opciones de compra, aparece un registro de inventario por cada combinación de sus opciones.
Por ejemplo, en un pantalón que posee colores rojo y negro y talles S, M y L, los registros de inventario serán 6:
Rojo S, Rojo M, Rojo L, Negro S, Negro M, Negro L.

Cada registro de inventario (stock) puede poseer un precio, moneda y cantidad disponible diferentes.

El inventario de un producto se presenta en el nodo xml/Item/Stocks.

Listar el inventario del producto (stocks)

Datos XML (fragmento)
Implementación XSLT (en item.xsl)

Botón de compra


Las compras se realizan sobre un stock del inventario de un producto.
En caso de que ese stock no posea una cantidad disponible suficente para la venta, el producto no podrá ser comprado.

En este ejemplo se mostrará la integración un botón de compra simple por cada registro (stock) del inventario.
En el capítulo siguiente se extenderán los ejemplo para crear formularios dinámicos de compra.

El proceso de compra de un stock es sencillo, simplemente consiste en invocar la url /Cart/AddToCart/[id del stock] pasándole como valor de la variable quantity la cantidad a comprar.

Por ejemplo, si se quieren comprar 2 productos del stock de id 1669, la URL sería: /Cart/AddToCart/1669?quantity=2
Es importante no confundir el ID del Stock con el ID del producto (Item). Lo que se agrega a la compra SIEMPRE es el ID de Stock.
Dado que la devolución de dicho script se presenta en formato de objeto JSON, es conveniente que la llamada a la URL de compra se realice mediante una función javascript que pueda procesar dicha devolución de datos.

Ejemplo de botón de compra con datos JSON


Botón de compra sobre el listado de stocks del inventario (en item.xsl)
Función de compra JSON (en archivo /js/item.js)

Datos de la compra

Para conocer cómo mostrar un resumen de la compra en todas las páginas, o cómo dirigirse al detalle de la compra, visite nuestro capítulo Integración: Carrito de compras

Banners


Los banners cargados desde el panel de control pueden ser asociados al tipo de contenido Item.
La integración de banners se realiza de forma similar en todos los tipos de contenidos.
Para acceder a la sección correspondiente, haga click aquí:

INTEGRAR BANNERS

Contenidos Relacionados


El tipo de contenido Item admite contenidos relacionados de los trestipos: Item, Article y Page.
Es decir, es posible incluir productos, notas y links a páginas en el detalle de un producto.
La cantidad de sectores de contenidos relacionados es ilimitada.
Pueden definirse varios sectores de productos destacados (ItemForItem), de notas (articleForItem), o de página (itemForPage)si el diseño así lo requiere.

Para ver cómo definir los sectores de contenidos relacionados haga click aquí.

La integración de contenidos relacionados se realiza de forma similar en todos los tipos de contenidos que lo admiten.
Para acceder a la sección correspondiente, haga click aquí:

INTEGRAR CONTENIDOS RELACIONADOS

Integración: Búsqueda de Productos
Integración avanzada de opciones de compra