Tutorial: Connect to UI Controls

The Web Scanning control automatically finds and connects to UI controls using their class identifiers, so it is sufficient for you to add, lay out and style the UI controls required by your application, and assign the appropriate classes to those controls.

Automatic controls connection is optional and could be completely replaced with custom application UI using corresponding API call.

Controls are connected on WebCaptureService initialization and could be unbound by disposing WebCaptureService.

Scan controls are divided into two groups. Following class identifiers are supported

Scan Controls
- atala-scanner-list
  
  select DOM element that will contain list of available scanner devices and the current visible selection will be used when a scan is initiated. If scanning is not possible or there are no scanners available, this control will be disabled.
```
<select class="atala-scanner-list" disabled="disabled" name="scannerList">
    <option selected="selected">(no scanners available)</option>
</select>
```
  Note, If the contents of the control were changed programmatically (for example, WIA scanners were filtered out of the list using jQuery), the currently selected value may not reflect the currently selected scanner. To synchronize the two, the onchange event should be manually triggered on the control.
- atala-scan-button
  
  button DOM element that triggers scanning with the current scanner and document selections.
```
<input type="button" class="atala-scan-button" value="Scan" />
```
- atala-local-file-import-button
  
  button DOM element that triggers local file import.
```
<input type="button" class="atala-local-file-import-button" value="Import" />
```
Capture controls
- atala-content-type-list
  
  Kofax Import Connector content types libraries.
  
  This control is automatically loaded with the list of available content types provided by the Kofax Import Connector (KIC) server, and the current visible selection is used when an import is initiated.
  If a connection cannot be established to the KIC server, this control is disabled.
```
<select class="atala-content-type-list"></select>
```
- atala-content-type-document-list
  
  Kofax Import Connector content type descriptions. This control is automatically loaded with the list of available content type descriptions as provided by the Kofax Import Connector server, and the current visible selection is used when a scan is initiated.
  If a connection cannot be established to the Kofax Import Connector server, this control is disabled.
```
<select class="atala-content-type-document-list"></select>
```
- atala-import-button
  
  Kofax Import Connector import button.
  
  This button is automatically enabled if KIC import is possible, and is disabled otherwise. When the user clicks it, a KIC import (of the last scanned document) is initiated.
```
<input type="button" class="atala-import-button" value="Import" />
```
- atala-indexfield-list
  
  Kofax Import Connector IndexFields. A table will with the index fields names for a label, and a text input will be constructed at this div.
```
<div class="atala-indexfield-list" style="width:600px; height:250px; overflow:scroll; border:solid 1px #CCC;"></div>
```
- atala-batchfield-list
  
  Kofax Import Connector Batch Fields. A table with the batch fields names for a label, and a text input will be constructed at this div.
```
<div class="atala-batchfield-list" style="width:600px; height:250px; overflow:scroll;
border:solid 1px #CCC;"></div>
```
- atala-import-index-field-button
  
  Kofax Import Connector Import With Index Fields Button.
  
  This button is automatically enabled if import is possible, and is disabled otherwise.
  
  When the user clicks it, an import (of the last scanned document) along with any entered index field values into Kofax Import Connector is initiated. One should also note, that any "button" that has a type="submit" will create an empty POST that will override any POST or GET that the web scanning control sends.
- atala-track-import-button
  
  Kofax Import Connector track import button. When the user clicks it, the status of the last import is returned.
```
<input type="button" class="atala-track-import-button" value="Track Import" />
```

Document Capture configuration

Filter selection lists

Use the removedContenTypes, and removedContentTypeDescriptions initialization parameter to filter the lists displayed in the atala-contentype-list, and atala-contenttype-document-list.


Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    loosePages: "true",
    removedContentTypes: "KfxSingleMessageBatch",
    removedContentTypeDescriptions: "KfxMultiDocument / NWestMulti",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); }
});

Connect controls with no UI

When using the client controls to connect to Kofax Capture through Kofax Import Connector, and it is not desired to have the content type/repository name selection boxes on the page,then a value can be passed through the capture service's initialize parameters.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    contentType: 'AtalasoftEngineering',
    batchFields: "BatchField1:value1, BatchField2:value2",
    contentTypeDescriptionName: 'Engineering / TestDocument',
    indexFields: "IndexField1: value1, IndexField2: value2",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); }
});

At a minimum the contentType must be specified for all document imports into Kofax Capture through Kofax Import Connector.

Import lose pages

When connecting to Kofax Capture (KC) via the Kofax Import Connector (KIC) a loose page can be imported by not selecting or specifying a document class/ form type combination when importing a document via the web scanning client, and by having the loosePages initialization parameter set to true. By default this parameter is set to false. When set to true by default a blank option will be added to the atala-contenttype-document-list (when available).

With UI

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    loosePages: "true, Loose Page: Test",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
    onImportCompleted: function(params) { console.log(params.id + ": " + params.status); }
});

Note, With UI assumes that batch fields will be displayed, along with the atala-contenttype-list, and atala-contenttype-document-list.

Without UI

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    contentType: 'AtalasoftEngineering',
    batchFields: "BatchField1:123, BatchField2:321",
    contentTypeDescriptionName:'',
    loosePages: "true",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); }
});

Index fields

Required fields

Kofax Import Connector has required index fields that need to be set for an import of a document into them to be successful. When the list of index fields is retrieved from the server the required field information is included with that information, and a class is added to the label of that index field. The class that gets added is:

class="atala-indexfield-required"

