Class ZMAGS.ui.Viewer

If you are experiencing a problem and need to troubleshoot, please send an e-mail to support@zmags.com.

Class Summary
Constructor Attributes	Constructor Name and Description
	ZMAGS.ui.Viewer() The viewer as it is represented in the page.

Field Summary
Field Attributes	Field Name and Description
<static> <constant>	ZMAGS.ui.Viewer.BUY_THE_LOOK_WIDGET_ACTIVATE Defines the event type 'buythelookwidgetactivate'.
<static> <constant>	ZMAGS.ui.Viewer.CURRENT_PAGES_CHANGE Defines the event type 'currentpageschange'.
<static> <constant>	ZMAGS.ui.Viewer.CURRENT_PUBLICATION_CHANGE Defines the event type 'currentpublicationchange'.
<static> <constant>	ZMAGS.ui.Viewer.CUSTOM_LINK_ACTIVATE Defines the event type 'customlinkactivate'.
<static> <constant>	ZMAGS.ui.Viewer.CUSTOM_LINK_CLICK Defines the event type 'customlinkclick'.
<static> <constant>	ZMAGS.ui.Viewer.CUSTOM_TOOLBAR_BUTTON_ACTIVATE Defines the event type 'customtoolbarbuttonactivate'.
<static> <constant>	ZMAGS.ui.Viewer.FACEBOOK_CONTEXT Facebook context.
<static> <constant>	ZMAGS.ui.Viewer.PRODUCT_ADD_TO_CART Defines the event type 'productaddtocart'.
<static> <constant>	ZMAGS.ui.Viewer.PRODUCT_LINK_ACTIVATE Defines the event type 'productlinkactivate'.
<static> <constant>	ZMAGS.ui.Viewer.PRODUCT_WIDGET_ACTIVATE Defines the event type 'productwidgetactivate'.
<static> <constant>	ZMAGS.ui.Viewer.PRODUCT_WINDOW_MESSAGE Defines the event type 'productwindowmessage'.
<static> <constant>	ZMAGS.ui.Viewer.PUBLICATION_CLOSE Defines the event type 'publicationclose'.
<static> <constant>	ZMAGS.ui.Viewer.PUBLICATION_LOAD Defines the event type 'publicationload'.
<static> <constant>	ZMAGS.ui.Viewer.PUBLICATION_OPEN Defines the event type 'publicationopen'.
<static> <constant>	ZMAGS.ui.Viewer.VERSION The current version of the API.

Method Summary
Method Attributes	Method Name and Description
	activateProduct(productID, publicationID) Searches for the specified product in the publication and triggers the onproductlinkactivate event without changing pages.
	addContext(context) Adds a context that the publication is viewed in.
	addEventListener(eventType, listener, scope) Registers an event listener function so that the listener receives notification of an event.
	addProduct(product, quantity) Adds a given quantity of a product to the viewer's wish list or shopping cart.
	atFirstPage(publicationID) Returns true if the viewer is at the first page of the specified publication.
	atLastPage(publicationID) Returns true if the viewer is at the last page of the specified publication.
	checkout() Initiates the checkout action in the viewer on the viewer's shopping cart.
	clearShoppingList() Removes all items from the viewer's wish list or shopping cart.
	closePublication(publicationID) Close the specified publication.
	dispatchEvent(event) Dispatches an event into the event flow.
	getCurrentPages(publicationID) Returns the current pages.
	getCurrentPublicationID() Returns the publication ID of the current publication in the viewer.
	getDisplayableCurrentPages(includeTotalPages, includePageText, publicationID) Returns a string representation of the current pages, using the page labels that are visible in the viewer.
	getNumberOfPages(publicationID) Returns the number of pages in a publication.
	getPageLabel(pageNumber, publicationID) Returns the page label for the specified page.
	getPageNumber(pageLabel, publicationID) Returns the page number for the specified page label.
	getPublicationTitle(publicationID) Returns the title of the publication.
	gotoFirstPages(publicationID) Goes to the first pages in the specified publication.
	gotoLastPages(publicationID) Goes to the last pages in the specified publication.
	gotoNextPages(publicationID) Goes to the next pages in the specified publication.
	gotoPage(pageNumber, publicationID) Goes to the specified page in the publication.
	gotoPreviousPages(publicationID) Goes to the previous pages in the current publication.
	gotoProduct(productID, pageNumber, publicationID) Goes to the page containing the specified product in the publication and triggers the onproductlinkactivate event.
	openPublication(publicationID) Opens the specified publication.
	registerProductAddedToSiteShoppingCart(product, quantity, productContext) Registers that a product has been added to the site shopping cart.
	registerProductDetailsViewed(product, productContext) Registers that the product details have been viewed.
	registerProductRemovedFromSiteShoppingCart(product, quantity, productContext) Registers that a product has been removed from the site shopping cart.
	registerSiteShoppingCartCheckedOut(cartItems) Registers that the site shopping cart has been checked out by a user.
	removeEventListener(eventType, listener, scope) Removes a listener from the Viewer object.
	removeProduct(product, quantity) Removes a given quantity of a product from the viewer's wish list or shopping cart.
	search(searchText) Opens the search dialog in the viewer with the specified query string.
	sendProductWindowMessage(message, target, correlationID) Sends a message to a product window.
	setHeight(value) Sets the height of the viewer in the page.
	setLocale(value) Sets the locale to use for the viewer.
	setParentElementID(value) Sets the element in which to insert the viewer.
	setPublicationID(value) Sets the publication ID to initially open in the viewer.
	setSharePublicationURL(customURL) Sets a custom 'share publication' URL.
	setWidth(value) Sets the width of the viewer in the page.
	setWindowMode(value) Sets the Window Mode property of the viewer for transparency, layering, and positioning in the browser.
	share(environment, customURL) Shares the publication on one of the social networks available.
	show() Shows the viewer in the HTML page.
	showArchiveDialog() Opens the archive dialog in the viewer.
	showPrintDialog() Opens the print dialog in the viewer.
	showTOCDialog() Opens the TOC dialog in the viewer.

