> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/web/migration-guides/migrating-to-v7.md).

# Migrating to V7 of WebViewer

Migrate smoothly to WebViewer 7.0

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](https://sdk.apryse.com/api/web/WebViewerInstance.html#setToolbarGroup__anchor) and you can edit each group using the [getHeader](https://sdk.apryse.com/api/web/UI.Header.html#getHeader__anchor) function.

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```js
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
        }
      });
    });
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

If you want to hide a specific toolbar group, like other DOM elements, they can be hidden by using [disableElements](https://sdk.apryse.com/api/web/WebViewerInstance.html#disableElements__anchor).

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

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.

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

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

});
```

{% endcode %}
{% endtab %}
{% endtabs %}

### 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](https://sdk.apryse.com/api/web/Core.AnnotationManager.html) and [DocumentViewer](https://sdk.apryse.com/api/web/Core.DocumentViewer.html) these were already taking in 1-indexed page numbers. If you were using APIs on the [Document](https://sdk.apryse.com/api/web/Core.Document.html) object these were taking in 0-indexed page numbers.

Below are some examples of the changes:

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

```js
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);
    });
  });
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

```js
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);
    });
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

The following APIs have been changed to use page numbers:

* [pageComplete](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#event:pageComplete__anchor)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

* DocumentViewer [textSelected](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#event:textSelected)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

* TextTool [textSelected](https://sdk.apryse.com/api/web/Core.Tools.TextTool.html#textSelected)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

* [getSelectedPages](https://sdk.apryse.com/api/web/Core.DisplayMode.html#getSelectedPages)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

```js
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;
  });
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

```js
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;
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

* [pageCoordinates](https://sdk.apryse.com/api/web/Core.Tools.PageCoordinate.html#PageCoordinate)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

* [SearchResult](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#.SearchResults)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

* [pageToWindow](https://sdk.apryse.com/api/web/Core.DisplayMode.html#pageToWindow)
* [windowToPage](https://sdk.apryse.com/api/web/Core.DisplayMode.html#windowToPage)
* [getPageTransform](https://sdk.apryse.com/api/web/Core.DisplayMode.html#getPageTransform)
* [getPageOffset](https://sdk.apryse.com/api/web/Core.DisplayMode.html#getPageOffset)
* [getLinks](https://sdk.apryse.com/api/web/Core.Document.html#getLinks)
* [getPageInfo](https://sdk.apryse.com/api/web/Core.Document.html#getPageInfo)
* [getPDFCoordinates](https://sdk.apryse.com/api/web/Core.Document.html#getPDFCoordinates)
* [getTextPosition](https://sdk.apryse.com/api/web/Core.Document.html#getTextPosition)
* [getXODCoordinates](https://sdk.apryse.com/api/web/Core.Document.html#getXODCoordinates)
* [getViewerCoordinates](https://sdk.apryse.com/api/web/Core.Document.html#getViewerCoordinates)
* [loadPageText](https://sdk.apryse.com/api/web/Core.Document.html#loadPageText)
* [loadThumbnailAsync](https://sdk.apryse.com/api/web/Core.Document.html#loadThumbnailAsync)
* [getPageMatrix](https://sdk.apryse.com/api/web/Core.Document.html#getPageMatrix)
* [getPageWidth](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#getPageWidth)
* [getPageHeight](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#getPageHeight)
* [getPageRotation](https://sdk.apryse.com/api/web/Core.Document.html#getPageRotation)
* [getPageRotations](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#getPageRotations)
* [setPageRotations](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#setPageRotations)
* [getPageZoom](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#getPageZoom)
* [setPageZoom](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#setPageZoom)
* [getViewportRegionRect](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#getViewportRegionRect)
* [updateLinks](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#updateLinks)
* [stopPageRender](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#stopPageRender)
* [loadCanvasAsync](https://sdk.apryse.com/api/web/Core.Document.html#loadCanvasAsync)
* [getVisiblePages](https://sdk.apryse.com/api/web/Core.DisplayMode.html#getVisiblePages)
* [updateView](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#updateView)

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

* `#pageContainer`
* `#pageWidgetContainer`

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### 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.

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### 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.

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

## 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](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#SnapMode)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

* [SearchResults](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#.SearchResults)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

```js
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;
        },
      });
    });
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

* [SearchMode](https://sdk.apryse.com/api/web/Core.Search.html)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

```js
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, ...);
    });
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

* [PageRotation](https://sdk.apryse.com/api/web/Core.html#.PageRotation)

{% tabs %}
{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v6.0+)" %}
{% code lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

## 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](https://sdk.apryse.com/api/web/Core.AnnotationManager.html#event:fileAttachmentDataAvailable__anchor) event is now fired on AnnotationManager instead of DocumentViewer.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/web/migration-guides/migrating-to-v7.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.