DOCUMENTATION

Welcome
Getting started
Tutorial
License
Reference
 Events
 Methods
 Helpers

Welcome to Encleso web scanner

Encleso allows you to scan documents direcly from your web browser, save scanned pages from multiple scan sessions, and create downloadable documents from multiple scanned pages, or download single pages as images, in various formats like PDF, Multi-page TIFF, PNG, JPEG, and more other formats.

You can also use Enacleso to scan documents from your own website using Encleso javascript component.

Encleso is compatible with almost any TWAIN-supported scanner.



Getting started

Getting started with Encleso is very easy. Just sign up for a free account, download the Encleso Client Application, and start scanning right away!

In the free mode, you can enjoy the full features of Encleso, but a watermark will be drawn on the scanned pages.

If you like Encleso and want to remove the watermark, head to the License section to learn about how to purchase a full copy of the application.

For developers:

If you are a developer and want to incorporate Encleso to scan from your website, it's also very easy.

After creating a free account and downloading the Encleso Clinet Application as usual, add the following script to your web page: (preferably near the closing </body> tag and before your own scripts) 

                  
<script type="text/javascript" src="https://encleso.com/Assets/scripts/encleso.min.js"></script>
And that's it. You can now use the global Encleso namespace and invoke its class methods.
Read more about this in the following Tutorial and Reference sections.



Tutorial

This section explains how to use Encleso javascript component to scan from your website.

Scripts below depend on JQuery to make the code as little as possible, but generally, JQuery is not needed for using Encleso and its methods, neither it is needed for the Encleso library itself.

The following tutorial scans and saves only one page, in order to keep things simple. However, it can be easily adapted to scan and save multiple images by reading the Reference section.
Note that this may reset your Image Library that you use with Encleso on this site. Also note that the scripts below may lack some error checks, for the same simplicity reasons.


  1. Set event handler functions for Encleso.OnError and Encleso.OnReady events. 
                         
// Set Encleso funtions (OnError() and OnReady())
Encleso.OnError = function(err) {
   // Reset your UI and show error message (from parameter: err.Message)
   // (Optional) Refresh the page after a timeout to re-check
}

Encleso.OnReady = function(ret) {
   // Go through ret.ScannersList and add scanner names to your UI
   var options = '';
   for (let i = 0; i < ret.ScannersList.length; i++) {
      let optSelected = (i == ret.DefaultIndex) ? 'selected' : '';
      options += '<option ' + optSelected + '>' + ret.ScannersList[i] + '</option>';
   }
   $('#ScannerName').html(options);
}
  2. When the user selects a scanner, call Encleso.GetCapabilities() to get the capabilities of the selected scanner: 
                         
function ScannerCombo_OnChange() {
   // Get the name of the currently selected scanner
   var ScannerName = $('#ScannerName option:selected').val();

   // Call Encleso.GetCapabilities() to get the capabilities of that scanner
   Encleso.GetCapabilities(ScannerName).then(ret => {
      // Set your UI according to the received capabilities (ret)
      // i.e. Scanner's supported resolution, pixel mode, etc.
   });
}

  3. After that the user sets the scan configuration (scan resolution, color mode, etc.).

    When the "Start Scan" button is pressed, call these two methods:

    • Encleso.SetCapabilities() to set the needed capabilities according to the user selection.
    • Encleso.StartScan() to start the scan process, and aquire the scanned pages.

    Calling SetCapabilities() method is optional, but it should be called first because it affects the next call of StartScan().

                         
var ScannerName = $('#ScannerName option:selected').val();
var ShowUI = $("#chkShowUI").is(":checked");

// Create 'Caps' object and pass it to the SetCapabilities() method
let Caps = {
   Resolution: $('#resolution option:selected').val(),
   PixelType: $('#colorMode option:selected').val(),
   Duplex: $('#chkDuplex').prop('checked')
};
Encleso.SetCapabilities(Caps);

// Start the actual scan
Encleso.StartScan(ScannerName, ShowUI).then(async (ret) => {
   // If (ret.ScannedImagesCount < 1) This means the scan was canceled
   // Otherwise, show the scanned page
});

    By setting the ShowUI parameter, you can control whether to show the scanner's driver user interface or not.

  4. To show the scanned image, call Encleso.GetImagePreview():

                         
let imgIndex = 0; // Get the first scanned image
Encleso.GetImagePreview(imgIndex).then(ret => {
   $('#outputImage').attr("src", ret);
});

    The ret parameter returns the scanned image data as a javascript Blob object, which is suitable to be used directly in the <img> tag's src attribute.

  5. To save the scanned document to your computer, use Encleso.SaveImageToFilesystem() and supply the image index and the desired file format.

    You can supply formats like PDF, PNG, JPEG, TIFF, and more. Multi-page TIFF and PDF are also supported. 

                         