Event Summary
Event Attributes	Event Name and Description
	onbuythelookwidgetactivate(event) Event handler function for the Buy The Look Widget Activate event.
	oncurrentpageschange(event) Event handler function for the Current Pages Changed event, the event is dispatched when the current pages have changed for an open publication.
	oncurrentpublicationchange(event) Event handler function for the Current Publication Changed event, the event is dispatched when the current publication has changed in the viewer.
	oncustomlinkactivate(event) Event handler function for the Custom Link Activate event.
	oncustomlinkclick(event) Event handler function for the Custom Link Clicked event, the event is dispatched when a custom link is clicked.
	oncustomtoolbarbuttonactivate(event) Event handler function for the Custom Toolbar Button Activate event.
	onproductaddtocart(event) Event handler function for the Product Add to Cart event.
	onproductlinkactivate(event) Event handler function for the Product Link Activate event.
	onproductwidgetactivate(event) Event handler function for the Product Widget Activate event.
	onproductwindowmessage(event) Event handler function for the Product Window Message event.
	onpublicationclose(event) Event handler function for the Publication Closed event, the event is dispatched when a publication has been closed.
	onpublicationload(event) Event handler function for the Publication Loaded event, the event is dispatched when a publication has been successfully loaded.
	onpublicationopen(event) Event handler function for the Publication Opened event, the event is dispatched when a publication has been opened.

Class Detail

ZMAGS.ui.Viewer()

The viewer as it is represented in the page.

To use the viewer, create a new viewer object, set the initial publication, and the ID of the element in which the viewer is inserted.

Author: zmags.com.


<html>
<head>
    <title>JavaScript API Test</title>
    <script src="http://viewer.zmags.com/js/viewer.js" type="text/javascript"></script>
</head>
<body>
<script>
    var viewer = new ZMAGS.ui.Viewer();
    viewer.setPublicationID("e90b813d");
    viewer.setParentElementID("myViewerContent");
    viewer.show();
</script>

<div id="myViewerContent" style="width:800px; height:600px;"></div>
</body>
</html>

Field Detail

<static> <constant> {String} ZMAGS.ui.Viewer.BUY_THE_LOOK_WIDGET_ACTIVATE

Defines the event type 'buythelookwidgetactivate'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.CURRENT_PAGES_CHANGE

Defines the event type 'currentpageschange'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.CURRENT_PUBLICATION_CHANGE

Defines the event type 'currentpublicationchange'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.CUSTOM_LINK_ACTIVATE

Defines the event type 'customlinkactivate'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.CUSTOM_LINK_CLICK

Defines the event type 'customlinkclick'.

Deprecated:
Use CUSTOM_LINK_ACTIVATE. This event is provided for backwards compatibility only.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.CUSTOM_TOOLBAR_BUTTON_ACTIVATE

Defines the event type 'customtoolbarbuttonactivate'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.FACEBOOK_CONTEXT

Facebook context.

Indicates that the user is viewing the publication in the context of Facebook, like when the publication is viewed in a Facebook app.

See:: ZMAGS.ui.Viewer#addContext

