Running WebViewer as a Web Component

Starting in version 11 WebViewer will be instantiated in a Web Component by default instead of an iframe.

There are some differences between working with WebViewer as an iframe and as a Web Component. Here are some of the key changes:

When using an iframe, it is possible to access DOM elements using instance.UI.iframeWindow.document.

1instance.UI.iframeWindow.document.querySelector('.ModularHeader');

However, with a Web Component, WebViewer is part of the main document but encapsulated within a Shadow DOM. Shadow DOM provides a contained scope for the Web Component, helping prevent unintended styling or script interference from the rest of the page. To access elements inside this Web Component, you need to first access its shadowRoot and then query within it.

1// there could be multiple instances of WebViewer on the page so the [0] is getting the first one
2document.getElementsByTagName('apryse-webviewer')[0].shadowRoot.querySelector('.ModularHeader');

This shadowRoot approach gives access to elements within the isolated part of the DOM where WebViewer resides. It respects the Shadow DOM’s encapsulation, which is key to keeping the component’s styles and scripts scoped and self-contained, while still allowing controlled access for customization or interaction when needed.

Since WebViewer is encapsulated within a Shadow DOM, in order to apply CSS styles to elements in WebViewer you need to use the :host selector when using the css option in your WebViewer constructor. This selector targets the Web Component itself, allowing you to style its elements from the outside.

The following code would style the WebViewer to use white icons and blue headers.

1:host {
2    --icon-color: #FFFFFF !important;
3
4    .ModularHeader {
5      background-color: #00a5e4;
6    }
7  }

You can then include the CSS file in the css property of your WebViewer constructor like so:

1Webviewer(
2    {
3      path: '/path/to/your/webviewer',
4      initialDoc: '/path/to/your/document.pdf',
5      css: '/path/to/your/styles.css'
6    },
7    viewerElement
8  ).then((instance) => {
9
10  });

Without using the :host selector, the styles would not be applied to the WebViewer.

Up until now, WebViewer has been instantiated using an iframe. An iframe, or inline frame, is an HTML document embedded inside another HTML document. Iframes have several benefits, such as content isolation and the ability to display content from different sources. However, they also present certain drawbacks. For instance, iframes can slow down site performance as the browser needs to load two separate pages. They can also pose accessibility challenges for assistive technologies like screen readers. Furthermore, running WebViewer in an iframe prevents the parent page from accessing its content directly, limiting opportunities for data gathering and analytics to better understand how users interact with your documents.

Web Components are a suite of web platform APIs that allow developers to create custom, reusable, encapsulated HTML tags for use in web pages and apps. As part of the web browser standard, they're an excellent choice for creating reusable code modules.

Benefits of Web Components:

• Encapsulation: Styles and behaviors within a web component are self-contained, preventing conflict with other code by avoiding global scope leakage.
• Reusability: Web Components can be reused across different projects or even within different parts of the same project, enhancing development efficiency.
• Interoperability: Web Components integrate well with existing web technologies and are compatible with any JavaScript library or framework that supports HTML.
• Standardization: Built on web standards, modern browsers natively support Web Components without the need for additional libraries.

With the release of version 11, WebViewer is now instantiated as a Web Component by default. This allows you to leverage the advantages of encapsulation and reusability while giving your site direct access to the viewer's content. As a result, you can create a more seamless experience for your users and gather data and analytics on how they interact with your documents.

Previously when using NPM to integrate WebViewer into your project, there needed to be minimal code changes to instantiate WebViewer as a Web Component.

In version 11, there is no longer any need to use WebViewer.WebComponent as Web Component is now the default for WebViewer. The following code snippet demonstrates how to instantiate WebViewer as a Web Component:

1import WebViewer from '@pdftron/webviewer'
2
3WebViewer({
4  path: '/public/webviewer',
5  licenseKey: 'YOUR_LICENSE_KEY',
6}, document.getElementById('viewer'))
7  .then(instance => {
8    const { UI, Core } = instance;
9    const { documentViewer, annotationManager, Tools, Annotations } = Core;
10    // call methods from UI, Core, documentViewer and annotationManager as needed
11
12    documentViewer.addEventListener('documentLoaded', () => {
13      // call methods relating to the loaded document
14    });
15
16    instance.UI.loadDocument('https://pdftron.s3.amazonaws.com/downloads/pl/demo-annotated.pdf');
17  })

If you prefer to use an iframe, you can still do so by replacing the WebViewer function with WebViewer.Iframe and it will work as it did before.

1import WebViewer.Iframe from '@pdftron/webviewer'
2WebViewer({
3  path: '/public/webviewer',
4  licenseKey: 'YOUR_LICENSE_KEY',
5}, document.getElementById('viewer'))
6  .then(instance => {
7    const { UI, Core } = instance;
8    const { documentViewer, annotationManager, Tools, Annotations } = Core;
9    // call methods from UI, Core, documentViewer and annotationManager as needed
10
11    documentViewer.addEventListener('documentLoaded', () => {
12      // call methods relating to the loaded document
13    });
14
15    instance.UI.loadDocument('https://pdftron.s3.amazonaws.com/downloads/pl/demo-annotated.pdf');
16  })

Manual integration is also straightforward. For more info please refer to the manual integration guide.

Large resource and worker files can be hosted on a CDN or some other external server for faster access and caching. WebViewer provides several APIs for dealing with cross-origin resource sharing issues and you can read more about it in this Cross Origin Workers guide.