Hidden fields

Index fields in KC have an optional flag called hidden, when this is set to true in KC the field that it is applied to will have the following class applied to it:

class="atala-field-hidden"

Index field list filtering

As part of the Atalasoft.WebScanning.CaptureService.Initialize list of parameters that get passed in includes a mechanism to provide a list of the index fields that should be displayed in the generated table of index fields.

In the example below the parameter displayedIndexFields specifies the list of index field that should be included for display. Only the index fields with named: "Name", "Title", and "Content type" will be displayed.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'DemoHandler.ashx',
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
    onImportCompleted: function(params) { console.log(params.id + ": " + params.status); },
    onTrackStatusReceived: function(params) { console.log("Import status: " + params); },
    displayedIndexFields: 'Name, Title, Content Type'
});

Set index field values without connecting to UI

As with content types, and content type descriptions indexfields can also be passed in through to the import POST parameters via the Atalasoft.Controls.Capture.CaptureService.initialize call.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'DemoHandler.ashx',
    contentType: 'Documents',
    contentTypeDescriptionName: 'Document',
    indexFields: "Name: Adam, Title: Q3 results , Content Type: "
});

The "indexFields" parameter takes a string where the index fields are comma separated with the name of the particular index field separated from the value being assigned to it by a ':', so indexField1: indexfieldValue1, indexfield2:indexfieldvalue2, ...

Index field validation

Client side validation

Any index field value validation beyond checking that required fields have values prior to import should be handled via the onIndexFieldTypeValidationStatus parameter in the Atalasoft.Controls.Capture.CaptureService.initialize setup.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'DemoHandler',
    contentType: 'Documents',
    contentTypeDescriptionName: 'Document',
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
    onImportCompleted: function(params) { console.log(params.id + ": " + params.status); },
    onTrackStatusReceived: function(params) { console.log("Import status: " + params.status); },
    onIndexFieldImportValidationError: function(error, validationResults) {
        // validationResults is the array containing true/false flags for corresponding(by indexes) index fields
        console.log(error); 
    },
    onIndexFieldTypeValidationStatus: function(params) { fieldTypeValidation(params); }
});

function fieldTypeValidation(params) {
    // do something with params
    console.log(params);
}

Where the function fieldTypeValidation(params) is a function elsewhere in the page that performs the additional index field input validation that could be run before importing. An example of this function is available in the WebCapture demo project included with the installer.

Server side validation

Validation on the server side checks that the index field input values are of the correct form for the culture specified in the web.config. By default the handler will use the default culture of the server.

Handling validation error events in the client

As with the other import, and track status events index field validation has an onIndexFieldImportValidationError event that can be used to return information to the client in the case that a input value has been deemed invalid. See the WebCapture demo for an example.

Skin the generated table

It is possible to "skin" the generated table of index fields to suit the needs of the design aesthetic of the site.

Generated Table of index fields

Once connected to the UI (see Connect to UI Controls) a table will be added as a child to the <div class="atala-indexfield-list"/> with id="atala-indexfield-table" applied to it. The table has an specific id applied to it as do the index field labels, and input fields. Each input field will have an id applied to it as well, and will be in the form of id="<indexfieldname>_inputId"

Required index field values

Required index field have a class applied to them, class="atala-indexfield-required" for an example of how to use this to apply a red '*' to the beginning of the label name see the Web Capture demo included with the installation.

Batch fields

Batch Fields are much like index fields. They have the same hidden, and required class associated with them, and can be used to add meta data to loose pages imports into Kofax Capture.

Display and enter values

Batch fields get displayed in the same <div> as index fields.

Filter the displayed list

To filter the batchfields that get displayed in the client page UI specify the batch fields to be displayed by setting the displayedBatchFields parameter.

In the example below only BatchField1, and BatchField2 would be displayed in the generated table.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    contentType: 'AtalasoftEngineering',
    displayedBatchFields: "BatchField1, BatchField2",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
    onImportCompleted: function(params) { console.log(params.id + ": " + params.status); },
});

Set values through the initialize parameter list

When no indexfield div has been added to a page, but batch field values still need to be set they can be passed through the capture service's initialize method.

In the example below the two batch fields (BatchField1, and BatchField2) for the AtalasoftEngineering batch class have each had a value set. The batchFields parameter takes a string where each bath field name value pair are comma separated, and the batch field name, and value are colon separated.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    contentType: 'AtalasoftEngineering',
    batchFields: "BatchField1:value1, BatchField2:value2",
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
});

Batch field validation

There are two capture service initialization parameters that can be used to handle batch field validation on the client. There is the error handling event, onBatchFieldImportValidationError, and the custom client validation parameter, onBatchFieldTypeValidationStatus.

Atalasoft.Controls.Capture.CaptureService.initialize({
    handlerUrl: 'KicWebHandler.ashx',
    contentType: 'AtalasoftEngineering',
    onError: function(msg, params) { console.log(msg + ": " + params.statusText); },
    onImportCompleted: function(params) { console.log(params.id + ": " + params.status); },
    onTrackStatusReceived: function(params) { console.log("Import status: " + params.status); },
    onBatchFieldImportValidationError: function(error, validationResults) {
        // validationResults is the array containing true/false flags for corresponding(by indexes) batch fields
        console.log(error); 
    },
    onBatchFieldTypeValidationStatus: function(params) { fieldTypeValidation(params); }
});

function fieldTypeValidation(params) {
    // do something with params
    console.log(params);
}