<static> <constant> {String} ZMAGS.ui.Viewer.PRODUCT_ADD_TO_CART

Defines the event type 'productaddtocart'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PRODUCT_LINK_ACTIVATE

Defines the event type 'productlinkactivate'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PRODUCT_WIDGET_ACTIVATE

Defines the event type 'productwidgetactivate'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PRODUCT_WINDOW_MESSAGE

Defines the event type 'productwindowmessage'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PUBLICATION_CLOSE

Defines the event type 'publicationclose'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PUBLICATION_LOAD

Defines the event type 'publicationload'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> {String} ZMAGS.ui.Viewer.PUBLICATION_OPEN

Defines the event type 'publicationopen'.

See:: ZMAGS.ui.Viewer#addEventListener

<static> <constant> ZMAGS.ui.Viewer.VERSION

The current version of the API.

Method Detail

activateProduct(productID, publicationID)

Searches for the specified product in the publication and triggers the onproductlinkactivate event without changing pages.

If the viewer is currently locked, this function does nothing.

If the product is not found, this function does nothing.

Parameters:
{String} productID: The ID of the product to activate.
{String} publicationID: The ID of the publication. This is an optional parameter. If unspecified, the current publication is assumed.

addContext(context)

Adds a context that the publication is viewed in.

It is possible to have more than one context. The set of all specified contexts is used to determine how the publication is presented, and how statistics are collected.

Some contexts may be mutually exclusive (e.g. a context that specifies the publication is accessed from Facebook and a context that specifies it is accessed from Google+). If that is the case, it is described on the context constant.

Parameters:
{String} context: A context that the publication is viewed in, as a *_CONTEXT constant.

{Function} addEventListener(eventType, listener, scope)

Registers an event listener function so that the listener receives notification of an event.


var viewer = new ZMAGS.ui.Viewer();
viewer.addEventListener(ZMAGS.ui.Viewer.CURRENT_PAGES_CHANGE, currentPagesChangedHandler);
     
function currentPagesChangedHandler(event) {
    alert("currentPagesChangedHandler, event type: " + event.type);
}

Parameters:
{String} eventType: Type the type of event.
{Function} listener: The listener function that handles the event.
{Object} scope: The object scope, optional.

addProduct(product, quantity)

Adds a given quantity of a product to the viewer's wish list or shopping cart.

The product is given as a product object, which has the following parameters:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).
price - {double} - The price of the product. (required, must be non-negative).
description - {String} - A description of the product (optional).

Customers using the product database may provide product objects using the product database property identifiers instead of the API identifiers listed above. The API identifiers map to the following default product database property identifiers:

productID - product_id
productName - name
price - discount_price, or price if no discount price is specified
description - short_description, or description if no short description is specified

These may differ from the actual product database identifiers if they have been renamed.

When adding a product, the viewer will first attempt to find an existing product in the list matching the given product. If a match is found, the quantity will be added to the existing item. Otherwise, a new product is added with the specified quantity.

If the product identifier is specified, the matcher will only take it into consideration. If the product identifier is not specified, the matcher will attempt to find an item with no identifier specified and a matching name.

If any required parameters are missing or can't be parsed correctly, no changes are made and no errors will be generated.

Parameters:
product: The product object (required).
quantity: The number of units of the product to add to the list (required). Must be positive.

{Boolean} atFirstPage(publicationID)

Returns true if the viewer is at the first page of the specified publication.

Parameters:
{String} publicationID: publicationID the publiication to check whether we are at the first page for. This is an optional parameter. If it is left out, the current publication is assumed.

Returns:: {Boolean} true if the viewer is at the first page, false if not.

{Boolean} atLastPage(publicationID)

Returns true if the viewer is at the last page of the specified publication.

Parameters:
{String} publicationID: publicationID the publiication to check whether we are at the last page for. This is an optional parameter. If it is left out, the current publication is assumed.

Returns:: {Boolean} true if the viewer is at the last page, false if not.

checkout()

Initiates the checkout action in the viewer on the viewer's shopping cart.

If the viewer does not have a shopping cart enabled, or the shopping cart is empty, no action will be taken and no errors will be generated.

clearShoppingList()

Removes all items from the viewer's wish list or shopping cart.

If the viewer does not have a wish list or shopping cart enabled, no action will be taken and no errors will be generated.

closePublication(publicationID)

Close the specified publication.

Parameters:
{String} publicationID: The ID of the publication to close.

{Function} dispatchEvent(event)

Dispatches an event into the event flow.

Parameters:
{Object} event: The event object to dispatch.

{Object} getCurrentPages(publicationID)

Returns the current pages.