let format = "png";
Encleso.SaveImageToFilesystem(format, [0]); // Save the first image (index = 0)

This concludes the tutorial, but there are more methods exported from the Encleso class. Read more about them in the License and Reference sections.

You can download the sample source code described in this tutorial from the following button:

(zip file ~3.5 KB)



License

You can use Encleso with all its features for free, but with a watermark which will be drawn on every scanned page.

To remove the watermark, purchase your copy of Encleso by contacting us using the Contact Us form, or sending us an email at: sales@jse.de.

On purchasing, you get a license key.

You need to call Encleso License API from your website's back-end, and pass your license key. The API will return a license token, which you need to pass to your page's javascript, and call Encleso.SetLicense() from within Encleso.OnReady event handler.

This will insure applying your purchased license and remove the watermark from your scans.

Exposing the license tokens to the front-end is not a problem, as these tokens are used for one time only, valid only for a limited time, and work only with your "allowed origin" that you specify when ordering the license key.

Please, keep your license key safe in your back-end.

Let's see a practical example:

  1. From your back-end, call the License API and pass your License Key.

    • The API end-point is: https://encleso.com/API/SetLicenseKey.
    • Use POST HTTP method.
    • Send Key = YOUR-LICENSE-KEY as FormData with the POST request.
    • Make sure to send the request from your "allowed origin".

                               
$url = 'https://encleso.com/API/SetLicenseKey'; // The license API endpoint
$data = ['Key' => 'xxx-your-license-key-xxx']; // Replace this by your key
$headers = "Content-type: application/x-www-form-urlencoded\r\n";
$headers .= "Origin: https://yoursite.com\r\n"; // Replace this by your site origin

// Use key 'http' even if you send the request to https://...
$options = [
   'http' => [
      'header' => $headers,
      'method' => 'POST',
      'content' => http_build_query($data)
   ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === false) {
   // Handle error
}

$jsonRes = json_decode($result);

// Output the received token to your javascript, passing it to Encleso.SetLicense()
echo 'const TOKEN = "' . $jsonRes->token . '";';
                              
                           
                               
using System;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;

class MyClass
{
   static async Task SendLicenseRequest()
   {
      HttpClient client = new HttpClient();
      client.DefaultRequestHeaders.Add("Content-type", "application/x-www-form-urlencoded");
      client.DefaultRequestHeaders.Add("Origin", "https://yoursite.com"); // Replace by your site origin
         
      var values = new Dictionary<string, string>
      {
         { "Key", "xxx-your-license-key-xxx" } // Replace this by your key
      };
      var content = new FormUrlEncodedContent(values);

      // The license API endpoint
      var response = await client.PostAsync("https://encleso.com/API/SetLicenseKey", content);
      var responseString = await response.Content.ReadAsStringAsync();
      dynamic respJson = JsonConvert.DeserializeObject(responseString);

      // Output the received token to your javascript, passing it to Encleso.SetLicense()
      string token = (string)respJson.token;
   }
}
                              
                           
                               
const https = require('https'); // Using the native https module

const data = JSON.stringify({
   Key: 'xxx-your-license-key-xxx' // Replace by your key
});

const options = {
   path: 'https://encleso.com/API/SetLicenseKey', // API endpoint
   method: 'POST',
   headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Origin': 'https://yoursite.com' // Replace by your site origin
   }
};

const req = https.request(options, (res) => {
   let data = '';
   res.on('data', (chunk) => { data += chunk; });

   res.on('end', () => {
      // Output the received token to your frontend javascript, passing it to Encleso.SetLicense()
      var token = JSON.parse(data).token;
   });
}).on('error', (err) => {
   // Handle errors
   console.log("Error: ", err.message);
});

req.write(data);
req.end();
                              
                           
                               
require 'uri'
require 'net/http'
require 'net/https'
require 'json'

@toSend = {
   "Key" => "xxx-your-license-key-xxx" # Replace by your key
}.to_json

uri = URI.parse("https://encleso.com/API/SetLicenseKey") # API endpoint
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req['Origin'] = 'https://yoursite.com' # Replace by your site origin
req.body = "[ #{@toSend} ]"
res = https.request(req)

# Output the received token to your frontend javascript, passing it to Encleso.SetLicense()
puts res.body.token
                              
                           
                               
import requests
import json

