Embed the Viewer
The PrizmDoc Viewer has been designed to be integrated into both new and existing web applications. Using the familiar jQuery plugin syntax, you can embed the Viewer into your application, and easily configure it to meet your needs.
The Viewer requires PrizmDoc Server (either using PrizmDoc Cloud or PrizmDoc Self-Hosted) in order to supplement viewing session requests. The Viewer also needs access to PrizmDoc Application Services; for more information on setting up PrizmDoc Application Services routing, see Configure PrizmDoc Application Services in your Server's Entry Point.
Setting up your Application to use the Viewer
Before initializing the Viewer using the jQuery plugin, some basic setup is required.
1. Add <meta> tags to the head of your page
These <meta> tags are important for utilizing the responsive features of the Viewer across devices and enabling support for Internet Explorer. Include these in the in the <head> of your page, if they are not already there.
Example
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1 user-scalable=no"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
2. Include the CSS files
The Viewer has a dependency on normalize, which needs to be loaded before all other styles. Then, load the two stylesheets that are part of the Viewer: viewercontrol.css, which styles the elements from the underlying viewer API, and viewer.css, which styles the Viewer itself.
To use the Viewer's user interface chrome, link to these stylesheets in the <head> of your page:
Example
<link rel="stylesheet" href="css/normalize.min.css">
<link rel="stylesheet" href="css/viewercontrol.css">
<link rel="stylesheet" href="css/viewer.css">
These files can be found in the viewer/css directory under the Prizm install directory.
3. Include the JavaScript files
The Viewer has a dependency on jQuery and jQuery Hotkeys, as well as Underscore. These need to be loaded first, followed by viewercontrol.js, the underlying viewing API, and viewer.js, the viewer code itself. Both viewercontrol.js and viewer.js are updated with each release of PrizmDoc.
Example
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="js/jquery.hotkeys.min.js"></script>
<script src="js/underscore.min.js"></script>
<script src="js/viewercontrol.js"></script>
<script src="js/viewer.js"></script>
<script src="js/viewerCustomizations.js"></script>
These files can be found in the viewer/js directory under the Prizm install directory. The order the scripts are loaded is important, and should be added in the order shown here.
4. Add a <div> to hold the Viewer
To add the Viewer to your application, you will need to create a <div> element with a unique ID where you would like to place the Viewer. In this example, we are using myDiv as our unique ID, but you may name it whatever fits your application’s coding guidelines.
Example
<div id="myDiv"></div>
5. Load Additional Resources and Initialize the Viewer
The Viewer ships with several additional resources which are required by the Viewer at runtime. These resources can all be found in the prizm installation directory under the Viewer subdirectory. These are compiled into viewerCustomizations.js via the Gulp buildscript in the Sample's viewer-assets directory.
languages
The Viewer's language resources which are required during initialization can be imported from viewerCustomizations.js. Including viewerCustomizations.js exposes a viewerCustomizations namespace which contains a languages object as a property. The languages object contains keys that correspond to locale identifiers.
The locale identifier should be provided during viewer initialization in the pluginOptions object, using the language key.
templates
Much of the Viewer's layout is defined in html template files. These files are found under the templates subdirectory and are required by the Viewer at initialization. The templates correspond to HTML files available in all samples - the filenames use the same name as the template names here, appending "Template.html" to the end - for example, the template fileName would correspond to a fileNameTemplate.html file. These files are compiled into viewerCustomizations.js and can be passed to the Viewer via viewerCustomizations.template. This should be set during initialization in the pluginOptions object, using the template key.
img
Several images containing icons and other graphic elements are required by the Viewer. These can be found under the img subdirectory. They are compiled into base64 image strings during compilation, and are provided in viewerCustomizations.js via viewerCustomizations.icons. This should be set during initialization in the pluginOptions object, using the icons key.
Directory Structure
The steps in this example assume the following layout for the resource directories:
├── index.html
├── css
├── img
├── js
├── languages
└── templates
Now that the setup is complete, you are ready to embed the full-featured, responsive Viewer into your web application using jQuery’s plugin syntax.
The Viewer’s user interface and behavior can be configured when it is embedded using JavaScript parameters. Only four parameters are required to initialize the Viewer: the previously described language, and template as well as the documentID and imageHandlerUrl which are described below. See the jQuery viewer plugin documentation for more information about each of these parameters.
documentID
This is the viewing session id returned upon the creation of a new viewing session. The id is used by the Viewer to make requests for document artifacts and to perform other operations.
imageHandlerUrl
This is the url of the PrizmDoc Application Services reverse proxy (or your own custom web tier). The Viewer will make requests through this endpoint. See Configure PrizmDoc Application Services in your Server's Entry Point for examples of setting up the reverse proxy.
Add the following snippet to your JavaScript file to set the required properties:
Example
var pluginOptions = {
documentID: viewingSessionId,
imageHandlerUrl: '/pas-service',
language: viewerCustomizations.languages['en-US'],
template: viewerCustomizations.template,
icons: viewerCustomizations.icons
}
$('#myDiv').pccViewer(pluginOptions);
If you chose a different ID than the example in Step 4 above, replace #myDiv with your chosen ID value.
There are lots of other configuration options for the Viewer. For detailed information on all the configuration options available to you, see the Configuration Options section.
Troubleshooting
Here are a few issues that may arise while initializing the Viewer that may not be immediately obvious. Here are some common console errors and their possible causes:
Uncaught TypeError
Cannot read property 'viewer' of undefined
This error is thrown when viewer.js cannot find the template object. Make sure that the template object exists and that there is a viewer property.
Uncaught ReferenceError
x is not defined
This error could be thrown if you have referenced a variable in the HTML templates that is not defined as data when loading the template. Check to see that this variable exists in either the language.json file or as a template data property used when loading a template.
If you’re still having issues setting up the Viewer, visit our Support page.