<script>
    var viewer = new ZMAGS.ui.Viewer();
    viewer.setPublicationID("e90b813d");
    viewer.setParentElementID("myViewerContent");
    viewer.addEventListener(ZMAGS.ui.Viewer.PUBLICATION_LOAD, publicationLoadedHandler);
    viewer.show();

    function publicationLoadedHandler(event) {
        var pageRange = viewer.getCurrentPages();
        alert("firstPage: " + pageRange.firstPage + " - lastPage: " + pageRange.lastPage);
    }
</script>

<div id="myViewerContent" style="width:100%; height:600px;"></div>

Parameters:
{String} publicationID: The ID of the publication to get current pages for. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:

{Object}

The current pages, as an object with two properties:

firstPage: The first page in the range.
lastPage: The last page in the range.

{String} getCurrentPublicationID()

Returns the publication ID of the current publication in the viewer.

Returns:: {String} The current publication ID as a obfuscated string.

{String} getDisplayableCurrentPages(includeTotalPages, includePageText, publicationID)

Returns a string representation of the current pages, using the page labels that are visible in the viewer.

Parameters:
{Boolean} includeTotalPages: Whether to include the total number of pages, e.g. "5-6 / 21".
{Boolean} includePageText: Whether to include a localized version of the page.
{String} publicationID: The ID of the publication to get current pages for. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:: {String} A string representation of the current pages.

{String} getNumberOfPages(publicationID)

Returns the number of pages in a publication.

Parameters:
{String} publicationID: The ID of the publication to get the number of pages for. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:: {String} The number of pages in a publication.

{String} getPageLabel(pageNumber, publicationID)

Returns the page label for the specified page.

Parameters:
{Number} pageNumber: The page to get a page label for.
{String} publicationID: The ID of the publicationthe page belongs to. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:: {String} The page label for the specified page.

{Number} getPageNumber(pageLabel, publicationID)

Returns the page number for the specified page label.

Parameters:
{String} pageLabel: The page label to get the corresponding page label for.
{String} publicationID: The ID of the publicationthe page belongs to. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:: {Number} The page number for the specified page label

{String} getPublicationTitle(publicationID)

Returns the title of the publication.

Parameters:
{String} publicationID: The ID of the publication to get the title for. This is an optional parameter. If unspecified, the current publication is assumed.

Returns:: {String} The title of the publication.

gotoFirstPages(publicationID)

Goes to the first pages in the specified publication.

If the viewer is locked or there is no first page, this function does nothing.

Parameters:
{String} publicationID: The ID publication. This is an optional parameter. If unspecified, the current publication is assumed.

gotoLastPages(publicationID)

Goes to the last pages in the specified publication.

If the viewer is locked or there is no first page, this function does nothing.

Parameters:
{String} publicationID: The ID publication. This is an optional parameter. If unspecified, the current publication is assumed.

gotoNextPages(publicationID)

Goes to the next pages in the specified publication. The next pages is not necessarily the pages that were just shown, but the pages just after the current one.

If the viewer is locked or the viewer is already showing the last page, this function does nothing.

Parameters:
{String} publicationID: The ID publication. This is an optional parameter. If unspecified, the current publication is assumed.

gotoPage(pageNumber, publicationID)

Goes to the specified page in the publication.

If the page does not exist, or the viewer is currently locked, this function does nothing.

Parameters:
{Number} pageNumber: The page to go to.
{String} publicationID: The ID publication. This is an optional parameter. If unspecified, the current publication is assumed.

gotoPreviousPages(publicationID)

Goes to the previous pages in the current publication. The previous pages is not necessarily the pages that were just shown, but the pages just before the current one.

If the viewer is locked or the viewer is already showing the first page, this function does nothing.

Parameters:
{String} publicationID: The ID of the publication to close.

gotoProduct(productID, pageNumber, publicationID)

Goes to the page containing the specified product in the publication and triggers the onproductlinkactivate event. Other viewer events may also be triggered (for example, oncurrentpageschange).

If the viewer is currently locked, this function does nothing.

If the product is not found and no page number is specified, this function does nothing.

If the product is not found and a page number is specified, the viewer will go to the specified page, but the onproductlinkactivate event will not be fired.

If the page is specified but does not exist, this function does nothing, regardless of whether the product exists.

Parameters:
{String} productID: The ID of the product to go to.
{Number} pageNumber: The page the product is located on. This is an optional parameter. If unspecified, the page number will be looked up.
{String} publicationID: The ID of the publication. This is an optional parameter. If unspecified, the current publication is assumed.

openPublication(publicationID)

Opens the specified publication.