url = 'https://encleso.com/API/SetLicenseKey' # API endpoint

headers = {
   "Content-Type": "application/x-www-form-urlencoded",
   "Origin": "https://yoursite.com", # Replace by your site origin
}

payload = {
   "Key": "xxx-your-license-key-xxx" # Replace by your key
}

r = requests.post(url, data=json.dumps(payload), headers=headers)

# Output the received token to your frontend javascript, passing it to Encleso.SetLicense()
print(r.content.token)

    Notes:

    • The "Origin" header will be further checked by our servers. You must provide the correct origin, which was provided when you ordered the license key.
    • The scripts above are minimal to get you in the track. You should always use best practices, handle errors, and consider security.

  2. Add the line await Encleso.SetLicense(TOKEN); passing your received token from the previous step, inside the Encleso.OnReady event handler: 

                         
Encleso.OnReady = async function(ret) {
   await Encleso.SetLicense(TOKEN); // Put your token here

   // The rest of the function
}

    Note that we used the async keyword in the event handler definition, to be able to use SetLicense() as a waitable method.


That's it. If you provide the correct credentials, your license will be applied automatically and the watermark will be removed.



Reference

This section describes Encleso javascript library's exported class methods in details.

General notes:

  • Almost all Encleso class methods are awaitable functions. You are adviced to define your functions as async, and add the await keyword in front of Encleso methods.
  • You should be familiar with the TWAIN specification to make the best use of this section.

Events:


Encleso.OnError
Description Fired when an error occurs, like error in connection with the Clinet App or other reasons described below.
Usage Encleso.OnError = function(err) { }

Encleso calls your handler function with the err parameter that contains 2 properties:
  • err.Code (number)
  • err.Message (string)
Refer to the Encleso.ErrorCodes enumertaion below for a list of possible values.

Encleso.OnReady
Description Fired when the library has established a connection with the ClinetApp, and has read a list of installed scanners in the system.
Usage Encleso.OnReady = function(ret) { }

Encleso calls your handler function with the ret parameter that contains 2 properties:
  • ret.ScannersList (array of strings)
    An array of detected scanner names.
  • ret.DefaultIndex (number)
    The index of the default scanner in the system.

Methods:


Encleso.GetCapabilities(ScannerName)
Description Returns multiple capability values related to the selected scanner. (awaitable function)
Usage Encleso.GetCapabilities(ScannerName).then(function(ret) { })

Parameters:

  • ScannerName (string) The name of the scanner, as obtained in the OnReady event handler.

The ret parameter is a JSON object that contains the following properties:

  • Resolution The supported resolution (DPI) of the scanner.
  • PixelType The pixel type or color mode types supported.
  • Duplex Indicates capability support for duplex scanning mode.
  • Feeder Indicates capability support for automatic paper feeder.
  • AutoRotate Indicates capability support for automatic rotation.
  • AutoDeskew Indicates capability support for automatic de-skew.
  • AutoDiscardBlankPages Indicates capability support for automatic discarding of blank pages.
  • AutoBrightness Indicates capability support for automatic brightness.

The Resolution and PixelType properties consist of a JSON object with the following properties:

  • Values (array of numbers) The DPI resolution.
  • CurrentIndex (number) The index of the default value.
  • ChangeAllowed (boolean) Whether the scanner supports changing the value.

The Values property of the PixelType has numeric values of the TWAIN.PixelType enumertaion. You can use the Encleso.PixelTypeToString() function to convert the numeric values to their textual representative.

The Duplex property consists of a JSON object with the following properties:

  • Supported (boolean) Whether the scanner supports duplex mode.
  • Enabled (boolean) Whether the duplex mode is currently enabled.
  • Type (numeric) One of the TWAIN.Duplex enumeration values.
  • ChangeAllowed (boolean) Whether the scanner supports changing the value.

The Feeder, AutoRotate, AutoDeskew, and AutoBrightness properties consist of a JSON object with the following properties:

  • Supported (boolean) Whether the scanner supports duplex mode.
  • Enabled (boolean) Whether the duplex mode is currently enabled.
  • ChangeAllowed (boolean) Whether the scanner supports changing the value.

The AutoDiscardBlankPages property consists of a JSON object with the following properties:

  • Supported (boolean) Whether the scanner supports duplex mode.
  • Enabled (boolean) Whether the duplex mode is currently enabled.
  • Value (numeric) One of the TWAIN.AutoDiscardBlankPages enumeration values.
  • ChangeAllowed (boolean) Whether the scanner supports changing the value.

