Embedding and integrating components in HTML
From FluidRetailWiki
Contents |
Overview
This guide covers embedding interactive displays in an HTML page. For embedding merchandisers, please see the Merchandiser Implementation Guide.
Downloading Sample Code
Begin by downloading sample HTML code from the authoring environment. Log in to Fluid Retail, choose the Display Tab and a product you would like to integrate.
Click the Display tab on the right-hand pane and click "View Code." For testing purposes, copy and paste this code into a text file and name it index.html.
Integrating Interactive Merchandising Displays
The code you copied above will be similar to the snippets below and should be placed in the <HEAD> and <BODY> sections of the HTML page where you wish the display to appear.
If you are using text personalization or Fluid Drive, your embed code with appear differently. Contact support@fluidretail.com for specific instructions on embedding this functionality.
Sample code:
Viewing code for A193 - detail
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/tr/xhtml11/dtd/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<!-- Insert the following into your header -->
<script type="text/javascript" src="{ BASE DEPLOY URL}/standard/v2/js/fluid/retail/FluidRetailDisplay.js?baseUrl={BASE DEPLOY URL }"></script>
<script type="text/javascript">
var config =
{
// Define configuration parameters here
// noFlashImageUrl: "path to alternate image"
};
fluid.defineConfiguration("display:6:A193:detail ", config);
</script>
</head>
<body>
<!-- Copy all body code from here down -->
<div class="fluid-display" id="display:6:A193:detail" style="position: absolute; top: 0px; left: 0px; width: 280px; height: 380px;"></div>
<script type="text/javascript">fluid.application.processFluidDiv(document.getElementById("display:
6:A193:detail "));</script>
<div class="fluid-zoom" id="zoom:6:A193:detail" style="position: absolute; left: 280px; top:0px; width:278px; height: 278px;"></div>
<script type="text/javascript">fluid.application.processFluidDiv(docum
ent.getElementById("zoom:6:A193:detail"));</script>
<!-- Copy all body code from here up -->
</body>
</html>
NOTE: The example above includes embed code for an additional "fluid-zoom" component. This is only necessary for displays which use an external magnifier window. Click and pan zoom, internal magnifier, etc. will not require this code.
Header
The variable { BASE DEPLOY URL } should be replaced with the path from your HTML page to the location where you extracted the download displays - the customers and standard directories.
Example
If the customers and standard folders reside here:
- http://www.mysite.com/products/catalog/fluid/customers/
- http://www.mysite.com/products/catalog/fluid/standard/
and the HTML page resides here:
- http://www.mysite.com/products/product_detail.html
then your base URL would be replaced with:
"catalog/fluid/"
The config object can be used to set additional configuration parameters such as noFlashImageUrl and transparency mode. See Popular Display Parameters below.
Example:
<head>
<!-- Insert the following into your header -->
<script type="text/javascript" src="{ BASE DEPLOY URL}/standard/v2/js/fluid/retail/FluidRetailDisplay.js?baseUrl={BASE DEPLOY URL }"></script>
<script type="text/javascript">
var config =
{
// Define configuration parameters here
// noFlashImageUrl: "path to alternate image"
};
fluid.defineConfiguration("display:6:A193:detail ", config);
</script>
</head>
Body
The Fluid Display itself is embedding in the page using a simple DIV.
<div class="fluid-display" id="display:6:A193:detail" style="position: absolute; top: 0px; left: 0px; width: 280px; height: 380px;"></>
<script
type="text/javascript">fluid.application.processFluidDiv(document.getElementById("display:
6:A193:detail "));</script>
The "id" field is comprised of the following elements:
componentType:customerId:productId:displayId
componentType
ComponentType is set by the system and typically does not need to be modified.
customerId
CustomerId is set by the system and should not be changed unless you change Fluid Retail accounts.
productId
In most cases, you will want productId to be a dynamic field so that it is populated at runtime to display the correct product or style number.
displayId
The variable displayID should be replaced with the specific display name of the product display you want to appear. Remember, each product can have more than one display (i.e. "catalogview" or "detailview"). The display name can be viewed in the authoring environment, under the display tab.
The contents of the DIV are ignored by Fluid Retail by will continue to be crawled by search engines. Embed relevant content here to increase your natural search rankings.
Popular optional display parameters
The DIV method of embedding displays is clean and lightweight however the Presentation Manager supports setting optional parameters using JavaScript.
Example:
<script type="text/javascript">
var id = "display:6:A193:detail";
var config =
{
wmode: "transparent"
};
fluid.defineConfiguration(id, config);
</script>
The example above sets the wmode of the display to transparent. Here are some popular optional parameters:
noFlashImageUrl
Specify an image to be use in the event Flash is not present
<script type="text/javascript">
var id = "display:6:A193:detail";
var config =
{
noFlashImageUrl: "http://www.mysite.com/images/product.jpg"
};
fluid.defineConfiguration(id, config);
preloaderFgColor'/'preloaderFgColor
The parameters preloaderFgColor and preloaderBgColor allow you to specify the foreground and background colors of the preloader progress bar.
<script type="text/javascript">
var id = "display:6:A193:detail";
var config =
{
preloaderFgColor: "0x723E17",
preloaderBgColor: "0x723E17",
};
fluid.defineConfiguration(id, config);
</script>
extraVariables
The extraVariables parameter allows you to pass arbitrary into the Fluid Display to be rendered at runtime. This particularly helpful for volatile data such as price or promotional copy. During the template creation process, these variables can be rendered in the display as rich Flash text, text buttons or used to define image references. For example:
var extraVariables: "price=$12.99&image=splash.jpg&rating=5",
In this example, the template would use the "image" variable to place a splash image over the display with "price" laid over the top. The "rating" variable could be used to define an image to represent product rating. Ex: 5+"stars.jpg" might place a "5star.jpg" over the top of the display. Contact support@fluidretail.com for more details on how to use this powerful feature.
Some optional parameters, not shown above, can be used for configuring JavaScript based analytics integrations as well as controlling display loading behavior such as swatch or view ordering. See the next section entitled Communicating with displays via JavaScript for this information.
- NOTE: If you are adding Fluid Display to just a subset of your entire product catalog, you will should create two product detail page templates (one static HTML, one Fluid) and add logic to your product catalog so that your server knows which template to use for a given product.
- NOTE: Fluid Displays require Flash version 8 or greater. As of December, 2007, more than 98% of internet users have Flash 8 or greater. If Flash 8 is not present, Fluid Display will show a static version of the default product image without color change, magnification, etc. We recommend reviewing your site analytics to determine how many of your users fall into this category. If helpful, add a Flash detection script to your site which sends users with Flash 7 and below to your standard HTML product detail page.
Initialization of the Fluid Components
The Fluid Display and Merchandiser position in the code is controlled by placing <div> tags in the appropriate places. For example:
<div class="fluid-display" id="display:6:A193:detail" style="position: absolute; top: 0px; left: 0px; width: 280px; height: 380px;"></div>
During page loading these <div> tags get replaced by the actual components. The actual timing of the loading of the components can be controlled. There are three scenarios:
1. If the Fluid Retail javascript file (eg FluidRetailDisplay.js) is included before one or more <div> tags, then those <div> tags are processed when the page's "onload" event occurs.
2. If the Fluid Retail javascript file is included after one or more <div> tags then those tags are processed automatically at the point of inclusion.
3. <div> tags can be processed explicitly with a call to one of two commands. a) processFluidDivs() which loads the components on all preceding <div> tags.
b) processFluidDiv(divID) which replaces a specific <div>. For example:
<script type="text/javascript">fluid.application.processFluidDiv(document.getElementById("display:6:A193:detail "));</script>
Communicating with displays via JavaScript
A comprehensive list of JavaScript API's can be found in the Fluid Experience Reference Examples page.
Integration with JavaScript-Based Analytics
Logging within Fluid Display is turned on by enabling an event listener. Using it, you can track changes to any element of Fluid Display: load, variation change, view change, etc.
Example: http://test.fluidretail.net/pmr/examples/display_pmr_event.html
Integration with HTML
Fluid Displays can integrate seamlessly within an existing HTML web page. This can be in the form of the display updating elements of the HTML page (such as updating the state of an HTML select list) or by actions on HTML elements which update the Fluid Display (such as an HTML select list changing the color shown within a display).
Controlling Fluid Display from HTML
Changes to the state of a Fluid Display can be made by calling the built in JavaScript function named selectCategory( categoryGroupId, categoryId ). In order to change the state of the display this function is called by indicating what display category ("VARIATION", "VIEW" or "HOTSPOT") will be selected and passing in the "Inventory ID" set within the authoring environment.
For example, in a case where an HTML select list was changed to display the red version of a product, whose color code was ’BC423’, a call would be made to the Fluid Display according to the following: selectCategory("VARIATION", "BC423") and the display would change state appropriately.
Examples:
http://test.fluidretail.net/pmr/examples/display_pmr_api.html
function changeColor(id)
{
var pmr = fluid.application;
var display = pmr.getPresentation("display:6:A193:detail");
display.selectCategory("VARIATION", id);
}
Controlling HTML from Fluid Display
There are two methods for broadcasting events within a Display to JavaScript:
1) Adding "clickUrl" to view or variation thumbnail and assigning JavaScript function. Contact Fluid Retail support to add this to your template
2) Setting up an event listener. These events can then be sent to JavaScript function which interprets them and controls other HTML page elements.
Example:
http://test.fluidretail.net/pmr/examples/display_pmr_event.html
In the case of HTML color pull-downs within the page, your custom JavaScript should detect when there is a change in the variationId and pass this to other page elements.
In addition, a JavaScript event could be called each time a user clicks on a color or view swatch. Please contact support@fluidretail.net if you would like this added to your template.
Hiding, showing and ordering variation and view thumbnails at runtime
The number and order of views and variations within a display can be controlled by passing XML into a display. In addition, a default variation or view can be selected on display load. There are two ways this data can be passed into the display:
1. Passing a URL that will return an XML document to the display as an embed parameter in the form of displayControlXmlPath:’pathToXmlFile’
2. Passing a string, either as a literal string or as a JavaScript variable, through a displayControlXml value passed to the Display configuration
The syntax for XML to be passed into the display is the same whether it is being passed as a string or included in an XML file. A sample is below.
<display-control> <views order="sequential" active="VIEW2,VIEW1" default=”VIEW1”/> <variations order="random" active="VAR1,VAR2" default="VAR2"/> </display-control>
In the example above the "active" parameter indicates the Inventory IDs of the views that will be shown when the display is loaded. The "order" parameter has two allowable values, either "sequential" or "random". If the order is set to sequential the views or variations will be shown in the order specified in the comma separated list of the active parameter. If it is set to random the views or variations will randomly ordered. In addition, a default value can be set to determine the variation or view selected upon Display load.
Examples:
http://test.fluidretail.net/pmr/examples/display_pmr_displayControlXml.html
http://test.fluidretail.net/pmr/examples/display_pmr_displayXML_default.html
The JavaScript function below can be used to wrap a comma separated list of color values in the appropriate XML for use within Fluid:
function getDisplayControlXML(swatches)
{
xml = "<display-control>";
xml += "<variations active=\"";
xml += swatches;
xml += "\" order=\"sequential\" />";
xml += "</display-control>";
return xml;
}
swatches = “<<COMMA_SEPARATED_LIST_OF_COLORS_FOR_PRODUCT>>”;
displayControlXmlVal = getDisplayControlXML(swatches);
var id = "display:6:A193:detail";
var config = {displayControlXml: displayControlXmlVal};
fluid.defineConfiguration("display:6:A193:detail", config);
In the example above the colors that are currently available for the product will be passed in via the swatches JavaScript variable, wrapped in appropriate XML and then passed into the display. Only swatches passed in will be shown, regardless of how many swatches were included in the display in the Fluid Display authoring environment.