Parameters:
{String} publicationID: The ID of the publication to close.

registerProductAddedToSiteShoppingCart(product, quantity, productContext)

Registers that a product has been added to the site shopping cart. This data is used to generate the Product Performance statistics in the Zmags Publicator.

The function takes three parameters. The first, product, is an object that describes the product. The second, quantity, is the number of units of the product that have been added. The third, productContext, is an optional object describing the context in which the product appears in the publication.

The product object contains the following properties:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.

productID - product_id
productName - name
price - discount_price, or price if no discount price is specified

These may differ from the actual product database identifiers if they have been renamed.

The product identifier and product name properties are limited to 255 characters. Longer strings will be truncated to this length.

The productContext object contains the following properties:

type - {ZMAGS.ui.Viewer.ProductContextType} - The type of context that the event is triggered in.
buyTheLookID - {String} - The string identifier of the Buy the Look widget the product is a part of. Only applicable if the type is ZMAGS.ui.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Parameters:
{Object} product: The product object (required).
{int} quantity: The number of products added (required). Must be positive.
{Object} productContext Optional: Optional context of the product and event being registered.

See:: ZMAGS.ui.Viewer.ProductContextType

registerProductDetailsViewed(product, productContext)

Registers that the product details have been viewed. This data is used to generate the Product Performance statistics in the Zmags Publicator.

The function takes two parameters. The first, product, is an object that describes the product. The second, productContext, is an optional object describing the context in which the product appears in the publication.

The product object contains the following properties:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).

productID - product_id
productName - name

These may differ from the actual product database identifiers if they have been renamed.

The product identifier and product name properties are limited to 255 characters. Longer strings will be truncated to this length.

The productContext object contains the following properties:

type - {ZMAGS.ui.Viewer.ProductContextType} - The type of context that the event is triggered in.
buyTheLookID - {String} - The string identifier of the Buy the Look widget the product is a part of. Only applicable if the type is ZMAGS.ui.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Parameters:
{Object} product: The product object.
{Object} productContext Optional: Optional context of the product and event being registered.

See:: ZMAGS.ui.Viewer.ProductContextType

registerProductRemovedFromSiteShoppingCart(product, quantity, productContext)

Registers that a product has been removed from the site shopping cart. This data is used to generate the Product Performance statistics in the Zmags Publicator.

The function takes three parameters. The first, product, is an object that describes the product. The second, quantity, is the number of units of the product that have been removed. The third, productContext, is an optional object describing the context in which the product appears in the publication.

The product object contains the following properties:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.

productID - product_id
productName - name
price - discount_price, or price if no discount price is specified

These may differ from the actual product database identifiers if they have been renamed.

The product identifier and product name properties are limited to 255 characters. Longer strings will be truncated to this length.

The productContext object contains the following properties:

type - {ZMAGS.ui.Viewer.ProductContextType} - The type of context that the event is triggered in.
buyTheLookID - {String} - The string identifier of the Buy the Look widget the product is a part of. Only applicable if the type is ZMAGS.ui.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Parameters:
{Object} product: The product object (required).
{int} quantity: The number of products removed (required). Must be positive.
{Object} productContext Optional: Optional context of the product and event being registered.

See:: ZMAGS.ui.Viewer.ProductContextType

registerSiteShoppingCartCheckedOut(cartItems)

Registers that the site shopping cart has been checked out by a user. This data is used to generate the Product Performance statistics in the Zmags Publicator.

The function takes one parameter, cartItems, which is an array of cart item objects. A cart item object is defined by the following properties:

product - {Object} - The product object (required).
quantity - {int} - The number of units (required). Must be positive.
productContext - {Object} - Object describing the context of the product in the publication (optional).

The product object contains the following properties:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.

productID - product_id
productName - name
price - discount_price, or price if no discount price is specified

These may differ from the actual product database identifiers if they have been renamed.

The product identifier and product name properties are limited to 255 characters. Longer strings will be truncated to this length.

The productContext object contains the following properties:

type - {ZMAGS.ui.Viewer.ProductContextType} - The type of context that the event is triggered in.
buyTheLookID - {String} - The string identifier of the Buy the Look widget the product is a part of. Only applicable if the type is ZMAGS.ui.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Parameters:
{Object[]} cartItems: The array of cart item objects representing the products in the checked out cart.

See:: ZMAGS.ui.Viewer.ProductContextType

{Function} removeEventListener(eventType, listener, scope)

Removes a listener from the Viewer object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:
{String} eventType: Type the type of event.
{Function} listener: The listener function that handles the event.
{Object} scope: The object scope, optional.

removeProduct(product, quantity)