Encleso.GetCapability(ScannerName, CapId, CapMsg)
Description Returns a single capability value related to the selected scanner. (awaitable function)
This method is useful if you want to get a capability beyond those retrieved by Encleso.GetCapabilities().
Usage Encleso.GetCapability(ScannerName, CapId, CapMsg).then(function(ret) { })

Parameters:

  • ScannerName (string) The name of the scanner, as obtained in the OnReady event handler.
  • CapId (numeric) One of the TWAIN.CapId enumeration values.
  • CapMsg (numeric) One of the TWAIN.CapMsg enumeration values.

The ret parameter is a JSON object that contains the following properties:

  • Success (boolean) Whether the scanner has responded successfully.
  • ContType (numeric) One of the TWAIN.CapContType enumeration values.
  • Value Depends on the requested CapId and CapMsg, and the returned ContType.

Check the value of the ContType to determine the type of the Value property:

When ContType is Value type
TWAIN.CapContType.TWON_ONEVALUE Value (one value)
Its data type depends on the requested CapId and CapMsg.
TWAIN.CapContType.TWON_ARRAY, or
TWAIN.CapContType.TWON_ENUMERATION 		Value (array of values)
Their data type depends on the requested CapId and CapMsg.
TWAIN.CapContType.TWON_RANGE Value (one value) It is a JSON object that contains the following properties:
  • MinValue (numeric)
  • MaxValue (numeric)
  • StepSize (numeric)

Consult the TWAIN specification to learn about Capability Ids, Capability Messages, Container types, and value types.

Encleso.SetCapabilities(Caps)
Description Sets multiple capability values to be applied on the next call to Encleso.StartScan().
Usage Encleso.SetCapabilities(Caps)

Create and provide the Caps parameter like the following:
                           
let Caps = {
   Resolution: 200,                       // The X and Y DPI resolution
   PixelType: TWAIN.PixelType.TWPT_RGB,   // Set PixelType to RGB Color
   Duplex: true,                          // Enable Duplex mode
   Feeder: true,                          // Enable automatic paper feed
   AutoRotate: false,                     // Disable automatic rotation
   AutoDeskew: false,                     // Disable automatic de-skew
   AutoDiscardBlankPages: true,           // Discard blank pages
   AutoBrightness: true                   // Adjust brightness automatically
}

// Call the method with the created Caps object
Encleso.SetCapabilities(Caps);

Caps's properties are optional, but you should provide at least one if you want to call this method.

This method has no return value.

Encleso.SetCapability(CapId, ValType, Value)
Description Sets a single capability value. Like Encleso.SetCapabilities(), the capability will be applied on the next call to Encleso.StartScan().
Usage Encleso.SetCapability(CapId, ValType, Value)

Parameters:

  • CapId (numeric) One of the TWAIN.CapId enumeration values.
  • ValType (numeric) One of the TWAIN.CapValType enumeration values.
  • Value Its data type depends on the ValType property.
When ValType is Value should be of type
TWAIN.CapValType.TWTY_INT8,
TWAIN.CapValType.TWTY_INT16,
TWAIN.CapValType.TWTY_INT32,
TWAIN.CapValType.TWTY_UINT8,
TWAIN.CapValType.TWTY_UINT16,
TWAIN.CapValType.TWTY_UINT32,
TWAIN.CapValType.TWTY_FIX32, or
TWAIN.CapValType.TWTY_HANDLE 		Value (numeric).
TWAIN.CapValType.TWTY_BOOL Value (boolean).
TWAIN.CapValType.TWTY_FRAME Value (JSON Object) It should be a JSON object that has the following properties:
  • Left (numeric)
  • Top (numeric)
  • Right (numeric)
  • Bottom (numeric)
TWAIN.CapValType.TWTY_STR32,
TWAIN.CapValType.TWTY_STR64,
TWAIN.CapValType.TWTY_STR128, or
TWAIN.CapValType.TWTY_STR255 		Value (string).
(Respecting the string length)

This method has no return value.

Encleso.StartScan(ScannerName, ShowUI)
Description Starts the actual scan process. Takes into account any previous call to Encleso.SetCapability() and Encleso.SetCapabilities(). (awaitable function)
Usage Encleso.StartScan(ScannerName, ShowUI).then(function(ret) { })

Parameters:

  • ScannerName (string) The name of the scanner, as obtained in the OnReady event handler.
  • ShowUI (boolean) Whether to show the scanner's driver user interface.

The ret parameter is a JSON object that contains the following property:

  • ScannedImagesCount (numeric) The count of successfully scanned images/pages.
  • ScannedImagesStartingIndex (numeric) The index of the first scanned image in the ImageLibrary.
  • TotalImagesCount (numeric) The total count of images in the Image Library (after the scan).

