Dev Center
Table of contents

Thanks for Downloading Dynamic Web TWAIN 30-Day Trial!

Your download will start shortly. If your download does not begin, click here to retry.

Configuring the Viewer

Prerequisite: DWT Initialization

The Viewer component of the WebTwain instance is responsible for displaying scanned documents, and all other UI features. This guide explains how to configure Viewer behavior.

Configuring Viewer Instantiation

Configuring Built-in Viewers

The default WebTwain instance automatically creates its own Viewer instance with default settings - the Viewer is bound to the HTML <div> element with id=dwtcontrolContainer and specified display size, which are defined by the Dynamsoft.DWT.Containers. We go over this process in detail in the DWT Initialization article. We can configure the Viewer’s id and display size by altering the configuration resource file dynamsoft.webtwain.config.js. Modify the existing Dynamsoft.DWT.Containers property as shown below:

Sample Code

Relevant Snippet from dynamsoft.webtwain.config.js
Dynamsoft.DWT.Containers = [{
    ContainerId: 'customDivID', // New default div id
    Width: '800px', // New initial Viewer pixel width
    Height: '600px' // New initial Viewer pixel height
}]
HTML
<html>
    <head>
        <!-- Initialize DWT by loading resource files, and instantiate WebTwain object behind-the-scenes -->
        <script src="Resources/dynamsoft.webtwain.config.js"></script>
        <script src="Resources/dynamsoft.webtwain.initiate.js"></script>
    </head>

    <body>
        <input type="button" value="Scan" onclick="AcquireImage();" /><br>
        <div id="customDivID"></div> <!-- The WebTwain object binds to this div by default -->
        <script>
            let DWTObject; // Use this to store the WebTwain object after retrieval

            // Retrieve WebTwain object after initializing DWT
            Dynamsoft.DWT.RegisterEvent("OnWebTwainReady", function () {
                DWTObject = Dynamsoft.DWT.GetWebTwain("customDivID"); // Retrieve instantiated WebTwain object with new div ID
            });

            // Scan image
            function AcquireImage() {
                if (DWTObject) {
                    DWTObject.SelectSourceAsync().then(
                        function () {
                            return DWTObject.AcquireImageAsync(
                                { IfCloseSourceAfterAcquire: true }
                            );
                        }
                    ).catch(function (exp) {
                        alert(exp.message);
                    });
                }
            }
        </script>
    </body>
</html>

APIs used:

Explanation

In the DWT configuration resource file, we changed the <div> container ID to customDivID, and set new dimensions for the default Viewer using the Dynamsoft.DWT.Containers property. (which contains Containers) During DWT initialization, not only does the containerId bind the default Viewer, it also acts as an identifier for the default WebTwain instance. Consequently, we must use customDivID with Dynamsoft.DWT.GetWebTwain() to get the default WebTwain instance once it has been created.

Binding a Viewer to a WebTwain Instance

To further customize a Viewer, we create a WebTwain instance that does not have a Viewer component, then bind a custom Viewer to it. In this example, we create a WebTwain instance with a viewer that also displays thumbnails to its side.

Relevant Snippet from dynamsoft.webtwain.config.js
Dynamsoft.DWT.Containers = []
Dynamsoft.DWT.AutoLoad = false;
HTML
<html>
    <head>
        <!-- Initialize DWT by loading resource files, and instantiate WebTwain object behind-the-scenes -->
        <script src="Resources/dynamsoft.webtwain.config.js"></script>
        <script src="Resources/dynamsoft.webtwain.initiate.js"></script>
    </head>

    <body>
        <input type="button" value="Scan" onclick="AcquireImage();" /><br/>
        <div id="customDivID"></div> <!-- The WebTwain object binds to this div by default -->
        <script>
            let DWTObject; // Use this to store the WebTwain object after retrieval

            // Create headless WebTwain instance and bind viewer after initializing DWT
            Dynamsoft.DWT.CreateDWTObjectEx({
                    WebTwainId: "customWebTwainID" // Identifier for WebTwain instance
                },
                function (createdDWTObj) {
                    DWTObject = createdDWTObj; // Get the WebTwain instance
                    DWTObject.Viewer.bind(
                        document.getElementById("customDivID")
                    ); // Create a Viewer, bind to the WebTwain instance and the div
                    DWTObject.Viewer.height = 600;
                    DWTObject.Viewer.width = 800;
                    let thumbnailViewer =
                        DWTObject.Viewer.createThumbnailViewer(); // Create a thumbnail viewer bound to the WebTwain instance
                    thumbnailViewer.show();
                    DWTObject.Viewer.show();
                },
                function (err) {
                    console.log(err);
                }
            );

            // Scan image
            function AcquireImage() {
                if (DWTObject) {
                    DWTObject.SelectSourceAsync().then(
                        function () {
                            return DWTObject.AcquireImageAsync(
                                { IfCloseSourceAfterAcquire: true }
                            );
                        }
                    ).catch(function (exp) {
                        alert(exp.message);
                    });
                }
            }
        </script>
    </body>