Removes a given quantity of a product from the viewer's wish list or shopping cart.

The product is given as a product object, which has the following parameters:

productID - {String} - The unique product identifier (required if productName is unspecified).
productName - {String} - The product name (required if productID is unspecified).

productID - product_id
productName - name

These may differ from the actual product database identifiers if they have been renamed.

If the quantity is not specified or is 0, all items of the product are removed from the list.

If no product can be found, or the product cannot be reduced by the given quantity, no changes are made and no errors will be generated.

Parameters:
{Object} product: The product to remove (required).
quantity: The number of units of the product to remove from the list (optional, must be positive if specified).

search(searchText)

Opens the search dialog in the viewer with the specified query string.

Parameters:
{String} searchText: The text to search for.

sendProductWindowMessage(message, target, correlationID)

Sends a message to a product window.

Messages are delivered to any active product windows that have registered an event listener. This feature is only available in Commerce viewers.

Parameters:
{String} message: The message to send (required). Limited to 1000 characters.
{String} target: Optional user-specified string that can be used by listeners to filter messages from a single source. Limited to 64 characters.
{String} correlationID: Optional user-specified string that can be used to correlate messages. Limited to 64 characters.

setHeight(value)

Sets the height of the viewer in the page.

If not specified, the height of the viewer adapts to the available space on the page.

Parameters:
{Object} value: The height, in pixels, or as a percentage.

setLocale(value)

Sets the locale to use for the viewer.

The locale affects which language is used to present messages to the user, and how dates and numbers are formatted.

If unspecified, the viewer tries to detect a locale from the browser settings.

Parameters:
{String} value: The locale to use for the viewer, e.g. en_US for the English (American) locale.

setParentElementID(value)

Sets the element in which to insert the viewer.

When the show() function is called, the Flash object is loaded and when it completes loading, it replaces the content of the parent element with the object.

Parameters:
{String} value: The ID of the element in which to insert the viewer.

{Function} setPublicationID(value)

Sets the publication ID to initially open in the viewer.

Parameters:
{String} value: The ID of the publication to open initially in the viewer.

setSharePublicationURL(customURL)

Sets a custom 'share publication' URL.

When a visitor shares the publication on a social network, the URL to the publication (i.e. http://viewer.zmags.com/publication/...) is used by default. Use this method to set up a custom URL that is shared instead, such as the URL of the page that is embedding the publication.

Parameters:
{String} customURL: the custom 'share publication' URL

setWidth(value)

Sets the width of the viewer in the page.

If not specified, the width of the viewer adapts to the available space on the page.

Parameters:
{Object} value: The width, in pixels, or as a percentage.

setWindowMode(value)

Sets the Window Mode property of the viewer for transparency, layering, and positioning in the browser.

window - viewer plays in its own rectangular window on a web page.
opaque - the viewer hides everything on the page behind it.
transparent - the background of the HTML page shows through all transparent portions of the viewer, this may slow animation performance.

Parameters:
{String} value: The window mode, possible values: "window", "opaque", "transparent".

share(environment, customURL)

Shares the publication on one of the social networks available.

For the moment the publication can only be shared on Facebook.

Parameters:

{String} environment

Enumeration of

facebook

The social network to share the publication or the customURL on. This enumeration might be extended in the future to support other environments. This is an optional parameter. If unspecified, the facebook environment is assumed.

{String} customURL

The custom 'share publication' URL. This is an optional parameter. If unspecified, the publicationURL is assumed. If the customURL is an invalid URL the publicationURL is assumed.

{Function} show()

Shows the viewer in the HTML page.

The viewer must first have had its parent element ID and its publication ID set.

See:: ZMAGS.ui.Viewer#setPublicationID; ZMAGS.ui.Viewer#setParentElementID

showArchiveDialog()

Opens the archive dialog in the viewer.

showPrintDialog()

Opens the print dialog in the viewer.

showTOCDialog()

Opens the TOC dialog in the viewer.

Event Detail

{Function} onbuythelookwidgetactivate(event)

Event handler function for the Buy The Look Widget Activate event. The event is dispatched when a buy the look widget is activated by the user, e.g. when it is clicked, in a viewer where a click on a buy the look widget is configured to trigger a JavaScript event.

This event will only be dispatched from Commerce viewers.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "buythelookwidgetactivate".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
title: The optional title of the widget.
description: The optional description of the widget.
statisticsID: The ID used when tracking statistics related to the widget.
mediaSource: The absolute URL pointing to the associated media resource, e.g. an image. Might be null.
products: An array of the product objects and related properties (explained below).

The products property is an array of objects with the following properties:

product: The product object
initiallySelectedProduct: The default variant leaf product.
variants: The product's leaf variants.
variantPropertyValues: An object containing ordered values of variant properties.
defaultIdentifiers: Object with a map of identifier to default identifier.

The product object contains all of the product properties defined during the import of product data to the Zmags Publicator, with matching property names and data types. Look up properties directly on the product object using the property name, i.e. product.product_id.

The event object contains the initiallySelectedProduct object, containing the product properties for the default product. The initiallySelectedProduct is the product identified by the standard product property "Default Product", with the following exceptions:

If no "Default Product" has been set, the initiallySelectedProduct is the first leaf variant.
If the product has no enabled leaf variants, it becomes its own initiallySelectedProduct.
If the selected "Default Product" isn't a leaf variant of the product, it is considered invalid, and the first (according to lexicographical sorting by product id), enabled leaf variant becomes the product's initiallySelectedProduct.

The variants property is an array of product objects containing all of the product's leaf variants. Leaf variants are variants of the product that do not have any variants of their own, and therefore represent a sellable product. Intermediate variants are not included. The variants are sorted lexicographically by their product ids. The variant product objects do not contain a default product object.

The variantPropertyValues object describes how a property with non-standard ordering should be ordered when the values are combined across multiple product variants. A good example of this is clothing sizes, like small, medium, and large. They cannot be ordered by traditional sorting functions, so the ordering of all values used by the product's variants is provided through the variantPropertyValues object. The values are stored as an array keyed by the property name. An example variantPropertyValues object:

variantPropertyValues: {"size": ["small","medium","large","extra large"]}

The defaultIdentifiers object contains a map of identifier to default identifier. If there is no default identifier available for an identifier (e.g. it is a custom property), then the identifier will map to null. Note also that only properties that are present in the products for the current event are listed.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} oncurrentpageschange(event)

