Class com.zmags.api.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
	com.zmags.api.Viewer() The Viewer API for initializing and communicating with a viewer.

Field Summary
Field Attributes	Field Name and Description
<static> <constant>	com.zmags.api.Viewer.BUY_THE_LOOK_WIDGET_ACTIVATE Defines the "Buy The Look Widget Activate" event.
<static> <constant>	com.zmags.api.Viewer.CURRENT_PAGES_CHANGE Defines the "Current Pages Change" event.
<static> <constant>	com.zmags.api.Viewer.CUSTOM_LINK_ACTIVATE Defines the "Custom Link Activate" event.
<static> <constant>	com.zmags.api.Viewer.LIGHTBOX_LINK_ACTIVATE Defines the "Lightbox link Activate" event.
<static> <constant>	com.zmags.api.Viewer.PRODUCT_LINK_ACTIVATE Defines the "Product Link Activate" event.
<static> <constant>	com.zmags.api.Viewer.PRODUCT_WIDGET_ACTIVATE Defines the "Product Widget Activate" event.
<static> <constant>	com.zmags.api.Viewer.TOOLBAR_BUTTON_ACTIVATE Defines the "Toolbar Button Activate" event.
<static> <constant>	com.zmags.api.Viewer.VIEWER_LOADED Defines the "Viewer Loaded" event.

Function Summary
Function Attributes	Function Name and Description
	activateProduct(product) Searches for the first occurrence of the specified product in the publication and triggers the appropriate product activation event (onproductlinkactivate or onproductwidgetactivate).
	addContext(context, contextData) 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.
	atFirstPage(callback, scope) Queries the viewer as to whether it is currently showing the first page of the publication.
	atLastPage(callback, scope) Queries the viewer as to whether it is currently showing the last page of the publication.
	downloadPDF() Invokes the download PDF functionality.
	getCurrentPages(callback, scope) Queries the viewer as to what pages are currently showing in the publication.
	getNumberOfPages(callback, scope) Queries the viewer as to the number of pages in the publication.
	getPublicationID(callback, scope) Queries the viewer as to the ID of the publication it is currently showing.
	getPublicationTitle(callback, scope) Queries the viewer for the title of the publication.
	gotoFirstPages() Goes to the first page range in the publication.
	gotoLastPages() Goes to the last page range in the publication.
	gotoNextPages() Goes to the page range immediately after the currently-displayed page range in the publication.
	gotoPage(pageNumber) Goes to the specified page in the publication.
	gotoPreviousPages() Goes to the page range immediately before the currently-displayed page range in the publication.
	gotoProduct(product, pageNumber) Goes to the page containing the specified product in the publication and triggers the appropriate product activation event (onproductlinkactivate or onproductwidgetactivate).
	openLightbox(url) Opens a lightbox to the given URL.
	print() Invokes the print functionality.
	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 an event listener function previously registered through a call to addEventListener.
	resize() Signals the viewer to resize itself to match its container's dimensions.
	search() Triggers the search function in the viewer.
	setFullscreenMode(fullscreenMode) Sets the fullscreen mode for the viewer to use.
	setLocale(locale) Sets the locale to use in the viewer.
	setParentElementID(parentElementID) Sets the ID of the element where the viewer is placed as a child in the DOM.
	setPublicationID(publicationID) Sets the ID of the publication to view.
	setScheduleID(scheduleID) Sets the ID of the schedule to view.
	setSharePublicationURL(sharePublicationURL) Sets a custom 'share publication' URL.
	show() Displays 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.
	oncustomlinkactivate(event) Event handler function for the Custom Link Activate event.
	onproductlinkactivate(event) Event handler function for the Product Link Activate event.
	onproductwidgetactivate(event) Event handler function for the Product Widget Activate event.
	ontoolbarbuttonactivate(event) Event handler function for the Toolbar Button Activate event.
	onviewerloaded(event) Event handler function for the Viewer Loaded event.

Class Detail

com.zmags.api.Viewer()

The Viewer API for initializing and communicating with a viewer.

It is responsible for selecting viewer and delegating initialization to the specific viewer.

On compatibility: The viewer API may be extended with further functions in the future, and the functions in the API may be extended with additional parameters. These parameters will be optional to avoid breaking backwards compatibility. Because new parameters may be added with as-yet-undefined meaning, it is recommended that you avoid providing additional undefined parameters to the functions in the API, as the meaning may change when the API is updated.

