Class com.zmags.api.widgets.Iframe

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.widgets.Iframe(window) Enables communication between an iframe widget and the viewer.

Field Summary
Field Attributes	Field Name and Description
<static> <constant>	com.zmags.api.widgets.Iframe.IFRAME_WIDGET_ACTIVATE Event sent from the viewer when the page containing the iframe is activated.
<static> <constant>	com.zmags.api.widgets.Iframe.IFRAME_WIDGET_DEACTIVATE Event sent from the viewer when the page containing the iframe is deactivated.

Function Summary
Function Attributes	Function Name and Description
<static>	com.zmags.api.widgets.Iframe.addEventListener(eventType, listener, scope) Adds an event listener for events sent from the viewer to the iframe.
<static>	com.zmags.api.widgets.Iframe.getViewerAPI() Gets an instance of the Viewer API that can be used to observe and control the viewer.
<static>	com.zmags.api.widgets.Iframe.horizontalSwipeNavigation(enabled) For interactive widgets running on touch based devices, enables (or disables) horizontal swipe navigation, i.e.

Class Detail

com.zmags.api.widgets.Iframe(window)

Enables communication between an iframe widget and the viewer.

To use the API, include this javascript file in the page loaded in the iframe and call the static addEventListener method to register a listener function for events from the viewer. There is no need to construct an instance of Iframe directly.

The viewer will load the iframe contents when it constructs the page containing the iframe widget. The user may or may not be viewing the page. If the user clicks normally through the publication, pages will typically be constructed a few spreads ahead of the user, and this is when the iframe will be loaded.

In order to synchronize animations or other events that need to happen when the user starts viewing the page, the viewer sends events that can be received using this API. When a page is displayed that contains an iframe widget, an "iframe widget activate" event is sent to it. When the user navigates away from the page, an "iframe widget deactivate" event is sent to it. If the user navigates far enough away from the page that the page is destroyed, the iframe will be destroyed as well, and will be reloaded if the user returns to that page.

Author: Zmags.


<!DOCTYPE html>
<html>
    <head>
        <title>Iframe API Test</title>
        <script src="//secure.api.viewer.zmags.com/widgets/iframe.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript">
            var Iframe = com.zmags.api.widgets.Iframe;

            // Register listener for when the iframe is activated
            Iframe.addEventListener(Iframe.IFRAME_WIDGET_ACTIVATE, function(event) {
                console.log("Widget activated for publication", event.publicationID);
            });

            // Register listener for when the iframe is deactivated
            Iframe.addEventListener(Iframe.IFRAME_WIDGET_DEACTIVATE, function(event) {
                console.log("Widget deactivated.");
            });
        </script>
    </body>
</html>

Parameters:
{Window} window: The iframe's window object.

Field Detail

<static> <constant> com.zmags.api.widgets.Iframe.IFRAME_WIDGET_ACTIVATE

Event sent from the viewer when the page containing the iframe is activated.

The iframe is considered "activated" when the page containing it starts being viewed by the user.

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.widgets.Iframe.IFRAME_WIDGET_ACTIVATE.
publicationID: The ID of the publication that contains the widget.
currentPages: The current page range displayed by the viewer.
widgetPages: The page range on which the widget is displayed.

The currentPages and widgetPages properties are page range objects, which contain the following properties:

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

The widgetPages property will currently always have the first page equal to the last page, as it is not possible to stretch an iframe widget across multiple pages. The property is defined in the API as a page range for future extensibility.

<static> <constant> com.zmags.api.widgets.Iframe.IFRAME_WIDGET_DEACTIVATE

Event sent from the viewer when the page containing the iframe is deactivated.

The iframe is considered "deactivated" when the page containing it stops being viewed by the user.

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.widgets.Iframe.IFRAME_WIDGET_DEACTIVATE.
publicationID: The ID of the publication that contains the widget.
currentPages: The current page range displayed by the viewer.
widgetPages: The page range on which the widget is displayed.

The currentPages and widgetPages properties are page range objects, which contain the following properties:

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

Function Detail

<static> com.zmags.api.widgets.Iframe.addEventListener(eventType, listener, scope)

Adds an event listener for events sent from the viewer to the iframe.

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

See:: com.zmags.api.widgets.Iframe.IFRAME_WIDGET_ACTIVATE; com.zmags.api.widgets.Iframe.IFRAME_WIDGET_DEACTIVATE

<static> com.zmags.api.widgets.Iframe.getViewerAPI()

Gets an instance of the Viewer API that can be used to observe and control the viewer.

All viewer API functions and events that can be used after the viewer is loaded are available for use here.

See:: http://documentation.zmags.com/viewercommonapi/index.html

<static> com.zmags.api.widgets.Iframe.horizontalSwipeNavigation(enabled)

For interactive widgets running on touch based devices, enables (or disables) horizontal swipe navigation, i.e. horizontal swipe gestures will result in the viewer navigating to the next or previous pages, depending on the swipe direction.

The Iframe API will listen for touch events on the iframe window's document (i.e. window.document), in order to determine if a swipe gesture was performed. If part of your content requires swiping, e.g. an image gallery, you would need to stop the touch event from propagating (event.stopPropagation) all the way to window.document, thus preventing the viewer from navigating.

By default, horizontal swipe navigation is disabled, i.e. swipe gestures are owned by the widget.

Calling this function from a non-interactive widget, or device that does not support touch events, has no effect (NOP).


<!DOCTYPE html>
<html>
    <head>
        <title>Iframe API Test</title>
        <script src="//secure.api.viewer.zmags.com/widgets/iframe.js" type="text/javascript"></script>
    </head>
    <body>
        <script type="text/javascript">
            var Iframe = com.zmags.api.widgets.Iframe;

            // Enable horizontal swipe navigation for touch based devices
            Iframe.horizontalSwipeNavigation(true);
        </script>
    </body>
</html>

Parameters:
{Boolean} enabled: Whether swipe navigation should be enabled or not.

Classes

Class com.zmags.api.widgets.Iframe