Event handler function for the Current Pages Changed event, the event is dispatched when the current pages have changed for an open publication.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "currentpageschange".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.
pages: The new page range. This object has two properties:
1) firstPage: The first page in the range.

2) lastPage: The last page in the range.


<script>
    var viewer = new ZMAGS.ui.Viewer();
    viewer.setPublicationID("e90b813d");
    viewer.setParentElementID("myViewerContent");
    viewer.show();

    viewer.oncurrentpageschange = function(event) {
        alert("Current page number is " + event.firstPage + " - last page number is " + event.lastPage);
    }

</script>

<div id="myViewerContent" style="width:100%; height:600px;"></div>

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} oncurrentpublicationchange(event)

Event handler function for the Current Publication Changed event, the event is dispatched when the current publication has changed in the viewer.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "currentpublicationchange".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} oncustomlinkactivate(event)

Event handler function for the Custom Link Activate event. The event is dispatched when a custom link is activated by the user, e.g. when it is clicked.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "customlinkactivate".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.
data: Custom data specified by the user.
pageNumber: The number of the page that was clicked.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} oncustomlinkclick(event)

Event handler function for the Custom Link Clicked event, the event is dispatched when a custom link is clicked.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "customlinkclick".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.
data: Custom data specified by the user.
pageNumber: The number of the page that was clicked.

Parameters:
{Object} event: The event object.

Deprecated:
Use oncustomlinkactivate instead. This event handler is provided for backwards compatibility only.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} oncustomtoolbarbuttonactivate(event)

Event handler function for the Custom Toolbar Button Activate event. This event is dispatched when a toolbar button is activated, for example when it is clicked.

This event will only be dispatched from Commerce viewers.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "customtoolbarbuttonactivate".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, 1970.
buttonID: The ID of the activated button.

The following lists the default button ids:

home: The Home button.
toc: The TOC button.
search: The Search button.
share: The expanded Share button.
facebook-share: The Facebook Share button.
download-pdf: The Download PDF button.
checkout: The Checkout button.
fullscreen: The Fullscreen button.
print: The Print button.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onproductaddtocart(event)

Event handler function for the Product Add to Cart event. The event is dispatched when a product should be added to an external shopping cart.

This event will only be dispatched from Commerce viewers.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "productaddtocart".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, 1970.
product: The product object.
quantity: The number of items to add to cart.
defaultIdentifiers: Object with a map of identifier to default identifier.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onproductlinkactivate(event)

