Migrating to V7 of WebViewer

There are a few breaking changes and other changes when migrating to v7 from older versions.

Breaking changes

New default UI

There is a new default user interface in WebViewer 7.0 which has changed the location and structure of some components in the UI. Most APIs will function the same as before.

One of the main changes is to the header toolbars which are split into several groups. You can change the group using setToolbarGroup and you can edit each group using the getHeader function.

JavaScript

WebViewer(...)
  .then(instance => {
    // adds a button to the shapes header
    instance.setHeaderItems(header => {
      const shapesHeader = header.getHeader('toolbarGroup-Shapes');
      shapesHeader.push({
        type: 'actionButton',
        img: '...',
        onClick: () => {
          // perform action
        }
      });
    });
  });

If you want to hide a specific toolbar group, like other DOM elements, they can be hidden by using disableElements.

JavaScript

WebViewer(...)
  .then(instance => {
    // hide the Shapes, Edit and Insert toolbar groups.
    instance.disableElements(['toolbarGroup-Shapes']);
    instance.disableElements(['toolbarGroup-Edit']);
    instance.disableElements(['toolbarGroup-Insert']);
  });

If you are not ready to update to the new UI yet you can still access the previous UI by passing ui: 'legacy' into your WebViewer constructor.

JavaScript

WebViewer({
  ui: 'legacy',
  // other constructor options
}).then(instance => {

});

Page numbers instead of page indexes for APIs

Several breaking changes have been made to make sure API signatures are more consistent in WebViewer 7.0. We've heard feedback that it can be confusing using some WebViewer APIs because some accept page indexes (starting with zero) and some accept page numbers (starting with one). In 7.0 we've updated all APIs to be page numbers (starting with one) to be consistent.

Generally if you were using APIs on AnnotationManager and DocumentViewer these were already taking in 1-indexed page numbers. If you were using APIs on the Document object these were taking in 0-indexed page numbers.

Below are some examples of the changes:

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const doc = instance.docViewer.getDocument();
      // get the information of the first page
      const pageNumber = 1;
      const pageInfo = doc.getPageInfo(pageNumber);
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const doc = instance.docViewer.getDocument();
      // get the information of the first page
      const pageIndex = 0;
      const pageInfo = doc.getPageInfo(pageIndex);
    });
  });

The following APIs have been changed to use page numbers:

• pageComplete

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('pageComplete', (pageNumber, canvas) => {
      ...
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('pageComplete', (pageIndex, canvas) => {
      ...
    });
  });

• DocumentViewer textSelected

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('textSelected', (quads, text, pageNumber) => {
      ...
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('textSelected', (quads, text, pageIndex) => {
      ...
    });
  });

• TextTool textSelected

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    const { TextTool } = instance.Tools;

    TextTool.prototype.textSelected = function(pageNumber, quads, text) {
      ...
    }
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const { TextTool } = instance.Tools;

    TextTool.prototype.textSelected = function(pageIndex, quads, text) {
      ...
    }
  });

• getSelectedPages

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    const displayMode = instance.docViewer.getDisplayModeManager().getDisplayMode();
    const windowPoint = { ... };

    const page = displayMode.getSelectedPages(windowPoint, windowPoint);
    const firstPageNumber = page.first;
    const lastPageNumber = page.last;
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const displayMode = instance.docViewer.getDisplayModeManager().getDisplayMode();
    const windowPoint = { ... };

    const page = displayMode.getSelectedPages(windowPoint, windowPoint);
    const firstPageIndex = page.first;
    const lastPageIndex = page.last;
  });

• pageCoordinates

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    const tool = instance.docViewer.getToolMode();

    console.log(tool.pageCoordinates[0].pageNumber);
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const tool = instance.docViewer.getToolMode();

    console.log(tool.pageCoordinates[0].pageIndex);
  });

• SearchResult

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      docViewer.textSearchInit(searchText, mode, {
        onResult: result => {
          // pageNum is 1-indexed
          console.log(result.pageNum);
        },
      });
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      docViewer.textSearchInit(searchText, mode, {
        onResult: result => {
          // CAUTION: page_num is 0-indexed
          console.log(result.page_num);
        },
      });
    });
  });

