Creating a Widget
1) Log into the Zmags Publicator and click on "All Publications".
2) To the right of the publication you'd like to add a widget to, click the little icon in the 'Enrichments' column.
3) Wait for Zmags Enriched to load. Using the page-select menu on the right side, navigate to the desired page.
4) Click the cog icon on the left side, "HTML5 Iframe Widget", and then "Rectangular Tool". ("Video embed Widget" is a special case, and will be covered later in this article.)
5) Draw a box on the page by dragging from where you would like one corner to be, to where you would like the opposite corner to be.
Once you have created a widget, the following options will be available to you:
First, select one of the following types of IFrame:
- Partial page / non-interactive: This frame will use the specified height and width variables (below). It also removes any interactivity from the framed content by ignoring user clicks.
- Partial page / interactive: Like the option above, but does not ignore user clicks. This is what you will want to use for most of your widgets, such as all of the examples in the next section.
- Full page / non-interactive: Like the first option, but does not use the specified height, width, or positioning - instead fills the entire page of the Zmag.
Thees properties determine the size and positioning of the IFrame, as measured in pixels:
- Top / Left: The positioning of the upper left corner of the IFrame, in relation to the upper left corner of the publication page.
- Width / Height: The size of the IFrame, in relation to the size of the publication page while zoomed in. Generally it is best to ignore these numbers and size your frame based on how it looks in the "Page Window". They can be helpful however, for tweaking the dimensions to a given ratio after rough sizing is complete.
- iframe URL: This property determines what HTML content will be displayed in the IFrame. Simply enter the full URL of the desired file, be it HTML, PNG, PHP, or something else entirely.
Sizing IFrame Content
When designing your content to be placed in a IFrame widget, it is important to keep in mind that the sizing of the frame is based on the size of the publication page. Because the publication page is resized based on how large the browser window is and what zoom level it is viewed at, the specific size of the frame can be unpredictable.
As such, it is best to use content that will scale to fit, whenever possible. YouTube videos, for example, do this automatically already. Try opening up the following video embed page and then resize your browser window a few times:
Once you have set up your content to properly scale for desktop devices, be sure to add the following code to the <head> of the finished HTML file to ensure proper scaling for mobile devices as well:
<meta name="viewport" content="initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width" />
In the worst case, if your content does not fit the IFrame's current size, scroll bars will be provided so that it can still be viewed in its entirety.
Video Embed Widget
These are a special type of IFrame widget intended to make integrating YouTube and Vimeo videos to your publications a much easier process. As in the Creating a Widget section above, follow the same steps but this time select "Video embed Widget" instead.
The widget properties are a little bit different in this case, but still relatively straightforward:
- Top / Left / Width / Height: Size and positioning properties, used the same way as above.
- Platform: Select whether the video will be loaded from YouTube or Vimeo.
- Video ID: Enter the YouTube or Vimeo ID. This is found at the end of the video URL on the hosting site. For example, the video https://www.youtube.com/watch?v=szCNPHY-0o4 would have the Video ID of "szCNPHY-0o4"
- Enable controls: Choose whether or not the control panel (progress bar, volume, etc) will be shown on the video player.
- Autoplay: Check this to automatically start the video when the reader reaches the appropriate page. (Does not work for most mobile devices.)
- Loop: Check this to loop back to start when the video reaches its end.
Example HTML5 Widgets
Simple HTML5 Animations:
The widgetizer is a great tool for creating simple sliding animations with text and image assets. These are hosted online by our system, and a simple URL is provided to paste into your widget settings:
For information on creating a widget featuring the Facebook like button, see this article:
Creating a Facebook Like Widget
To add a form generator form to your IFrame:
1) Using the Zmags Form Generator tutorial, create an online form. (Complete the "Hosting the Form" and prior sections, but skip the "Embedding" sections after that.)
2) Use the URL of the HTML form file for the widget's "iframe URL".
3) You may need to do some guess and check with the size and positioning of your widget, as the "light box size recommendations" from the Form Generator will not be helpful here.
Our IFrame Widget API allows your HTML IFrame widgets to access some of the Viewer API's functionality. This is particularly useful because ordinarily accessing API functionality requires an embedded viewer page, but in some cases a widget may instead be used to roll that functionality directly into the viewer.zmags.com URL.
To start using the API, include this code in the <head> of your widget HTML:
var Iframe = com.zmags.api.widgets.Iframe;
var viewer = Iframe.getViewerAPI();
After that's done, you are ready to start using some of the available functionality. Code for the examples show in the demo are given below:
- Page turn: Here is the code used for the first page, previous page, next page, and last page buttons.
<button type="button" onClick="viewer.gotoFirstPages();">|<</button>
<button type="button" onClick="viewer.gotoPreviousPages();"><</button>
<button type="button" onClick="viewer.gotoNextPages();">></button>
<button type="button" onClick="viewer.gotoLastPages();">>|</button>
- Go to Page: This code runs the page number entry and associated 'Go' button.
<input type="text" name="goto" style="text-align:right;">
<button type="button" onClick="viewer.gotoPage(document.getElementsByName('goto').value); document.getElementsByName('goto').value = ''">Go</button>
This section of the demo might not look like much, as most of its data will not change very often, but the interesting thing here is that it is dynamically loading this information on page turn. Ordinarily, you would then use this data to do something more interesting, but in this case we are simply displaying it to the reader. Here is the script that loads the data:
document.getElementById('title').innerHTML = data.publicationTitle;
document.getElementById('pub_id').innerHTML = data.publicationID;
document.getElementById('num_pages').innerHTML = data.numberOfPages;
document.getElementById('cur_pages').innerHTML = data.firstPage + "-" + data.lastPage;
Here is the HTML used to hold the data once loaded:
Title: <span id="title"></span><br>
ID: <span id="pub_id"></span><br>
Number of pages: <span id="num_pages"></span><br>
Current page(s): <span id="cur_pages"></span><br><br>
This button simply opens the viewer's built-in search functionality:
<button type="button" onClick="viewer.search();">Search Text</button>
Controlling Widget Load Timing:
By default, your widgets will load just as soon as the page they occupy does, but this is not always desirable behavior. If your animation is non-looping, it may already be done playing by the time readers are actually viewing the proper page.
To correct this, add the following to the <script> in the <head> of your widget HTML, below the "var viewer" line added earlier:
// Code to activate your widget's animation goes here.
// Optionally, code to deactivate or reset your animation goes here.
Other Uses for the IFrame API:
This tutorial demonstrates how to use the API to preserve horizontal swipe functionality on mobile devices:
Horizontal Swipe within IFrame Widgets
This tutorial demonstrates opening a lightbox link when clicking content within an IFrame widget:
Opening a Lightbox from a Widget