Event handler function for the Product Link Activate event. The event is dispatched when a product link is activated by the user, e.g. when it is clicked.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "productlinkactivate".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, 1970.
linkID: The ID of the product link used to activate the product.
product: The product object.
defaultProduct: The default variant leaf product.
variants: The product's leaf variants.
variantPropertyValues: An object containing ordered values of variant properties.
defaultIdentifiers: Object with a map of identifier to default identifier.
mousePosition: A point object containing the mouse click position relative to the div containing the Zmags viewer.
linkBounds: A rectangle object representing the bounds of the link relative to the div containing the Zmags viewer.

The mouse position is given as a point object, containing the following properties:

x: The x position of the mouse relative to the div containing the Zmags viewer.
y: The y position of the mouse relative to the div containing the Zmags viewer.

The mouse position will be set to null if the product link was not activated by a mouse click.

The link bounding rectangle is given as a rectangle object, containing the following properties:

x: The x position of the left of the rectangle relative to the div containing the Zmags viewer.
y: The y position of the top of the rectangle relative to the div containing the Zmags viewer.
width: The width of the rectangle.
height: The height of the rectangle.

The link bounding rectangle will be set to null if the product link was not activated by a mouse click.

Products created using the product database:

The event object contains a defaultProduct object, containing the product properties for the default product. The default product is the product identified by the standard product property "Default Product", with the following exceptions:

If no "Default Product" has been set, the default product is the first leaf variant.
If the product has no enabled leaf variants, it becomes its own default product.
If the selected "Default Product" isn't a leaf variant of the product, it is considered invalid, and the first (according to lexicographical sorting by product id), enabled leaf variant becomes the product's default product.

variantPropertyValues: {"size": ["small","medium","large","extra large"]}

Products created manually:

The product object contains all of the product properties defined during the creation of the product link (i.e. product id, product name, product description and product price). The properties will be added to the object with the following identifiers:

productID
productName
description
price

The event object contains a defaultProduct object that is the same as the product object.

The variants property array will be empty when the activated product is a manual product as the functionality does not apply for manual products.

The variantPropertyValues object is empty when the activated product is a manual product as the functionality does not apply for manual products.

The defaultIdentifiers object contains a map of identifier to default identifier.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onproductwidgetactivate(event)

Event handler function for the Product Widget Activate event. The event is dispatched when a product widget is activated by the user, e.g. when it is clicked, in a viewer where a click on a product widget is configured to trigger a JavaScript event.

This event will only be dispatched from Commerce viewers.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "productwidgetactivate".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
products: An array of the product objects and related properties (explained below).
buttonBounds: A rectangle object representing the bounds of the product widget button relative to the div containing the Zmags viewer.

The button bounding rectangle is given as a rectangle object, containing the following properties:

x: The x position of the left of the rectangle relative to the div containing the Zmags viewer.
y: The y position of the top of the rectangle relative to the div containing the Zmags viewer.
width: The width of the rectangle.
height: The height of the rectangle.

The products property is an array of objects with the following properties:

product: The product object
initiallySelectedProduct: The default variant leaf product.
variants: The product's leaf variants.
variantPropertyValues: An object containing ordered values of variant properties.
defaultIdentifiers: Object with a map of identifier to default identifier.

If no "Default Product" has been set, the initiallySelectedProduct is the first leaf variant.
If the product has no enabled leaf variants, it becomes its own initiallySelectedProduct.
If the selected "Default Product" isn't a leaf variant of the product, it is considered invalid, and the first (according to lexicographical sorting by product id), enabled leaf variant becomes the product's initiallySelectedProduct.

variantPropertyValues: {"size": ["small","medium","large","extra large"]}

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onproductwindowmessage(event)

Event handler function for the Product Window Message event. The event is dispatched when a product window sends a message.

This event will only be dispatched from Commerce viewers.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "productwindowmessage".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, 1970.
message: The string message. Limited to 1000 characters.
messageTarget: Optional. User-specified string that can be used by listeners to filter messages from a single source. Limited to 64 characters.
correlationID: Optional. User-specified string that can be used to correlate messages. Limited to 64 characters.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onpublicationclose(event)

Event handler function for the Publication Closed event, the event is dispatched when a publication has been closed.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "publicationclose".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onpublicationload(event)

Event handler function for the Publication Loaded event, the event is dispatched when a publication has been successfully loaded.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "publicationload".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

{Function} onpublicationopen(event)

Event handler function for the Publication Opened event, the event is dispatched when a publication has been opened.

The event handler function takes one argument, the event object, which contains the following properties:

type: The type of the event. This string is hardcoded to "publicationopen".
target: A reference to the Viewer object that generated the event.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, December 1970.
publicationID: The ID of the publication whose current pages has changed.

Parameters:
{Object} event: The event object.

See:: ZMAGS.ui.Viewer#addEventListener

Classes

Class ZMAGS.ui.Viewer