• pageToWindow
• windowToPage
• getPageTransform
• getPageOffset
• getLinks
• getPageInfo
• getPDFCoordinates
• getTextPosition
• getXODCoordinates
• getViewerCoordinates
• loadPageText
• loadThumbnailAsync
• getPageMatrix
• getPageWidth
• getPageHeight
• getPageRotation
• getPageRotations
• setPageRotations
• getPageZoom
• setPageZoom
• getViewportRegionRect
• updateLinks
• stopPageRender
• loadCanvasAsync
• getVisiblePages
• updateView

The following DOM elements have been changed to use page numbers:

• #pageContainer
• #pageWidgetContainer

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const iframeDocument = instance.iframeWindow.document;
      const firstWidgetContainer = iframeDocument.querySelector('#pageWidgetContainer1');
    })
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const iframeDocument = instance.iframeWindow.document;
      const firstWidgetContainer = iframeDocument.querySelector('#pageWidgetContainer0');
    })
  });

PartRetrievers cannot be accessed directly

Previously you could reference a PartRetriever directly from the PartRetriever namespace. Now the PartRetrievers are lazy loaded when needed so you can access them through the asynchronous getPartRetriever API.

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(async (instance) => {
    const { PartRetrievers } = instance.CoreControls;
    const options = {};

    const partRetriever = await PartRetrievers.getPartRetriever(PartRetrievers.TYPES.ExternalPdfPartRetriever, 'YOUR_FILE_PATH', options)
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const options = {};
    const partRetriever = new instance.CoreControls.PartRetrievers.ExternalPdfPartRetriever('YOUR_FILE_PATH', options);
  });

ResultCode has been moved to the CoreControls namespace

The XODText namespace has been removed from the iframe window, and ResultCode belongs to the CoreControls namespace now.

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.textSearchInit(searchText, mode, {
      onResult: result => {
        const { ResultCode } = instance.CoreControls.Search;
        if (result.resultCode === ResultCode.FOUND) {
          ...
        }
      },
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.textSearchInit(searchText, mode, {
      onResult: result => {
        const { ResultCode } = instance.iframeWindow.XODText;
        if (result.resultCode === ResultCode.e_found) {
          ...
        }
      },
    });
  });

Deprecated usages

In WebViewer 7.0, we also renamed some constant variables to be more consistent with others. Their previous names are kept for backwards compatibility, though we still encourage you to update them.

• SnapMode

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    console.log(instance.docViewer.SnapMode.DEFAULT);
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    console.log(instance.docViewer.SnapMode.e_DefaultSnapMode);
  });

• SearchResults

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      docViewer.textSearchInit(searchText, mode, {
        onResult: result => {
          const {
            ambientStr,
            resultStr,
            resultStrStart,
            resultStrEnd,
            pageNum,
            resultCode,
            quads,
          } = result;
        },
      });
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      docViewer.textSearchInit(searchText, mode, {
        onResult: result => {
          const {
            ambient_str,
            result_str,
            result_str_start,
            result_str_end,
            page_num,
            resultCode,
            quads,
          } = result;
        },
      });
    });
  });

• SearchMode

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const { Mode } = instance.CoreControls.Search;
      const searchMode = Mode.PAGE_STOP | Mode.HIGHLIGHT | ...;
      instance.docViewer.textSearchInit(searchText, searchMode, ...);
    });
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    instance.docViewer.on('documentLoaded', () => {
      const { SearchMode } = instance.docViewer;
      const searchMode = SearchMode.e_page_stop | SearchMode.e_highlight | ...;
      instance.docViewer.textSearchInit(searchText, searchMode, ...);
    });
  });

• PageRotation

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    console.log(instance.CoreControls.PageRotation.E_0);
  });

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    console.log(instance.CoreControls.PageRotation.e_0);
  });

APIs removed

A few very rarely used APIs have been removed related to CanvasManager canvas modes.

CoreControls.CanvasMode CoreControls.setCanvasMode DocumentViewer.setPagesPerCanvas DocumentViewer.returnCanvas

Other

The fileAttachmentDataAvailable event is now fired on AnnotationManager instead of DocumentViewer.