Config files

WebViewer fundamentals explains how WebViewer creates the UI app inside an iframe, so that Core namespaces and classes are encapsulated. The iframe window and document object are still accessible through contentWindow and contentDocument, but it can still be tricky to run scripts or listen to events happening inside the iframe.

WebViewer provides an option referred to as a "config file". It's just an ordinary JavaScript file, but it will be executed in the context of the iframe. This gives you easy access to the Document, DocumentViewer and AnnotationManager objects (among others) which can allow you to make more complicated customizations.

To instantiate WebViewer with a config file you just need to set the config option in the WebViewer constructor. For example:

WebViewer({
  initialDoc: "mydoc.pdf",
  config: "path/to/my/config/file.js" // relative to your HTML file
}, viewerElement);

The config file is executed even before the core objects are instantiated, so you won't be able to call core functions immediately. You can listen for events on the HTML document object that will notify you at key points.

The first important one is the viewerLoaded event. viewerLoaded will be fired after app has been rendered, and at this point you'll be able to access the documentViewer variable before the document has loaded. For example:

instance.UI.addEventListener(instance.UI.Events.VIEWER_LOADED, () => {
  documentViewer.setMargin(20);
  documentViewer.addEventListener('fitModeUpdated', fitMode => {
    console.log('fit mode changed');
  });
});

Another important event is documentLoaded. Once documentLoaded has fired you can access Document as well as functions related to the page number on ReaderControl, DocumentViewer and AnnotationManager. For example:

instance.UI.addEventListener(instance.UI.Events.DOCUMENT_LOADED, () => {
  const doc = documentViewer.getDocument();
  doc.loadThumbnailAsync(1, thumb => {
    const myThumbnailDiv = document.getElementById('myThumbnailDiv');
    myThumbnailDiv.appendChild(thumb)
  });

  const annotManager = documentViewer.getAnnotationManager();
  const rectangle = new Annotations.RectangleAnnotation();
  rectangle.PageNumber = 2;
  rectangle.X = 100;
  rectangle.Y = 100;
  rectangle.Width = 250;
  rectangle.Height = 250;
  rectangle.Author = annotManager.getCurrentUser();
  annotManager.addAnnotation(rectangle);

  documentViewer.displayLastPage();
});

Sometimes you might want to send custom data from the "outer" page (with the PDFTron.WebViewer constructor) to the "inner" page (your config file). To do this you can use the custom option in the WebViewer constructor. The property expects a string value. So for example to pass an object:

const myObj = {
  startPage: 10
};

WebViewer({
  custom: JSON.stringify(myObj)
}, viewerElement);

Then inside the config file you access this data as follows:

let custom;

instance.UI.addEventListener(instance.UI.Events.VIEWER_LOADED, () => {
  const custom = JSON.parse(instance.UI.getCustomData());
  console.log(custom.startPage); // outputs 10
});

instance.UI.addEventListener(instance.UI.Events.DOCUMENT_LOADED, () => {
  const docViewer = instance.Core.documentViewer;
  docViewer.setCurrentPage(custom.startPage);
});

If you have the WebViewer path on a different domain than your app, then to protect against XSS attacks you will need to edit the lib/ui/configorigin.txt file to whitelist your app's domain(s). A wildcard character can also be used to match part of a domain. Add each domain on a separate line, for example:

http://localhost:3000
https://example.com
https://*.pdftron.com

Domains in this list will be allowed to have WebViewer specify config files that can be loaded.

If you want to access the outer page from inside the iframe, for example from code in your config file, you can access the parent window using window.parent. So if you defined an API that's loaded on your HTML page, you could access it from inside the iframe like window.parent.myApi.myFunction().

If you want to access the WebViewer instance from the config file, depending on the version you can use instance in place of the instance argument normally returned when instantiating WebViewer.

Here is an example of the Viewing sample converted to a config file:

instance.UI.addEventListener(instance.UI.Events.VIEWER_LOADED, function() {
  window.parent.document.getElementById('select').onchange = function(e) {
    instance.UI.loadDocument(e.target.value);
  };

  window.parent.document.getElementById('file-picker').onchange = function(e) {
    var file = e.target.files[0];
    if (file) {
      instance.UI.loadDocument(file);
    }
  };

  window.parent.document.getElementById('url-form').onsubmit = function(e) {
    e.preventDefault();
    instance.UI.loadDocument(window.parent.document.getElementById('url').value);
  };
});