The "Optional" property of a Group element
At the creation of a Group element the Optional element box is clear by default, i.e. the element is obligatory. At FlexiLayout matching, a non-null hypothesis is generated for an obligatory Group element, even if null hypotheses are generated for all of its subelements. To check the properties of the subelements of such a hypothesis, call the code in their Advanced sections. If the Group element is optional, a null hypothesis can be generated for it (if there are no non-null hypotheses with the quality higher than the quality of a null hypothesis).
It is not recommended to select the Optional element box for Group elements. The reasons for this are that, if the Group element is Optional element and it is not detected (its quality is lower than the quality of a null hypothesis, of the function Dontfind() is called for it), then any call to any of its subelements will cause errors, because in a group with a null hypothesis, the hypotheses of subelements are not formulated. To avoid this error, you must first check the Group element. If the IsNull -check returns True, you mustn't address any of the subelements.
Then why do we need an optional Group element and its null hypothesis? It is needed when the entire group of fields is not present on the image. Then it is useless to search for them. And the search for the elements can be speeded up by calling the DontFind() method for the Group element.
Note.Under "call" we mean writing code in any of the sections on the Advanced tab or in the block properties in the Expression window. If the properties of a Group element are called when setting the search constraints in Relations, then the IsNull -check is automatic. You can see this if you click Code on the Advanced tab.
To illustrate this, we created the project GroupSample.fsp (folder %public%\ABBYY\FlexiCapture\12.0\Samples\FLS\Tips and Tricks\Optional Group).
In the Properties dialog box of the Group element InvoiceRequisiteGroup, we selected the Optional element box. On the Advanced tab in the section Advanced pre-search relations we wrote the following code:
if FormID.IsNull then Dontfind();
Next we check for the availability of the element which identifies the document type. By using the element FormID, created prior to the Group element InvoiceRequisiteGroup, we search for the static text with a known value ("ID2015"). If the value of the identifier on the document matches the value specified in the Search text section, then a non-null hypothesis is generated for the element FormID. Otherwise, the static text FormID is not detected and we tell the program not to look for the Group element InvoiceRequisiteGroup, i.e. we created a null hypothesis for the optional Group element InvoiceRequisiteGroup.
In the project there is an element TotalSumHeader that is used to look for the name of the sum field. The following code is entered for the element in the Advanced pre-search relations section:
Below: SearchElements.InvoiceRequisiteGroup.InvoiceDateHeader, 0 * dot;
This code means that the search for the name will be run below the date field described by the element InvoiceDateHeader, which, in its turn, is a subelement of the Group element InvoiceRequisiteGroup.
Let's run the FlexiLayout matching procedure on both pages in the batch. For page 1 the procedure was successful, but at the attempt to apply the FlexiLayout to page 2, the program displays the following error notice: "Page 2: Error in element "SearchElements.TotalSumHeader", Advanced generator parameters section: Attempt to access undefined hypothesis: SearchElements.InvoiceRequisiteGroup".
This happens because on page 2 the value of the identifier of the document is ID 2589. Since this value is different from the one specified in the properties of the element FormID, the function Dontfind() for the Group element InvoiceRequisiteGroup generated a null hypothesis. So in the code we called for a non-existent hypothesis.
The correct code must look like this.
if not( SearchElements.InvoiceRequisiteGroup.IsNull ) then
{ Below: SearchElements.InvoiceRequisiteGroup.InvoiceDateHeader, 0 * dot;}
Note.If you comment the code in the Advanced pre-search relations section and activate the flag near the similar search constraint of the element TotalSumHeader in the Relations section, then clicking Code in the Advanced tab will show that the compiled code already contains the IsNull -check.
4/12/2024 6:16:02 PM