JavaScript API Starter Tutorial - Vuzit Online Document Viewer

Introduction

This tutorial describes the basics of using the Vuzit web-based document viewer. It is meant for developers or designers of web applications. Persons reading this tutorial should, in the very least, have a rudimentary knowledge of HTML and JavaScript. Please reference the HTML and JavaScript tutorials at W3Schools, should any help understanding the terminology be necessary.

Example Script

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>Vuzit Simple Document Example</title>
    <!-- Required JavaScript and CSS includes -->
    <link href="http://vuzit.com/stylesheets/Vuzit-2.6.css" rel="Stylesheet" type="text/css" />
    <script src="http://vuzit.com/javascripts/Vuzit-2.6.js" type="text/javascript"></script>
 
    <script type="text/javascript">
      // Called when the page is loaded.
      function initialize() {
        vuzit.Base.apiKeySet("PUT_YOUR_KEY_HERE");
        var viewer = vuzit.Viewer.fromUrl("http://www.welcomingcenter.org/documents/PMP.pdf", {});
        viewer.display(document.getElementById("vuzit_viewer"), { zoom: 1, page: 2 });
      }
    </script>
  </head>
  <body onload="initialize()">
    <div id="vuzit_viewer" style="width: 650px; height: 500px;"></div>
  </body>
</html>

To see how this works, download the source code here. The above code will be broken down into some more digestible pieces further into this tutorial.

Note: if the downloaded script runs on a local computer with Internet Explorer (IE), the user will be shown a small warning bar beneath the Address Bar that approximately states: "To help protect your security, Internet Explorer has restricted this file from showing active content that could access your computer". Right-click on this bar and select "Allow blocked content" to see the viewer. Once this is done, click "Yes" on the following dialog box.

Loading the Vuzit code

<link href="http://vuzit.com/stylesheets/Vuzit-2.6.css" rel="Stylesheet" type="text/css" />
<script src="http://vuzit.com/javascripts/Vuzit-2.6.js" type="text/javascript"></script>

The script tag loads the JavaScript library containing the widget. The link tag loads the URL to CSS for the viewer. Without it, the viewer will not be properly loaded. Note that each file has a version number in the name. As the Vuzit team comes out with new versions this number will increase.

NOTE: Please do not download the JavaScript file and store it on your server. We will never remove old versions of the libraries however if there are bugs that creep into a revision we do hold the right to fix them. If you download a copy to your server then you will not receive the fixes. The proper method of including Vuzit in your application is to access it directly using the URL provided above.

Viewer Container

<div id="vuzit_viewer" style="width: 650px; height: 500px;"></div>

The code above defines the viewer container where the viewer will ultimately load itself. The style attribute defines the width and height of the container. The user can change these settings to adjust the size of the viewer to whatever is preferred. This example references the "vuzit_viewer" element when the control is loaded in the next section.

Setting The Developer Key

vuzit.Base.apiKeySet("PUT_YOUR_KEY_HERE");

In order to use the Vuzit viewer, it is necessary to sign up for an API key.

Replace the "PUT_YOUR_KEY_HERE" with the Vuzit Public Key provided. This can be found on your Settings page. The vuzit.Base.apiKeySet function needs to be called before using any Vuzit tools to verify that the user is allowed to use the API.

Viewer Object - vuzit.Viewer

var viewer = vuzit.Viewer.fromUrl("http://www.welcomingcenter.org/documents/PMP.pdf", {});

The vuzit.Viewer object is the base object for the viewer. It can be created by the above line of code using the fromUrl function. This tells the viewer to load the document at the specified URL in the first parameter, in this case the "http://www.welcomingcenter.org/documents/PMP.pdf" file. You can define any publicly addressable document here. The second parameter is the name of a function that should be called when the document is finished being loaded. For instance, if you have defined a "printer()" function in your code and wish to run it after the document is loaded, you would set "printer" (without the parentheses) for the second parameter. If you do not wish to run any functions upon loading, simply set this value to null. For more examples of the constuctor, consult the examples at our developer page.

var viewer = vuzit.Viewer.fromId("1g", {});

As an alternative to fromUrl, you can also create a Viewer object with the fromId function. This tells the viewer to load the document with the specified Vuzit web id in the first parameter, in this case the document with the id "1g." The web id is a Base 36 encoded string. This means it should always be enclosed in quotes to denote it as a strong. For instance, "1" will work, but 1 (without quotes) will not. As in fromUrl, the second parameter is the name of a function that should be called when the document is finished being loaded. fromId will ONLY work if there is already a document in Vuzit with the id that is passed in, otherwise there will be no document shown.

NOTE: The fromUrl and fromId functions do not actually display a viewer. You must call the display function as well.

viewer.display(document.getElementById("vuzit_viewer"), { zoom: 1, page: 2 });

The vuzit.Viewer display function allows the user to load the viewer control into the div tag described previously, which is defined in the first parameter. The document.getElementById("vuzit_viewer") function returns the div tag that was created in the body tags. Display requires the user to set the Viewer's document before it is called, either in the constructors or via the setUrl or setId functions, described below.

Notice a pair of brackets "{ }", this symbolizes a hash table of options. The "zoom: 1" tells the viewer to load the second zoom level. Possible zoom levels are 0 (smallest), 1, and 2 (largest). The "page: 2" tells the viewer to load with page number 2 of the document.

viewer.setUrl("http://localtype.org/images/morimotomenu.pdf");

viewer.setId("8");

The vuzit.Viewer setUrl and setId functions are optional functions that can be used to load a different document into the viewer after the constructor has been called. setUrl tells the viewer to load the document at the specified URL, in this case the "http://localtype.org/images/morimotomenu.pdf" file. setId tells the document to load the document with the specified Vuzit web id, here the document with an id of "8". Like the constructor, you can add any publicly addressable document into this function.

NOTE: If display was called previously via setUrl or setId, the setUrl or setId call will hide the viewer on the page. You must call display again to show the viewer.

Loading The Viewer

<body onload="initialize()">

This section tells the web page to call the initialize function once the page is done loading. Some web browsers run scripts before the HTML is done loading, which causes problems. By adding this script to the onload event, it prevents the viewer from being loaded before that happens.

Now you should be a veritable expert on Vuzit, right? Well maybe not yet, but you are on your way!

What Else Can I Do?

There are several things that still be done. For instance, there are methods to set the page of the document as well as the zoom. Please see the vuzit.Viewer object in the Vuzit reference document for more information.