After scan, this method adds the newly scanned pages to the Image Library. Properties of the ret object reflect the updated Image Library.

Encleso.SetLicense(token)
Description Sets your license information to activate the full version of Encleso. (awaitable function)
Usage await Encleso.SetLicense(token)

Parameters:

  • token (string) The license token that you receive from the call to Encleso License API.

    You need to call Encleso License API from your website's back-end, which will return a license token. Pass the token to your front-end, and pass it as a parameter to this method.

    For more information, refer to the License section.

Returns: This method has no return value.

Encleso.ImageLibGetCount()
Description Gets the total count of scanned images/pages in the Imagelibrary. (awaitable function)
Usage await Encleso.ImageLibGetCount()

Parameters: none.

Returns: (numeric) The count of images in the Image Library.


Encleso.ImageLibRemove(idxList)
Description Deletes one or more images/pages from the Image Library. (awaitable function)
Usage Encleso.ImageLibRemove(idxList).then(function(ret) { })

Parameters:

  • idxList (array of numbers) Array of image indices in the Image Library, to be deleted (not necessarily sequential).
    You can pass the array [0, 3] to delete 2 images of indices 0 and 3, respectively.

    Make sure to pass only valid indices otherwise the deletion fails. Check with Encleso.ImageLibGetCount() to make sure you don't pass any outbound index.

The ret parameter is a JSON object that contains the following property:

  • RemovedImageCount (numeric) Number of successfully deleted images.
  • NewCount (numeric) The new count of images in the Image Library (after deletion).

Encleso.GetImagePreview(imgIndex)
Description Gets a preview of one on the scanned images in the Imagelibrary. (awaitable function)
Usage Encleso.GetImagePreview(imgIndex).then(function(ret) { })

Parameters:

  • imgIndex (numeric) The index of the required image in the Image library.

The ret parameter is a binary Blob data, which can be used directly in the src attribute of an <img> tag.


Encleso.GetImageThumbnail(imgIndex)
Description Gets a thumbnail image of one on the scanned images in the Imagelibrary. (awaitable function)
Usage Encleso.GetImageThumbnail(imgIndex).then(function(ret) { })

Parameters:

  • imgIndex (numeric) The index of the required thumbnail image in the Image library.

The ret parameter is a binary Blob data, which can be used directly in the src attribute of an <img> tag.


Encleso.GetImagesAsPrintablePdf(idxList)
Description Allows you to get a pdf data consisting of one or more images from the Image library. Suitable for printing (awaitable function)
Note: To save a PDF file to your computer, use the Encleso.SaveImageToFilesystem() method instead of this one.
Usage await Encleso.GetImagesAsPrintablePdf(idxList)

Parameters:

  • idxList (array of numbers) Array of image indices in the Image Library. (not necessarily sequential).

Returns a binary Blob representing the pdf file for printing.

The Encleso.SaveImageToFilesystem() method is preferred if you want to get a PDF to save to your computer.

Encleso.SaveImageToFilesystem(format, idxList)
Description Allows you to save one or more images/pages in the Image Library as one of the supported file formats, to your computer. (awaitable function)
Usage Encleso.SaveImageToFilesystem(fileFormat, idxList)

Parameters:

  • fileFormat (string) one of the supported formats, as the following:
    fileFormat value Meaning
    'png' PNG image (single image)
    'jpg' JPEG image (single image)
    'tiff-single' TIFF image (single image)
    'tiff-multi' TIFF image (multi-page image)
    'bmp' Bitmap image (single image)
    'pdf-single' PDF document (single image)
    'pdf-multi' PDF document (multi-page document)
  • idxList (array of numbers) Array of image indices in the Image Library, from which the file will be created (not necessarily sequential).

    Make sure to pass only valid indices otherwise the save fails. Check with Encleso.ImageLibGetCount() to make sure you don't pass any outbound index.

Returns: none.

This method initiates a download operation that saves your image/images as a file/files to your computer in the requested format.

Helper methods:


Encleso.PixelTypeToString(twainPixelTypeVal)
Description Gets a textual representative of one of the TWAIN's pixel types.
Usage Encleso.PixelTypeToString(twainPixelTypeVal)

Parameters:

  • twainPixelTypeVal (numeric) One of the TWAIN.PixelType enumeration values.

Returns: (string) The textual representative of the passed TWAIN.PixelType value.

We use Cookies to provide the best experience and security for our users. By continueing to use the website you consent to our cookies.