DOKuStar Validation for Ascent Capture Programming Manual Océ Document Technologies GmbH
Océ Document Technologies GmbH Max-Stromeyer-Straße 116 D-78467 Konstanz - Germany Phone: ++49(0)75 31/87-0 Fax; ++40(0)7531/87-4567 E-Mail: sales@odt-oce.com www.odt-oce.com Edition: 6.2004 (V3.6 SR01) The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved.
Contents Introduction 1 The VBA Studio 2 Development Environment........................................................................................................... 2 Files.............................................................................................................................................. 5 The Document Model 7 Overview ......................................................................................................................................
OnCursorChanged........................................................................................................... 34 FieldClass Events ....................................................................................................................... 35 Data Objects 36 Dataset........................................................................................................................................ 36 Schema ........................................................................
Introduction This manual covers the topics an integrator needs to adapt DOKuStar Validation for Ascent Capture to specific requirements. This is mainly the scripting interface, DOKuStar Validation offers, and this will cover most of this manual. An additional chapter describes the format of the table data output. This is interesting only for those applications that also use the DOKuStar Recognition Server and read table data.
The VBA Studio Development Environment When planning to write scripts, you must know - where to write the code - how to test the code. These are both done in the same environment: After defining your batch class (which uses DOKuStar Validation as one queue) in the Ascent Capture Administration, select the batch class and give a right click with the mouse. In the context menu, you will find an item DOKuStar Validation Scripting...
Selecting this menu item will open the DOKuStar Validation Module. This is almost exactly the DOKuStar Validation program window that the validation operator will see, with one important difference: in the toolbars there is a button which, when pressed, opens the VBA studio: In the VBA studio, a tree view in the left window with a root node named Project can be seen. Expand this node up to the TheApplication node, and then double click.
Some important remarks: - You can (but you don’t have to) publish the batch class before you start writing scripts. This is useful in order to get test data. - It is not necessary to „republish“ the batch after code changes. - You can switch to the VBA studio regardless of whether you have a batch open in the DOKuStar Validation or not. - In order to get the code you just entered working, it is often necessary to re-open the batch: Suspend the batch in DOKuStar Validation and then re-open it.
Files Yet, I didn’t mention one important thing: Where does all the code go? In most development environments, you have some file handling functionality, like File...Open/Close menus or something similar to that. The VBA studio is different here: When you look around in the studio, you will not find anything like it. So: Where is the code stored? The answer is simple: It all goes into one file on the Ascent Capture Server.
So, when you plan to copy the scripting code from one system to another, proceed as follows: - export the Ascent Capture batch class definition, - import it on the target system, - copy the DOKuStar Validation Scripting file, - publish the batch class on the target system. Although all the scripting code goes into one file, you can still store the modules, class modules and forms into separate files by exporting them into text files.
The Document Model Overview In order to access fields, values, documents, etc., it is important to understand how data is organized in DOKuStar Validation. This data structure is called the document model. This document model is quite a large structure, and contains parts that you will probably never use. This manual concentrates on those items that are common to most applications. At the top of the hierarchy stands the Application object, which has some assigned members and methods.
Here is the source code for this example: Dim WithEvents Amount As FieldType Private Sub Application_OnProjectLoaded(ByVal App As Application) Set Amount = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Amount") End Sub Private Function Amount_OnFieldChanging(ByVal Field As Field, ByVal SubField as Field, ByVal VerifyEventArgs As VerifyEventArgs) As Boolean Amount_OnFieldChanging = True 'Preset return value If Val(Field.Value) > 1000 Then If MsgBox("You entered a value > 1000.
Before getting more into the details, here is a second way of solving the same problem: Dim WithEvents ctrl As Controller Private Sub Application_OnProjectLoaded(ByVal App As Application) Set ctrl = App.Project.DataSet.Controller End Sub Private Function ctrl_OnFieldChanging(ByVal Controller As Controller, ByVal Field As Field, ByVal SubField As Field, ByVal VerifyEventArgs As VerifyEventArgs) As Boolean ctrl_OnFieldChanging = True 'Preset return value If Field.Document.Name = "Invoice" And Field.
Relation to the Ascent Capture Definition There are some relations between the document model and the Ascent Capture batch class definition. Whenever a batch class is published, and also whenever DOKuStar Validation scripting is called from the administration module, the document model is created from the Ascent Capture batch class definition. As stated in the previous chapter, the Ascent Capture form types will become the document types in Validation’s document model.
Ascent Capture Field Types can have value lists; if so, the user input is also checked against this list: DOKuStar Validation for Ascent Capture Page • 11
Support of Ascent Capture Index Field Properties In the Document Class Properties dialog box, properties can be assigned to index fields. Some of these properties are supported by DOKuStar Validation, others are not. In the following picture the supported properties are marked: Name: This is obvious. The name must match the field name in the Extraction project file. DisplayName: This is the name of the field as displayed in Validation. If not present, the display name will be the field name.
Hidden: A hidden field will not appear in Validation, but can still be accessed by scripting routines. Sticky: If a field is set to be sticky, it will get its value from the preceding field, in case its value is empty. Table issues There are two field types of DOKuStar Extraction, that will be displayed in a table grid in Validation: Table and InvoiceItems. When defining a table in DOKuStar Extraction, you will also specify its columns.
This is all that must be done. Beyond that, there are some options that can influence the layout of the tables in Validation: Columns can be hidden, renamed, added, and reordered. This will be explained in the following (using an InvoiceItems field in the example, but in can be done for other tables as well). Generally, when changing something on table columns, this is done by a placeholder field for the column in the Ascent Capture index field definition.
To reorder columns, you can add a position number to the column name. This number is separated by a ‘#’ from the column name. In the example above, if you want your new column to be the second column in the table, you name it Items/ANewColumn#2. This will make your column the second one in the table grid, moving all other columns one place backward. Numbers on hidden columns are ignored; also, hidden columns are not counted when determining the position.
InvoiceItems Postprocessing There is obviously a correlation between the Invoice Items fields and the Invoice Totals field: Invoice Items lists the details, and Invoice Totals holds the sums. When opening a batch that contains these two fields, some automatic checking is done. Especially, the total amount is checked against the details; if they do not match, some self-correction is tried. This is all done “behind the scenes”.
Events Concept Certain objects can get events. You will probably use the events defined for the FieldType and the DocumentType object, but there are many more objects which have the ability to get events. For example, an event may be assigned to a single Field (instead of the FieldType), e.g. to the amount field on the first document. So you could add code that would be executed if the user changed the amount on the first document, but not, if he changed the amount on one of the following documents.
When writing an event handling routine, proceed as follows: - Define a variable of the appropriate object type: Dim WithEvents fld As FieldType - This variable will now appear in the drop down list above the editing window. Select it: - In the drop down list to the right, select the event handling routine wanted. The function body will then be added to the code automatically: In the following chapters, events are described in detail, always in the ...ed format.
Events for the FieldType Object OnFieldActivated This event will be fired when a field gets activated, either by keyboard entry, mouse click or by the scripting code itself. Definition: Private Sub fld_OnFieldActivated(ByVal Field As Field, ByVal PreviousField As Field) The parameter Field is the field that gets activated, PreviousField is the field that gets deactivated. When you return False in the OnFieldActivating, always the next field will be activated automatically.
OnFieldDeactivated These events will be fired when the field was deactivated. If the OnFieldDeactivating event is aborted, the current field will remain active. Definition: Private Sub fld_OnFieldDeactivated(ByVal Field As Field, ByVal NextField As Field) The parameter Field is the field that becomes deactivated, where NextField is the field that will become activated.
OnFieldDataSourceChanged These events result when the DataSource (i.e. the image) of the field changes. This may happen in several situations: - The user chooses a DOKuStar alternative for the field, which is on a different page of the document. - The user splits a document: field contents may be emptied, thus losing their image. - The user moves pages from one document to another: again fields may be emptied, thus losing their image.
Table Fields Tables require additional features, because they are fields that are made up of rows, columns, and cells. an example, imagine a table in your document that has (among others) three columns Quantity, SinglePrice and TotalPrice. Whenever the user corrects a cell in the Quantity or SinglePrice column, the corresponding total price is recalculated (by: Quantity times SinglePrice) and compared against the value in the TotalPrice column.
If SubField.Name = "Quantity" Or SubField.Name = "SinglePrice" Then Next, the generic Field must be converted to a specialized TableField variable: Set t = Field This allows you to use methods and properties that only exist for TableFields. One of these methods is the Row method, that delivers the row in which the cell is in. The cell is passed as a parameter to this method. What we get is an object of type TableRow: Set row = t.
Event Order Field events occur in the following order: OnFieldActivating OnFieldActivated OnFieldChanging OnFieldChanged OnFieldDeactivating (old field) OnFieldActivating (next field) OnFieldDeactivated (old field) OnFieldActivated (next field) If any of the ...ing events is aborted, the events following this one will not be fired. Instead, you will get an ...ingCanceled event for this specific event.
For table fields, the event queue is as follows: OnFieldActivating (when the user steps into the table) OnFieldActivated OnSubFieldActivating (for the first cell) OnSubFieldActivated OnFieldChanging OnFieldChanged OnSubFieldDeactivating (for the first cell) OnSubFieldActivating (for the second cell) OnSubFieldDeactivated (for the first cell) OnSubFieldActivated (for the second cell) OnFieldChanging OnFieldChan
Events for the DocumentType Object OnField Events For the DocumentType object, the same OnField... events are available as for the FieldType object. These events will be fired for any field on the document. Definition (example OnFieldChanged): Private Sub doc_OnFieldChanged(ByVal Field As Field, ByVal SubField As Field) This is a convenient way of handling all fields of a certain form type together. Example: Suppose a form type TaxForm exists with several amount fields.
OnDocumentActivated This event occurs whenever a new document is selected. This may happen explicitly (e.g. when the user selects a different document in the tree view) or implicitly (e.g. the user moves from field to field and the document changes). Definition: Private Sub doc_OnDocumentActivated(ByVal Document As Document, ByVal PreviousDocument As Document) The current document and the previous document come as parameters.
OnDocumentCreated This event will be fired when a new document is created. This may happen explicitly (e.g. when the user splits a document in the tree view) or by scripting code. Definition: Private Sub doc_OnDocumentCreated(ByVal Document As Document) OnDocumentDataSourceChanged This event will be called when one of the data sources of the document (i.e. one of the images) is changing.
Definition: Private Sub doc_ OnDocumentDescriptorLost(Document As Document, DocumentDescriptor As DocumentDescriptor, NextDocumentDescriptor As DocumentDescriptor) Document is the document whose descriptor changes DocumentDescriptor is the current descriptor NextDocumentDescriptor is the descriptor the user selected from the context menu Private Sub doc_ OnDocumentDescriptorGot(Document As Document, DocumentDescriptor As DocumentDescriptor, PreviousDocumentDescriptor As DocumentDescriptor) Document is the
Batch Events Batch events concern opening and closing of a batch. When a batch is opened and closed, you get an event where scripts can be added. These events are events of the Data object, thus requiring the use of a Data object as the event sink: Dim WithEvents data As Data Private Sub Application_OnProjectLoaded(ByVal App As Application) Set data = App.Project.DataSet.
OnPreExported This event will be fired after the user selected to close or suspend the batch, but before the batch is really closed. The data are still present. If OnPreExporting returns False, the closing process is aborted and the batch remains open. The closing mode (Suspend or Close) is handed over as a parameter.
Controller Events The controller object itself is described below in a separate chapter, please refer for a description. This object gets events when the active object changes, i.e. a field or document gets activated or deactivated. So here is another potential place to enter the (de)activation code. This is especially useful for routines that are common to all documents or all fields. OnDocumentActivated Will be fired for any document that gets activated.
OnDocumentDeleted Will be fired for any document that gets deleted. Definition: Private Sub ctrl_OnDocumentDeleted(ByVal Controller As Controller, ByVal Document As Document) Parameter Document is the document that gets deleted. OnDocumentCreated Will be fired for any document that is created. Definition: Private Sub ctrl_OnDocumentCreated(ByVal Controller As Controller, ByVal Document As Document) Parameter Document is the document that is created.
OnFieldChanged Will be fired for any field that gets changed. Definition: Private Sub ctrl_OnFieldChanged(ByVal Controller As Controller, ByVal Field As Field, ByVal SubField As Field) The parameter Field is the field itself. SubField may point to a sub-field of the Field. OnCursorChanged Will be fired when a cursor changes. See below for a description of cursors.
FieldClass Events There are the same events for FieldClass objects as for FieldType objects, see there for a description of the events. The only additional event for the FieldClass object is a OnFieldClassDeleted event, which is not used in the Ascent Capture version of DOKuStar Validation. You will use FieldClass events when you want to handle all fields of a certain FieldClass (= Ascent Capture FieldType) alike.
Data Objects Dataset The Dataset is the topmost object in DOKuStar Validation concerning the data, and can be accessed from the Application object via: Application.Project.Dataset Every sub-object of the Dataset object has a property called Dataset, which delivers a pointer to its parent Dataset object. Example: Field.Dataset Furthermore, there are often properties that point to the parent(s) of an object.
Schema The Schema object describes the batch structure, i.e. the Document Types and Field Types. The schema has completely been filled with the Ascent Capture form types and index fields for this batch upon opening, so you don’t have to care about filling this structure. Note: Although technically adding DocumentTypes and FieldTypes on the fly is possible, the corresponding data would not be transferred back to Ascent Capture. The Schema and belonging descendents will be used when defining events, e.g.
Property/Method Returns Description At DocumentType Delivers a document type object at the specified position Begin DocumentType Delivers the first document type object in the collection Empty Boolean Returns true if the collection is empty Last DocumentType Delivers the last document type object in the collection Next DocumentType Delivers the next document type in the list Parameter: PreviousDocumentType as DocumentType Previous DocumentType Delivers the previous document type in the l
FieldTypes See the description for DocumentTypes. The properties and methods are identical after replacing DocumentTypes by FieldTypes and DocumentType by FieldType respectively. FieldType FieldTypes are used at two places: - linked to a DocumentType object, they describe the index fields for this document type, - linked to a FieldType itself, they describe sub-fields of an index field. Currently, the only place where FieldTypes are used as sub-fields of a FieldType is the TableField.
Data The Data object is situated below the Dataset object, parallel to the Schema object. While the Schema holds the document definition, the Data object holds the data itself. The Data object has been filled completely when the batch was opened. Although you technically could add documents yourself, which also would show up in the Validation, there is not much use doing this since these documents could not be transferred back to Ascent Capture when the batch is closed.
Documents Holds the collection of documents in this batch. An individual document can be accessed using the At method, which takes a Document as parameter.
Document Holds information about one document, especially the fields and the images. Furthermore, there is an Activate method which lets the document get activated. Properties and methods of the Document object (excerpt): Property/Method Returns Description Activate Boolean Activates the document. Returns True if successful. Activated Boolean Returns True if the document is currently activated. DataSources DocumentDataSources Returns the list of DataSource objects for this document.
Fields Holds a collection of Field objects. Individual Fields can be accessed either by name or object: Fields(MyField) Fields.At(MyField) Fields(„OrderDate“) Fields.
Field Properties and methods of the Field object (excerpt): Property/Method Returns Description Activate Boolean Activates the field. Returns True if successful. Activated Boolean Returns True if the field is currently activated. ActivateSubField Boolean Activates a sub-field. Returns True if successful. Can be used to jump to a specific cell of a table field. Parameter: SubField as Field ActiveSubField Field Returns the currently active subfield (i.e. table cell) of a field.
TableField A TableField is a special Field object. Being derived from Field, all Field’s properties and methods can be used. A TableField also has some additional properties and methods: Properties and methods of the TableField object (excerpt): Property/Method Returns Description Row TableRow Returns the row object for a given table cell. Parameter: Cell as Field Rows TableRows Returns a TableRows object, which is the collection of the tables‘ rows.
SourceInfo, ImageSourceInfo SourceInfo is the base class of ImageSourceInfo. Within DOKuStar Validation for Ascent Capture, only ImageSourceInfo is used. Properties and methods of the ImageSourceInfo object (excerpt): Property/Method Returns Description DataSource ImageDataSource Holds the ImageDataSource object, which includes the images filename. Zone Zone Describes the box around the field. DataSource, ImageDataSource DataSource is the base class of ImageDataSource.
UserData UserData is an object that is linked to each field and document object. It serves as a container for additional data that you want to attach to the field or document. This data are organized as key/value pairs. You can attach as many of these key/value pairs to the document as you like. Example: Whenever the user changes the contents of a field, the original value shall be saved. When the field is activated again later on, the old contents shall be displayed in the status window.
VerifyEventArgs VerifyEventArgs is an object that is used with some events like OnFieldChanging. When such an event occurs, a VerifyEventArgs object is one of the parameters of the event handling function. VerifyEventArgs has two properties: Error, which is currently unused, and PreviousValue, which contains the old value before the user typed something in.
Controller The Controller object is the third sub-object of the Dataset, with the purpose of controlling the behavior of the application. Using the controller object enables to: - activate and deactivate documents and fields, - administer the cursor. The Cursor object is described below in a separate chapter. With the controller object, a second way of activating fields or documents (the first one is the Activate method on the field and document object) is provided.
Cursors and Filters These topics are covered together, because there are some dependencies between them. Cursors define a behavior which fields and/or documents will get activated in the DOKuStar Validation’s user interface. They do not denote the shape of the cursor. Cursors are mainly defined by a set of filters. There are three types of filters defined in DOKuStar Validation: Field state filters, field confidence filters and document type filters.
Option Explicit Private Dim Dim Dim Dim Sub Application_OnProjectLoaded(ByVal App As Application) crs As Cursor fieldFilter As FieldStateFilter docFilter As DocumentTypeFilter docType As DocumentType Set crs = App.Project.DataSet.Controller.Cursors.Add("dataset::DefaultCursor", "MyCursor") ' Add a new cursor App.Project.DataSet.Controller.Cursor = crs ' Activate it Set fieldFilter = crs.Filters.Add("dataset::FieldStateFilter", "ErrorAndReject") ' Add a fieldState Filter Set docFilter = crs.Filters.
Property/Method Returns Description Documents Documents Returns the list of documents with respect to the currently selected filters. Fields Fields Returns the list of fields with respect to the currently selected filters. Filters CursorFilters Returns the list of CursorFilters appended to this cursor. FirstDocument Document Returns the first document from the Documents list. FirstField Field Returns the first field from the Fields list.
In addition, all the methods defined for collections are available. For the filter objects, there is a base class called CursorFilter. This class has few methods and properties, which you hardly will use. Derived from this base class there are the three classes DocumentTypeFilter, FieldStateFilter and FieldConfidenceFilter, where you define which document types and field states respectively are switched on and off.
DOKuStar Validation for Ascent Capture Page • 54
Add-Ins Introduction Validation allows to modify its behavior using VBA. Because of some limitations of this method, Validation provides, starting with version 3.2, another way for interaction: add-ins . An add-in for Validation is an ActiveX Control. An add-in allows to add new menu entries or create and use one custom user control and one custom toolbar. In addition it is possible to easily handle the existing image control or to replace the existing edit and fields controls with your own controls.
Registry Key for Validation Add-Ins To be able to use a newly created add-in you must first add some information into the registry. It is useful to do this as a first step, because afterwards you are already able to test the add-in while you write the program code. Therefore Validation will use the following registry path (for version 3.2; for later versions replace this string by the respective version): HKEY_LOCAL_MACHINE\SOFTWARE\ODT-OCE\DOKuStarValidation\3.
Under this key a sub-key has to be created for each add-in that should be used for the respective application, here dsval.exe. The key name must be the program id of the add-in, which has the format .. Here is the name of the VB6 project and is the name of the class module. In the following section we will create a library ValiTour.dll with an add-in that is represented by the class MyValidation.
Creating an Add-In An add-in for DOKuStar Validation is always an ActiveX Control. You can write such an ActiveX Control in any programming language. In our example we use Visual Basic. In Visual Basic use the New Project command of the File menu and choose ActiveX Control from the appearing New Project dialog box: Now choose References from the Project menu. In the References dialog box select the entry ODT DOKuStar DataSet x.y Type Library (x.
Private Sub IAddIn_Initialize(ByVal App As DOKuStarDataset.IApplication) for this class. It is called when the add-in has been initialized by Validation. Now type in the following code for the class MyValidation and generate ValiTour.dll.
Creating a Custom User Control In the previous section is described, how to create an add-in for Validation. In this section a new custom user control is added to Validation. The appropriate service is called UserCtrlBarData service. It is only possible to add one and only one custom user control. We will implement the custom user control for Validation using an add-in: First we have to add another reference. Use the command References of the Project menu.
Modify the code of our example in the following way and generate ValiTour.dll: There is also a special custom user control interface IUserCtrl. You must implement the function of the interface, or otherwise the custom user control will not work properly. When you now start dsval.exe you will see that our custom user control appears on the Validation user interface. The View menu now allows activating or deactivating the custom user control.
DOKuStar Validation for Ascent Capture Page • 62
Creating a Custom Toolbar It is also possible to create one and only one custom toolbar for DOKuStar Validation. The appropriate service is called UserToolbarData service. First add a new user control to the project and name it Toolbar: Afterwards define the elements of the toolbar. For our example we add a toolbar and an image list to the form. To be able to add a ToolBar control, you have to add it to the ToolBox first.
As you can see, the toolbar is activated in the same way as the user control. The only difference is the type of service which has to be defined. There is also a special custom toolbar interface IUserToolbar. You must implement all three functions of the interface, otherwise the toolbar will not work properly. The first one sets the caption of the toolbar. It can be seen when the toolbar is dragged outside the toolbar area and changes into a window.
DOKuStar Validation for Ascent Capture Page • 65
Creating Menu Entries for Validation The programming interface allows to change the menu entries of DOKuStar Validation. The appropriate service is called Workspace service. New menu entries can be added, existing menu entries can be replaced or deleted. Now we will modify the menu using our add-in: First of all we have to define the workspace by the line Dim WithEvents workspaceSink As DOKuStarValidationServices.WorkspaceService. Then we have to get the specific service for processing workspaces.
After this code has been entered, generate ValiTour.dll and start dsval.exe.
The New command has been replaced and shows a submenu with two entries. Following the Export Data command the new command Import Extraction Result… appears. The only thing you have to do now is implementing what should happen if the new menus are used. For this purpose the Workspace service has two functions: workspaceSink_OnCommand and workspaceSink_OnCommandUpdate. Let us first look at workspaceSink_OnCommandUpdate. In our example we replace the existing New command with our own one.
The second function of the Workspace service, workspaceSink_OnCommand, is needed to specify the actions that should take place when the menu command is used. Here you must again use EventArgs.
If you enter the code shown above, generate ValiTour.dll, start dsval.exe, and open the File menu, the new menu items will be shown.
Workspaces In the previous section we used the Workspace service of Validation. In this section it is explained what a workspace is and how it is used. The workspace of Validation comprises the size and location of the various elements of the user interface of Validation within the main window. For example, if you drag custom user control of our example from the bottom of the main window to the top, you are changing the workspace of Validation. The same is true, if you change the order of the toolbars.
What happens? We have loaded the workspace default.vws at startup of Validation. In this workspace our custom user control is no longer at the bottom of the Validation window. Now enlarge our control until the Restore button appears and close Validation. If you now restart dsval.
Validation now comes up with the last changes you made in the workspace. Play a little around to get a feeling. You could remove the call to storeDefault and check that changes of workspace will no longer take effect. To write it to a file is probably not the best method to save a workspace. Therefore it is also possible to store the workspace information in the registry. The corresponding commands are workspaceSink.LoadWorkspaceFromRegistry and workspaceSink.SaveWorkspaceToRegistry.
Then we have to modify the functions loadDefault() and storeDefault(). In loadDefault() we first check whether the registry key already exists. If not we load the workspace from file, otherwise we fetch it from the registry. In storeDefault() we store the workspace to the registry and into a file. So, when dsval.exe is started for the first time, the workspace will be loaded from file. When Validation is closed the workspace will be written to the registry as well.
Handling Keyboard Strokes Keyboard strokes can also be handled by an add-in for DOKuStar Validation. The appropriate service is called Keyboard service. First you must provide the keyboard service of Validation. The keyboard service has two functions OnChar() and OnKeyDown(). In OnChar() you get the final code from the keyboard. That means if you press Shift-A, you get the final key code in OnChar(), in this case 65. In OnKeyDown() you get the code for Shift and a.
Now start now Validation with dsval ValiTour.vpj. The Validation window will look as follows: Press the F4 key and the message box will appear: Now try to enter numbers for the fields. Numbers will be suppressed but all other characters will appear normally.
Replacing Existing Controls In a previous section we created a custom user control. As was stated there, you can create only a single new user control, but you can replace existing controls, namely edit control and the fields control. In our example we will replace the edit control. The appropriate service is called UserEditData service. Let us replace the current edit control and use a new one for the text fields. First of all we create a new user control and name it Edit.
Now start Validation with the command dsval ValiTour.vpj. The Validation will look like this: The replaced edit control can be easily recognized by its changed color. If you move the cursor to the field Table, the color will disappear because this field is of the field type TableField and our new edit control was attached only to text fields.
Managing the Image Control The behaviour of the image control, like scrolling and zooming, can also be managed by an add-in. The appropriate service is called SourceCtrl service. Like the other services it must first be provided which is done by the lines Dim sourceCtrlSink As DOKuStarValidationServices.SourceCtrlService and Set sourceCtrlSink = dsValApp.Services("SourceCtrl"): Let us now implement a special behaviour of the image control.
Now start dsval ValiTour.vpj and try the key combinations to see the effects. Predefined Add-Ins There are two add-in modules that will be provided by DOKuStar Validation. ODT_F4.Module This default add-in is ready for use. It changes the layout of the DOKuStar Validation user interface from "normal" view to "table" view by using the Table Mode command of the View menu. DOKuStarValidation.Spy This add-in starts an event spy window. In the window all events fired by DOKuStar Validation will be listed.
Special Issues Information Bar The information bar is one of the windows of the Validation’s user interface; when the program starts, it is located above the field source bar (which displays the field’s snippet), but it can be moved around like any another window. This information bar can be filled programmatically, in order to display messages to the validation operator. To do so, there is a class StatusTextTransporter.
The result will look like this: DOKuStar Validation for Ascent Capture Page • 82
Exchanging the Fields View In the Validation’s Fields View all fields of the current document are displayed together with their values. The fields are displayed one below the other, the active field is always highlighted. The appearance of this window can be exchanged individually for each Ascent Capture form type. This is done by defining an HTML template for each form type. To do so, place a file named
In this mode, you could also close the editing window. - Display Mode: In this mode, editing is still done in the editing window.
Note 1: You can also mix the modes: Use the editing mode for some fields, and the display mode for others Note 2: Tables can only be edited in the editing window, not in the HTML view. The HTML file itself can be created with any HTML editor (FrontPage etc.). To link it to the document model, you must use an attribute named id in your tags, which has the field name as value.
Table Data Output When DOKuStar recognizes tables, the corresponding data is transported in separate files outside the Ascent Capture data structure. When you finally release your batch, it is important to know how to access this data. Table data are stored in XML files. There is one file for each document, which has the same name as the image file of the first page of the document with an extension .tab instead of .tif. For example, you could have a file name like ....\Ascent\images\0000009C\200\1.tab.
If no table was found on the document, there will be a table data file whose element is empty:
Character correction mode For editing single characters (for example rejects as first step of a multi-grade Validation), you can use the character correction mode feature. This feature is realized by an additional ActiveX Control named ValRejectEdit, using the UserEditData service and will replace the default EditControl.
Step 3 Now we are ready for integrating the following code lines When the project is loaded, first we call InitRejectEditCtrl to connect all field classes of the schema to the RejectEditControl, with the exception of TableFields. TableFields are displayed in the DOKuStar Validation GUI by the TableEdit Control. Therefore we prevent the TableField class from registering by the RejectEditControl. So we are able for editing characters in TableFields by the TableEdit Control.
Remarks: You will find the above code lines, explaining the character correction mode, as a complete BatchClass, in your Ascent Capture installation path in the folder .\Bin\DOKuStar\ValAC_Demos\Demo3 So you can copy and implement the sample code for your own batch classes.
Properties and methods of the ValRejectEdit control: Property/Method Value Default Description AllowLeaveRejectMode True or False True Enable the editing of all characters, not only rejected ones. AllowRemoveDetail True or False True Enable the deleting of a rejected character AllToUppercase True or False False All entered characters will appear in upper case.
In the snippet view window the image of the index field is displayed, where the rejected character is highlighted; in the edit view you see the Reject Character ready for processing. • • FixedMode = True ShowDetailZone = True In the snippet view window only the image of the rejected character is displayed. This mode will be usefull to enlarge the image of the Reject Character to see further details.
How Do I… Reject Documents and Pages Documents and pages can be rejected and un-rejected by the user: He clicks on the document/page in the tree view and chooses reject… or unreject from the context menu. Also, he can add a reject text to the object. This can also be achieved by scripting. To reject a document or page, add a UserData named Rejected to the Document or DataSource object and set its value to 1.
Note: In this example, it is important to check for the existence of the Rejected UserData before trying to read its value.
Test the Scripting Code Something about this topic has already been said in the first chapter, this chapter discusses some more details. It is important to understand that each Ascent Capture Batch Class that uses DOKuStar Validation has a Validation Project assigned to it. Each project in turn has its scripting code. Whenever a batch is opened in DOKuStar Validation, the following things happen: - The scripting code of the batches’ batch class is loaded.
DOKuStar Validation is opened, and you can modify your scripting code for the batch class you selected in the Administration module, without having to open a batch. Only the first two steps from above have so far been executed: - The scripting code of the batch class you selected in the AC administration module is loaded. - The project is loaded (which leads to the Application_OnProjectLoaded event in the scripting code).
You can now test your code with real loaded data. You can also add changes to your code. When you are ready, you will close or suspend the batch. Then: - The data are exported (which leads to the Data_OnExported event in the scripting code) and unloaded. - The project will not be closed and the scripting code will not be unloaded.
Not Restore Old Contents When a scripting routine returns False in the OnFieldChanging event, the original contents of the field (before the user changed it) is restored. Sometimes however it might be better to keep what the user typed in, but still stay in the field and display an error message. This might be suitable for larger texts, where the user just made a spelling mistake. It is better then to let him correct what he typed than to let him enter it completely once again.
Display Multi-Line Status Texts Sometimes it might be necessary to display more than one line of text in the Information Bar. Using the StatusTextTransporter’s HTMLText Property, this is no problem, because you will format everything yourself using the appropriate HTML tags. When you are not familiar with HTML and prefer the StatusTextTransporter’s Text Property, you can still display more than one line of text.
Check All Fields Before Closing the Batch When the user closes a batch, you might want to check if there all still erroneous fields. You place such a check in the Data objects OnPreExporting event. In the following example, all fields are checked if they have the state Empty or Error. If so, exporting is aborted and the first field of this kind is activated.
Check if the Last Field is Reached When the user leaves the last field of the last document in the batch, you could perform some action like displaying a message box etc. The check for the last field should be done with respect to the current filter settings. If the user choose only to jump to empty fields, the last field is another one as if he jumped to all fields. The Cursor object provides a method LastField, so this is the easiest way to check for the last field.
Merge Table Rows The following example merges two table rows into one. The corresponding columns will be connected by adding the second cell’s value to the first one (strings put together separated by comma). The zone of the new cell will be the surrounding rectangle of the individual zones. It is assumed that the table field has three columns named Description, SinglePrice and TotalPrice. Whenever there is a table row that has only the Description filled, it shall be merged with the preceding one.
Private Dim Dim Dim Sub mergeZones(firstFld As Field, secondFld As Field) firstSrcInfo As ImageSourceInfo secondSrcInfo As ImageSourceInfo fr, fb, sr, sb As Long Set firstSrcInfo = firstFld.SourceInfo Set secondSrcInfo = secondFld.SourceInfo fr = firstSrcInfo.Zone.X + firstSrcInfo.Zone.Width fb = firstSrcInfo.Zone.Y + firstSrcInfo.Zone.Height fr = secondSrcInfo.Zone.X + secondSrcInfo.Zone.Width fr = secondSrcInfo.Zone.Y + secondSrcInfo.Zone.Height If firstSrcInfo.Zone.X > secondSrcInfo.Zone.
Changing the Color of Documents Sometimes it may be necessary to inform the validation operator, which documents are always processed or which documents still contain errors after they have been processed by the operator. This can be done by changing the color of the document in the Tree View, using the ColorService. In the following example we use the OnDocumentDeactivated event as indicator that the validation operator changed to another document.
Private Dim Dim Dim Dim Sub colorDoc(doc As Document, bnOK As Boolean) lngRed As Long lngGreen As Long lngBlue As Long cs As ColorService Set cs = doc.Services("Color") lngRed = 0 lngGreen = 0 lngBlue = 0 ' display processed documents in different colors... If bnOK Then lngGreen = 255 cs.SetForeColor lngRed, lngGreen, lngBlue '...document without an empty field Else lngBlue = 255 cs.SetForeColor lngRed, lngGreen, lngBlue '...