To use the Viewer API, the minimal required steps are, in order:

Load the viewer script from http://api.viewer.zmags.com/viewer/viewer.js.
Instantiate a viewer by calling the constructor.
Set a publication ID or schedule ID by calling either setScheduleID() or setPublicationID().
Set the parent element that the viewer should be shown in by calling setParentElementID().
Call show().

Author: Zmags.

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>JavaScript API Test</title>
    <script src="http://api.viewer.zmags.com/viewer/viewer.js" type="text/javascript"></script>
</head>
<body>
<div id="myViewerContent" style="width:800px; height:600px;"></div>

<script type="text/javascript">
    var viewer = new com.zmags.api.Viewer();
    viewer.setPublicationID("e90b813d");
    viewer.setParentElementID("myViewerContent");
    viewer.show();
</script>
</body>
</html>

Field Detail

<static> <constant> com.zmags.api.Viewer.BUY_THE_LOOK_WIDGET_ACTIVATE

Defines the "Buy The Look Widget Activate" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.CURRENT_PAGES_CHANGE

Defines the "Current Pages Change" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.CUSTOM_LINK_ACTIVATE

Defines the "Custom Link Activate" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.LIGHTBOX_LINK_ACTIVATE

Defines the "Lightbox link Activate" event.

Warning: If you implement an event handler for this event, it should not stop its default propagation.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.PRODUCT_LINK_ACTIVATE

Defines the "Product Link Activate" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.PRODUCT_WIDGET_ACTIVATE

Defines the "Product Widget Activate" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.TOOLBAR_BUTTON_ACTIVATE

Defines the "Toolbar Button Activate" event.

See:: com.zmags.api.Viewer#addEventListener

<static> <constant> com.zmags.api.Viewer.VIEWER_LOADED

Defines the "Viewer Loaded" event.

See:: com.zmags.api.Viewer#addEventListener

Function Detail

activateProduct(product)

Searches for the first occurrence of the specified product in the publication and triggers the appropriate product activation event (onproductlinkactivate or onproductwidgetactivate).

The product may be specified in one of two ways:

As a product ID (String)
As a product object previously returned by the API (see onproductlinkactivate, onproductwidgetactivate, etc.)

If the viewer is currently locked or the product is not found, this function does nothing.

Parameters:
{String|Object} product: The product, either as a string (the product ID) or a product object previously returned by the API.

Throws:
{String}: If the product is invalid.

addContext(context, contextData)

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.

Supported contexts are defined on com.zmags.api.Viewer.Context.

Contexts must be defined prior to calling show() to load the viewer. Calling this function later has no effect.

Parameters:
{String} context: The context to add.
{Object} contextData Optional: Optional contextData of the context being added.

Throws:
{String}: If an unsupported context is passed or if the function is called after show() has been called.

See:: com.zmags.api.Viewer.Context

addEventListener(eventType, listener, scope)

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

The listener function should accept one parameter, the event.

The properties available on the various event types are documented on the event function, see under Event Detail. In addition to the event-specific properties, each event will comply with the DOM Level 2 event interface, by defining the following properties:

The PhaseType constants: CAPTURING_PHASE (1), AT_TARGET (2), and BUBBLING_PHASE (3).
type: String describing the event type.
target: A reference to the API Viewer object.
currentTarget: A reference to the API Viewer object.
eventPhase: Always 2 (AT_TARGET).
bubbles: Always false.
cancelable: Always false.
timeStamp: The time the event was generated. This is the number of milliseconds since January 1, 1970.
preventDefault: Empty function.
stopPropagation: Empty function.
initEvent: Function that initializes the type, bubbles, and cancelable properties.

For a description of these properties, see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface.

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

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

Throws:
{String}: If the eventType or listener is invalid, or if scope is specified but invalid.

atFirstPage(callback, scope)

Queries the viewer as to whether it is currently showing the first page of the publication.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain one property, atFirstPage, which is the boolean response to the query.

Example data object:

{
    atFirstPage: true
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

atLastPage(callback, scope)

Queries the viewer as to whether it is currently showing the last page of the publication.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain one property, atLastPage, which is the boolean response to the query.

Example data object:

{
    atLastPage: true
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

downloadPDF()

Invokes the download PDF functionality.

Equivalent to clicking the download button in the toolbar.

HTML Desktop: This method must be called from code triggered by a user interaction, otherwise it might be blocked by the browser's pop-up blocker.

getCurrentPages(callback, scope)

Queries the viewer as to what pages are currently showing in the publication.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain two properties:

firstPage - {Number} - the first page in the page range.
lastPage - {Number} - the last page in the page range.

Example data object:

{
    firstPage: 1,
    lastPage: 2
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

getNumberOfPages(callback, scope)

Queries the viewer as to the number of pages in the publication.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain one property, numberOfPages, which is the integer response to the query.

Example data object:

{
    numberOfPages: 24
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

getPublicationID(callback, scope)

Queries the viewer as to the ID of the publication it is currently showing.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain one property, publicationID, which is the publication ID string.

Example data object:

{
    publicationID: "e90b813d"
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

getPublicationTitle(callback, scope)

Queries the viewer for the title of the publication.

The callback function should take one parameter, the data object returned from the viewer.

The data object will contain one property, publicationTitle, which is the title as a string.

Example data object:

{
    publicationTitle: "Verge issue 1"
}

Parameters:
{Function} callback: The callback function that will receive the result of the query.
{Object} scope Optional: The object scope (optional).

Throws:
{String}: If the callback is not a function, or if scope is specified but invalid.

gotoFirstPages()

Goes to the first page range in the publication.

If the viewer is locked, this function does nothing.

gotoLastPages()

Goes to the last page range in the publication.

If the viewer is locked, this function does nothing.

gotoNextPages()

Goes to the page range immediately after the currently-displayed page range in the publication.

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

gotoPage(pageNumber)

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.

Throws:
{String}: If the pageNumber is not a positive integer.

gotoPreviousPages()

Goes to the page range immediately before the currently-displayed page range in the publication.

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

gotoProduct(product, pageNumber)

Goes to the page containing the specified product in the publication and triggers the appropriate product activation event (onproductlinkactivate or onproductwidgetactivate).

If the current pages change, a currentpageschange event will also be fired. It is undefined whether this event is fired before or after the product activation event.

The product may be specified in one of two ways:

As a product ID (String)
As a product object previously returned by the API (see onproductlinkactivate, onproductwidgetactivate, etc.)

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 no product link or product widget activate event will be fired.

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

If the page number is not specified and the product exists on multiple pages, the first occurrence is used.

Parameters:
{String|Object} product: The product, either as a string (the product ID) or a product object previously returned by the API.
{Number} pageNumber Optional: The page number. Optional. If specified, must be a valid integer in the publication's page range.

Throws:
{String}: If the product or pageNumber is invalid.

openLightbox(url)

Opens a lightbox to the given URL.

The lightbox will only open if the viewer is configured to display a lightbox. This requires one of the following:

The existence of an external link in the publication that opens in a lightbox.
The viewer to be configured to open product links in a lightbox.

If the viewer is not configured to display a lightbox, the URL is invalid, or the viewer is currently locked, this function does nothing.

Parameters:
{String} url: The URL to open in the lightbox.

print()

Invokes the print functionality.

Equivalent to clicking the print button in the toolbar.

HTML Desktop: This method must be called from code triggered by a user interaction, otherwise it might be blocked by the browser's pop-up blocker.

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:

product_id - {String} - The unique product identifier (required if name is unspecified).
name - {String} - The product name (required if product_id is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.
discount_price - {double} - The per-unit discount price. If specified, is used instead of price. Must be non-negative.

If the product is from the product database, specifying the product_id is preferred to only specifying the name. This is because the product_id will then be used to look up the name. The reverse lookup cannot be done and less information will be logged.

The product object may contain additional properties; they will be ignored when registering statistics.

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 - {com.zmags.api.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 com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Example usage:

var product = {
    product_id: "my-product-id",
    name: "My Product Name",
    price: 1.0
},
quantity = 2,
context = {
    type: com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK,
    buyTheLookID: "my-btl-id"
};
viewer.registerProductAddedToSiteShoppingCart(product, quantity, context);

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.

Throws:
{String}: If the product or quantity is invalid.

See:: com.zmags.api.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:

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

The product object may contain additional properties; they will be ignored when registering statistics.

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 - {com.zmags.api.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 com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Example usage:

var product = {
    product_id: "my-product-id",
    name: "My Product Name",
    price: 1.0
},
context = {
    type: com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK,
    buyTheLookID: "my-btl-id"
};
viewer.registerProductDetailsViewed(product, context);

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

Throws:
{String}: If the product is invalid.

See:: com.zmags.api.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:

product_id - {String} - The unique product identifier (required if name is unspecified).
name - {String} - The product name (required if product_id is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.
discount_price - {double} - The per-unit discount price (optional). If specified, is used instead of price. Must be non-negative.

The product object may contain additional properties; they will be ignored when registering statistics.

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 - {com.zmags.api.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 com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Example usage:

var product = {
    product_id: "my-product-id",
    name: "My Product Name",
    price: 1.0
},
quantity = 2,
context = {
    type: com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK,
    buyTheLookID: "my-btl-id"
};
viewer.registerProductRemovedFromSiteShoppingCart(product, quantity, context);

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.

Throws:
{String}: If the product or quantity is invalid.

See:: com.zmags.api.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:

product_id - {String} - The unique product identifier (required if name is unspecified).
name - {String} - The product name (required if product_id is unspecified).
price - {double} - The per-unit price (required). Must be non-negative.
discount_price - {double} - The per-unit discount price (optional). If specified, is used instead of price. Must be non-negative.

The product object may contain additional properties; they will be ignored when registering statistics.

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 - {com.zmags.api.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 com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK. The identifier is included in the event sent to the API when a Buy the Look widget is activated.

Example usage:

var product = {
    product_id: "my-product-id",
    name: "My Product Name",
    price: 1.0
},
quantity = 2,
context = {
    type: com.zmags.api.Viewer.ProductContextType.BUY_THE_LOOK,
    buyTheLookID: "my-btl-id"
},
cartItem = {
    product: product,
    quantity: quantity,
    productContext: context
};
viewer.registerSiteShoppingCartCheckedOut([ cartItem ]);

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

Throws:
{String}: If the cartItems is not an array of valid cart items.

See:: com.zmags.api.Viewer.ProductContextType

removeEventListener(eventType, listener, scope)

Removes an event listener function previously registered through a call to addEventListener.

If there is no registered event listener matching the given parameters, this function does nothing.

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

Throws:
{String}: If the eventType or listener is invalid, or if scope is specified but invalid.

resize()

Signals the viewer to resize itself to match its container's dimensions.

Call this function whenever you manipulate the page in such a way that the size of the viewer's container may change.

The viewer will automatically resize itself when the browser window is resized (including orientation changes of mobile devices).

search()

Triggers the search function in the viewer.

Supported by all Verge viewers. Standard viewers are only supported in Flash.

If the viewer is locked, this function does nothing.

setFullscreenMode(fullscreenMode)

Sets the fullscreen mode for the viewer to use.

This setting applies only to Verge viewers that have the fullscreen button activated in the toolbar.

The fullscreen mode must be set before calling show() to load the viewer. Calling this function later has no effect.

If you do not change the fullscreen mode from the default, the fullscreen button will toggle the native fullscreen functionality of either Flash (for the Flash viewer) or the web browser (for the HTML5 viewer). If you are using lightboxes or other elements that should be displayed on top of the viewer, they may not work correctly when native fullscreen is active.

To address this, you may set the fullscreen mode to API_ONLY and use an event handler to simulate fullscreen by hiding other elements on the page, thereby giving the viewer a larger viewport. Remember to call resize on the viewer object after doing this.

Here is an example page where the viewer is displayed with a header, footer, and some margins. When the fullscreen button is pressed, these extra elements are removed so that the viewer fills the entire browser window.

<!DOCTYPE html>
<html>
    <head>
        <title>JavaScript API Test</title>
        <style>
            body {
                background: #444;
                color: #fff;
                padding: 0;
                margin: 0;
            }
            div#header, div#footer {
                width: 100%;
                height: 100px;
                position: absolute;
                text-align: center;
                line-height: 100px;
            }
            div#header {
                top: 0;
            }
            div#footer {
                bottom: 0;
            }
            div#myViewerContent {
                position: absolute;
                top: 0;
                bottom: 0;
                left: 0;
                right: 0;
                overflow: hidden;
                margin: 100px;
            }
            div#myViewerContent.fullscreen {
                margin: 0;
            }
        </style>
        <script src="http://api.viewer.zmags.com/viewer/viewer.js" type="text/javascript"></script>
        <script type="text/javascript">
            // Embed the viewer
            var viewer = new com.zmags.api.Viewer();
            viewer.setPublicationID("4d7f4063");
            viewer.setParentElementID("myViewerContent");
            viewer.setFullscreenMode(com.zmags.api.Viewer.FullscreenMode.API_ONLY);
            viewer.addEventListener(com.zmags.api.Viewer.TOOLBAR_BUTTON_ACTIVATE, toolbarButtonActivateHandler);
            viewer.show();

            function toolbarButtonActivateHandler(event) {
                // This event handler is fired for all toolbar button events, so make sure we only handle the
                // fullscreen button here
                if (event.buttonID === "fullscreen") {
                    var viewerElement = document.getElementById("myViewerContent"),
                        headerElement = document.getElementById("header"),
                        footerElement = document.getElementById("footer");
                    if (viewerElement.className === "fullscreen") {
                        viewerElement.className = "";
                        headerElement.style.display = "";
                        footerElement.style.display = "";
                    } else {
                        viewerElement.className = "fullscreen";
                        headerElement.style.display = "none";
                        footerElement.style.display = "none";
                    }

                    // Tell the viewer that the space available to it has changed
                    viewer.resize();
                }
            }
        </script>
    </head>
    <body>
        <div id="header">(header content)</div>
        <div id="myViewerContent"></div>
        <div id="footer">(footer content)</div>
    </body>
</html>

Parameters:
fullscreenMode: The fullscreen mode to set.

Throws:
{String}: If an unsupported fullscreen mode is passed or if the function is called after show() has been called.

See:: com.zmags.api.Viewer.FullscreenMode

setLocale(locale)

Sets the locale to use in the viewer.

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

If a locale is specified in the viewer configuration used by the publication, it is overridden by this function. If no locale is specified in the API or the viewer configuration, it is detected from the browser settings.

The following locales are supported:

ar (Arabic)
cs_CZ (Czech)
da_DK (Danish)
de_DE (German)
en_UK (English - United Kingdom)
en_US (English - United States, default)
es_ES (Spanish)
et_EE (Estonian)
fi_FI (Finnish)
fr_FR (French)
id_IN (Indonesian)
is_IS (Icelandic)
it_IT (Italian)
ja_JP (Japanese)
ko_KR (Korean)
lv_LV (Latvian)
nl_NL (Dutch)
no_NO (Norwegian)
pl_PL (Polish)
pt_BR (Portugese - Brazil)
pt_PT (Portugese - Portugal, default)
ru_RU (Russian)
sv_SE (Swedish)
zh_CN (Chinese - China, default)
zh_HK (Chinese - Hong Kong SAR)
zh_MO (Chinese - Macau SAR)
zh_TW (Chinese - Taiwan)

You may omit the region specifier from the locale, and just specify the language code. For languages that have multiple regions, the default region is specified in the list above. For example, pt is equivalent to pt_PT.

Locales are currently only used by the Flash viewer.

The locale must be set prior to calling show() to load the viewer.

Parameters:
{String} locale: The locale to use for the viewer, e.g. en_US.

Throws:
{String}: If an unsupported locale is passed or if the function is called after show() has been called.

setParentElementID(parentElementID)

Sets the ID of the element where the viewer is placed as a child in the DOM. The viewer is not actually inserted into the DOM until show() is called.

The parent ID must be set prior to calling show() to load the viewer.

On browser compatibility: When calling this function, it must be possible to determine the dimensions of the parent element. Different browsers have slightly different behaviors when determining the height. To make it work across most browsers, it might be necessary to explicitly set the style attributes 'height' and 'position' of the parent element. Specifying the 'height' in pixels seems to work regardless of the value of 'position' attribute. If the 'position' attribute is set to 'absolute' using a percentage for the 'height' also works.

Example:

width: 53%;
height: 760px;
position: relative;

Parameters:
{String} parentElementID: The ID of the element where the viewer is placed.

Throws:
{String}: If the parentElementID does not exist, the parentElement has an invalid size, or the function is called after show() has been called.

See:: com.zmags.api.Viewer#show

setPublicationID(publicationID)

Sets the ID of the publication to view.

To find the ID of a publication, look at the Basic Settings of the Edit Publication page in the Zmags Publicator.

The publication ID must be set prior to calling show() to load the viewer.

If setPublicationID() is called multiple times the last call takes precedence. setPublicationID() and setScheduleID() are mutually exclusive so the function that is requested last takes precedence.

If the publication uses redirects the redirected publication will be used.

Parameters:
{String} publicationID: The publication ID.

Throws:
{String}: If the publication ID is invalid or if the function is called after show() has been called.

setScheduleID(scheduleID)

Sets the ID of the schedule to view.

To find the ID of a schedule, look at either the schedule list or Edit Schedule page in the Zmags Publicator.

The schedule ID must be set prior to calling show() to load the viewer.

If setScheduleID() is called multiple times the last call takes precedence. setPublicationID() and setScheduleID() are mutually exclusive so the function that is requested last takes precedence.

Parameters:
{String} scheduleID: The schedule ID.

Throws:
{String}: If the schedule ID is invalid or if the function is called after show() has been called.

setSharePublicationURL(sharePublicationURL)

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 function to set up a custom URL that is shared instead, such as the URL of the page that is embedding the publication.

Parameters:
{String} sharePublicationURL: the custom 'share publication' URL.

Throws:
{String}: If the sharePublicationURL is invalid.

show()

Displays the viewer.

If the requested publication or schedule cannot be found, the viewer will not be loaded.

When/if the viewer has successfully loaded a com.zmags.api.Viewer.VIEWER_LOADED event will be fired.

Throws:
{String}: If no publication ID or schedule ID has been specified, or parentElementID has not been set, or show() has already been called.

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 not be dispatched from viewers that don't support product widgets (i.e. Standard viewers).

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

type: The type of the event. The value is com.zmags.api.Viewer.BUY_THE_LOOK_WIDGET_ACTIVATE.
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.
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 event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

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

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.

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 has a defaultProduct object, containing the product properties for the default product. The defaultProduct is the product identified by the standard product property "Default Product", with the following exceptions:

If no "Default Product" has been set, the defaultProduct is the first leaf variant.
If the product has no enabled leaf variants, it becomes its own defaultProduct.
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 defaultProduct.

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"]}

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

oncurrentpageschange(event)

Event handler function for the Current Pages Changed event. The event is dispatched when the current page range changes in the publication.

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

type: The type of the event. The value is com.zmags.api.Viewer.CURRENT_PAGES_CHANGE.
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.
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.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

Example usage:

<script>
    var viewer = new com.zmags.api.Viewer();
    viewer.setPublicationID("e90b813d");
    viewer.setParentElementID("myViewerContent");
    viewer.show();

    viewer.oncurrentpageschange = function(event) {
        alert("Current page range: " + event.pages.firstPage + " - " + event.pages.lastPage);
    }

</script>

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

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

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. The value is com.zmags.api.Viewer.CUSTOM_LINK_ACTIVATE.
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.
data: Custom data specified by the user.
pageNumber: The number of the page that was clicked.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

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. The value is com.zmags.api.Viewer.PRODUCT_LINK_ACTIVATE.
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.
defaultProduct: The default variant leaf product.
variants: The product's leaf variants.
variantPropertyValues: An object containing ordered values of variant properties.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

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.

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:

product_id
name
description
price

These property names are equivalent to the corresponding built-in identifiers in the product database, so if you mix product database and manual products, you can re-use these property names.

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.

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

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 not be dispatched from viewers that don't support product widgets (i.e. Standard viewers).

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

type: The type of the event. The value is com.zmags.api.Viewer.PRODUCT_WIDGET_ACTIVATE.
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.
defaultProduct: The default variant leaf product.
variants: The product's leaf variants.
variantPropertyValues: An object containing ordered values of variant properties.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

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

If no "Default Product" has been set, the defaultProduct is the first leaf variant.
If the product has no enabled leaf variants, it becomes its own defaultProduct.
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 defaultProduct.

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

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

ontoolbarbuttonactivate(event)

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

This event will not be dispatched from viewers that don't support the toolbar (i.e. Standard viewers).

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

type: The type of the event. The value is com.zmags.api.Viewer.TOOLBAR_BUTTON_ACTIVATE.
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.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

onviewerloaded(event)

Event handler function for the Viewer Loaded event. The event is dispatched when the viewer has loaded the publication in response to a call to show.

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

type: The type of the event. The value is com.zmags.api.Viewer.VIEWER_LOADED.
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.

The event also contains additional properties to comply with the DOM Level 2 event interface (see http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface).

Parameters:
{Object} event: The event object.

See:: com.zmags.api.Viewer#addEventListener

Classes

Class com.zmags.api.Viewer