</html>

APIs used:

Explanation

To demonstrate Viewer binding, we first create a Viewer-less (headless) WebTwain instance. We must first prevent DWT from creating a default-configured WebTwain instance (auto-loading) during its initialization stage, as this instance comes with a Viewer. We can clear Dynamsoft.DWT.Containers and set Dynamsoft.DWT.AutoLoad false in the configuration dynamsoft.webtwain.config.js resource file to prevent auto-loading.

We then use CreateDWTObjectEx() to create the desired custom WebTwain instance without a Viewer. In the success callback of CreateDWTObjectEx(), we then customize its features, namely its Viewer and ThumbnailViewer. This is the key point of this sample.

bind() simultaneously creates the Viewer instance, binds it to the WebTwain instance that it was called from, and also binds it to the HTML container by container id. This Viewer instance is then accessible using the Viewer property from the WebTwain instance. For example, DWTObject.Viewer.height is the height of the Viewer.

Likewise, after the Viewer has been instantiated and bound, we can create a thumbnail viewer in the Viewer by accessing the createThumbnailViewer() function provided within the Viewer instance. Finally, we display both the Viewer and ThumbnailViewer on screen with their respective show() APIs.

Note: The Viewer is always bound to a WebTwain instance. As such, the Viewer and its properties must always be accessed as a property of a WebTwain instance.

Interacting with the Viewer

Users can interact with the Viewer graphically to work with scanned documents. These interactions also have APIs which can be called directly. Here is a non-exhaustive list of commonly used interactive features, along with their associated APIs (accessed from its parent WebTwain instance):

Here is a rudimentary sample that demonstrates page movement APIs:

Sample Code

<html>
    <head>
        <!-- Initialize DWT by loading resource files, and instantiate WebTwain object behind-the-scenes -->
        <script src="Resources/dynamsoft.webtwain.config.js"></script>
        <script src="Resources/dynamsoft.webtwain.initiate.js"></script>
    </head>

    <body>
        <input type="button" value="Scan" onclick="AcquireImage();" /><br>
        <div id="customDivID"></div> <!-- The WebTwain object binds to this div by default -->
        <!-- Buttons to demonstrate Viewer API calls -->
        <input
            type="button"
            value="Next page"
            onclick="DWTObject.Viewer.next();"
        /><br>
        <input
            type="button"
            value="Previous page"
            onclick="DWTObject.Viewer.previous();"
        /><br>
        <input
            type="button"
            value="First page"
            onclick="DWTObject.Viewer.first();"
        /><br>

        <script>
            let DWTObject; // Use this to store the WebTwain object after retrieval

            // Retrieve WebTwain object after initializing DWT
            Dynamsoft.DWT.RegisterEvent("OnWebTwainReady", function () {
                DWTObject = Dynamsoft.DWT.GetWebTwain("customDivID"); // Retrieve instantiated WebTwain object with new div ID
            });

            // Scan image
            function AcquireImage() {
                if (DWTObject) {
                    DWTObject.SelectSourceAsync().then(
                        function () {
                            return DWTObject.AcquireImageAsync(
                                { IfCloseSourceAfterAcquire: true }
                            );
                        }
                    ).catch(function (exp) {
                        alert(exp.message);
                    });
                }
            }
        </script>
    </body>
</html>

APIs used:

Is this page helpful?

YesYes NoNo

In this article:

latest version

    • Latest Version (18.5.1)
    • Version 18.4
    • Version 18.3
    • Version 18.1
    • Version 18.0
    • Version 17.3
    • Version 17.2.1
    • Version 17.1.1
    • Version 17.0
    • Version 16.2
    • Version 16.1.1
    Change +