This document describes the steps necessary to enable and display blank fields on a dynamic document.
Dynamic Document A CSi document that compiles itself dynamically based on the parameters of individual transactions so that the document only contains information relevant to the transaction in question.
Datapoint A placeholder in a document for transaction-specific or customer-defined data. Every datapoint in a document either has
a CSi schema mapping path that describes where to find its value using the CSi data schema model, or
key/value pairs in the datavalues section of a TXL file indicating the value for that datapoint.
TXL A data file structured to use the hierarchy of the CSi data schema. A TXL file may contain the data values required to populate the datapoints in one document , or for all datapoints for all documents required to perfect a transaction.
Blank Field A blank field refers to a data/fill-in datapoint that is rendered on a dynamic document as a blank “fill-in” field. To designate a datapoint as a blank field, its value must be set to an empty string and its EmptyValue property must be set to blankField.
Blank Fields On/Off Blank Fields On means that certain data fields on a dynamic document are to be rendered as a blank field. Blank Fields Off means that no data fields are rendered as a blank field.
Blankable Datapoint A blankable datapoint refers to a data/fill-in datapoint whose value may be empty without triggering the “form must be completed” margin message when EnableBlankFields is true.
Empty Value A datapoint defined with and empty value (e.g. “”) and passed into the system.
Prior to February, 2009, the intent to represent a datapoint on a document as a blank field was indicated by turning blank fields on and setting the value of the datapoint to an empty value. For example, the following DXL record would have indicated that datapoint_name should be represented on a rendered form as a blank field:
<datavalue name="datapoint\_name"></datavalue>
A new attribute (emptyvalue) was added to explicitly indicate which datapoints in a data value set are to be rendered as a blank field. This attribute can be used within a datavalue element in a DXL file and within a value/leaf node in a TXL file. This attribute can also be set programmatically via a new DataValue.EmptyValue class property.
The DXL record above is now be written as:
<datavalue name="datapoint_name">emptyvalue="blankField"></datavalue>
The default for emptyvalue depends upon the consuming application. Additional details can be found throughout this document.
Blank fields must be enabled in order for any blank fields to render on a form.
A datapoint will render as a blank field if all of the following are true about its record in a data value set:
a. The value is an empty string (i.e., “”).
b. The blankwidth attribute is greater than zero. This can be set explicitly in the data value set, or implicitly through system defaults and preference values.
c. The emptyvalue attribute is “blankField”. This can be set explicitly in the data value set, or implicitly through system defaults and preference values.
A datapoint’s value is validated unless all of the following are true:
a. Blank fields are enabled.
b. The datapoint is blankable.
c. The data value is an empty string.
d. The data value is designated as a blank field.
The “form must be completed” margin message is generated under the following conditions:
a. Blank fields are enabled.
i. And any non-blankable datapoints are designated as a blank field (and have an empty value)
ii. Or any non-optional, non-structural required datapoints have no value.
b. Blank fields are disabled.
i. And any non-optional datapoints have no value.
Note that the “form must be completed” margin message can also be generated from within the CSiScript of dynamic documents, which may cause the message to be generated outside of the above rules.
If blank fields are disabled, emptyvalue=“blankField” is treated as emptyvalue=“emtpyString”.
Data value sets created prior to the existence of the emptyvalue attribute (prior to Feb, 2009) will not display any blank fields in newer versions of the Compliance Engine unless the emptyvalue default is set to blankField (which is the default as installed). This can be changed in the application configuration file (via the “EmptyDataValueDefault” appSetting) or in application preferences (prefs.FieldPrefs.EnableBlankFields).
Blank Fields may be enabled with fill-able PDFs and is recommended for fill-able PDFs for data collection.
To determine which datapoints are blankable on a given document, do the following:
Load the document into a csi.Engine.Containers.FormFile object or an EDoc object.
Call GetDatapointDictionary() to get a list of all datapoints used on that document.
Loop through the list - a datapoint is blankable if its IsBlankValueAllowed property is true.
To illustrate:
using csi.Engine.Containers;
…
FormFile formFile = new FormFile( filePath );
ArrayList datapoints = formFile.GetDatapointDictionary();
ArrayList blankableDatapoints = new ArrayList();
foreach( Datapoint datapoint in datapoints )
{
if( datapoint.IsBlankValueAllowed )
blankableDatapoints.Add( datapoint );
}
Blank Fields are enabled in the IntelleDoc Viewer Control via the BlankFields and BlankShading properties, as follows.
csi.Controls.EDocView viewer = new csi.Controls.EDocView();
…
viewer.BlankFields = true;
viewer.BlankFieldsShading = BlankFieldsShadingType.Underline;
…
If EmptyValue is not set explicitly for a given data value (e.g. DataValue object or DXL file), a default value is used.
The default EmptyValue value may be set in the Viewer Control or as an appSetting in the application configuration file:
viewer.EmptyDataValueDefault = csi.Utility.Datapoints.DataValue.EmptyValueType.blankField;
or
<appSettings>
...
<add key="EmptyDataValueDefault" value="blankField"/>
</appSettings>
Application preferences take precedence over the configuration file setting. If neither is defined, the hard-coded default of ignoreValue is used.
See the Specifying Which Fields Render as a Blank Field section in this document for more information on the EmptyValue property.
To be backwards compatible (prior to February 2009), set EmptyDataValueDefault to blankField.
Blank Fields are enabled in the Compliance Engine via the csi.Engine.Properties.Preferences class, as follows.
using csi.Engine.Properties;
…
Preferences prefs = new Preferences( csiLicenseKey );
prefs.FieldPrefs.EnableBlankFields = true;
prefs.FieldPrefs.BlankHighlight =
DataFieldPreferences.BlankHighlightType.gray30;
// Not required, but helps readability of rendered document.
prefs.FieldPrefs.RenderForDataCollection = true;
…
If BlankWidth is not set explicitly for a given data value (e.g.,DataValue object or DXL file), a default value is used.
The default BlankWidth value for a specific datapoint may come from the datapoint dictionary of the FXL file being evaluated, or it may be set in the Compliance Engine preferences. For example:
using csi.Engine.Properties;
…
Preferences prefs = new Preferences( csiLicenseKey );
prefs.FieldPrefs.BlankWidth = 28;
A setting in the FXL file takes precedence over the preference setting. If neither is defined, the hard-coded default of 10 is used.
See the Specifying Which Fields Render as a Blank Field section in this document for more information on the BlankWidth property.
If EmptyValue is not set explicitly for a given data value (e.g.,DataValue object or DXL file), a default value is used.
The default EmptyValue value may be set in the Compliance Engine preferences or as an appSetting in the application configuration file:
using csi.Engine.Properties;
using csi.Engine.Containers;
…
Preferences prefs = new Preferences( csiLicenseKey );
prefs.FieldPrefs.EmptyDataValueDefault = DataValue.EmptyValueType.blankField;
or
<appSettings>
...
<add key="EmptyDataValueDefault" value="blankField"/>
</appSettings>
Application preferences take precedence over the configuration file setting. If neither is defined, the hard-coded default of blankField is used. This provides backward compatibility with DXL files created prior to February, 2009.
See the Specifying Which Fields Render as a Blank Field section in this document for more information on the EmptyValue property.
Blank Fields are enabled in the ComplianceService interface via the TransactionJobPreferences of the csi.Web.Services.ComplianceService object1, as follows.
…
TransactionJobPreferences preferences = new TransactionJobPreferences();
preferences.FieldPrefs.EnableBlankField = true;
…
See Transaction Server section in this document for more information.
Blank Fields are enabled in the ComplianceServiceSimple interface via the <enableblankfields> element, as follows.
<complianceservicerequest>
<preferences>
<license>...</license>
<fields>
<enableblankfields>true</enableblankfields>
<blankhighlight>none</blankhighlight>
…
</fields>
…
</preferences>
…
</complianceservicerequest>
See Transaction Server section in this document for more information.
The Transaction Sever sits behind the ComplianceService and ComplianceServiceSimple applications. Blank Fields are enabled in the Transaction Server via the csi.Transaction.Shared.JobTicket class, as follows:
using csi.Transaction.Shared;
…
JobTicket jobTicket = new JobTicket();
jobTicket.Prefs.FieldPrefs.EnableBlankFields = true;
jobTicket.Prefs.FieldPrefs.BlankHighlight =
DataFieldPreferences.BlankHighlightType.gray30;
// Not required, but helps readability of rendered document.
jobTicket.Prefs.FieldPrefs.RenderForDataCollection = true;
…
If BlankWidth is not set explicitly for a given data value (e.g.,TXL file), a default value is used.
The default BlankWidth value for a specific datapoint may come from the datapoint dictionary of the FXL file being evaluated, or it may be set in the job ticket preferences. For example:
using csi.Transaction.Shared;
…
JobTicket jobTicket = new JobTicket();
jobTicket.Prefs.FieldPrefs.BlankWidth = 28;
A setting in the FXL file takes precedence over the preference setting. If neither is defined, the hard-coded default of 10 is used.
See the Specifying Which Fields Render as a Blank Field section in this document for more information on the BlankWidth property.
If EmptyValue is not set explicitly for a given data value (e.g. TXL file), a default value is used.
The default EmptyValue value may be set in the job ticket preferences:
using csi.Transaction.Shared;
using csi.Utility.Datapoints;
…
JobTicket jobTicket = new JobTicket();
jobTicket.Prefs.FieldPrefs.EmptyDataValueDefault = DataValue.EmptyValueType.blankField;
Changing the default EmptyDataValueDefault Preference must occur on a job by job basis.
If the jobticket preference setting is not set, the hard-coded default of ignoreValue is used.
See the Specifying Which Fields Render as a Blank Field section in this document for more information on the EmptyValue property.
To be backwards compatible (prior to February 2009), set EmptyDataValueDefault to blankField.
Remember that blank fields must be enabled in order for blank fields to be rendered.
A datapoint is designated as a blank field by setting its value to an empty string and setting its DXL/TXL emptyvalue attribute to blankField or by setting its EmptyValue object property to blankField (see csi.Utility.Datapoints.DataValue.EmptyValue).
The BlankWidth property of the DataValue class (or blankwidth attribute in DXL or TXL files) indicates the character width of a blank field.
If not set explicitly, a default value is used. The default for a specific datapoint may come from the datapoint dictionary of the FXL file being evaluated or, if it is not provide there, the Compliance Engine default of 10 is used.
Valid values include integers with a value of zero or greater. An empty data value with a blank width of zero is not rendered and will therefore not appear on the rendered document.
This property is ignored if the data value is not empty, or it is not designated as a blank field, or if blank fields are turned off.
The EmptyValue property of the DataValue class (or emptyvalue attribute in DXL or TXL files) indicates how an empty data value is treated when a document is rendered. Possible values include:
| blankField | Indicates that, when blank fields are turned on, an empty value is rendered as a blank field according to the blankwidth value. When blank fields are turned off, an empty value is treated as an empty string. |
| emptyString | Indicates that an empty value is treated as an empty string. This allows an empty value to be treated as an empty string, not a blank field. Datapoints with an emptyString value are generally not rendered, and therefore have limited utility. |
| ignoreValue | Indicates that an empty value is ignored and treated as if no value was supplied for the datapoint. |
If not set explicitly, a default value is used, which may vary depending upon the consuming application. The default may be set in the application preferences (FieldPrefs.EmptyDataValueDefault) or as an appSetting in the application configuration file:
<appSettings>
...
<add key="EmptyDataValueDefault" value="ignoreValue"/>
</appSettings>
Application preferences takes precedence over the configuration file setting. If neither is defined, the hard-coded default of ignoreValue is used.
A DataValue object (csi.Utility.Datapoints.DataValue or csi.Engine.Containers.DataValue) can be used with the Viewer Control or Compliance Engine. For the Viewer Control, use the SetData() or UpdateData() methods. For the Compliance Engine use the csi.Engine.Containers.DataValueList object.
In the following sample data value set, the form will render as follows (assuming that blank fields are enabled):
dp_01 will render as a blank field with a width of 10 characters.
dp_02 will not render because blankwidth is zero.
dp_03 will not render because emptyvalue is emptyString. If an empty string is not a valid value for the datapoint, an invalid value error is generated.
dp_04 will render as a “Apollo”, blankwidth and emptyvalue are ignored.
using csi.Engine.Containers;
…
DataValue dataValue01 = new DataValue( "dp_01", "" );
DataValue dataValue02 = new DataValue( "dp_02", "" );
DataValue dataValue03 = new DataValue( "dp_03", "" );
DataValue dataValue04 = new DataValue( "dp_04", "Apollo" );
…
DataValue01.BlankWidth = 10;
DataValue01.EmptyValue = DataValue.EmptyValueType.blankField;
DataValue02.BlankWidth = 0;
DataValue02.EmptyValue = DataValue.EmptyValueType.blankField;
DataValue03.BlankWidth = 10;
DataValue03.EmptyValue = DataValue.EmptyValueType.emptyString;
DataValue04.BlankWidth = 10;
DataValue04.EmptyValue = DataValue.EmptyValueType.blankField;
…
DXL files may be used with the Viewer Control, Compliance Engine,and SOAP interfaces. In the Viewer Control, use the SetData() or UpdateData() methods. In the Compliance Engine, use the csi.Engine.Containers.DataValueList and DataValue objects.
DXL files may be used with the Viewer Control, Compliance Engine,and SOAP interfaces. In the Viewer Control, use the SetData() or UpdateData() methods. In the Compliance Engine, use the csi.Engine.Containers.DataValueList and DataValue objects.
In the following sample data value set, the form will render as follows (assuming that blank fields are enabled):
dp_01 will render as a blank field with a width of 10 characters.
dp_02 will not render because blankwidth is zero.
dp_03 will not render because emptyvalue is emptyString.
dp_04 will render as a “Apollo”, blankwidth and emptyvalue are ignored.
<datavalues>
<datavalue name="dp_01" blankwidth="10" emptyvalue="blankField" />
<datavalue name="dp_02" blankwidth="0" emptyvalue="blankField" />
<datavalue name="dp_03" blankwidth="10" emptyvalue="emptyString" />
<datavalue name="dp_04" blankwidth="10" emptyvalue="blankField">Apollo</datavalue>
</datavalues>
TXL files may be used with the SOAP interfaces and with the Transaction Server.
A feature that is important to some CSi business partners involves setting the emptyvalue attribute to “ignoreValue”. This allows a TXL file to be generated (for example, via XSLT) that contains a number of empty values, and those empty values will be ignored.
In the following sample data set, the middle name node will cause a blank field to be generated (assuming blank fields are enabled), and the name suffix node will be ignored (regardless of whether blank fields are enabled).
<TransactionValues>
<Entities>
<Entity id="Borrower\_1">
<Roles>
<Role>Borrower</Role>
</Roles>
<Name>
<First>Will</First>
<Middle blankwidth="10" emptyvalue="blankField"></Middle>
<Last>Badger</Last>
<Suffix emptyvalue="ignoreValue"></Suffix>
</Name>
</Entity>
</Entities>
</TransactionValues>
Each usage type is listed along with how the field is rendered when Blank Fields are enabled and the value is designated as a blank field (e.g., its value is empty and emptyvalue=“blankField”).
The field is rendered with the appropriate blank field width.
If the datapoint is not supplied (null value), the field is not rendered.
Optional datapoints never generate a “form must be completed” margin message.
The field is rendered with the appropriate blank field width.
If the datapoint is Blankable, no margin message is displayed.
If the datapoint is NOT Blankable, a “form must be completed” margin message is displayed.
If a data value is not supplied (null value), the field is not rendered.
The field is rendered with the appropriate blank field width.
If the datapoint is Blankable, no margin message is displayed.
If the datapoint is NOT Blankable, a “form must be completed” margin message is displayed.
If a data value is not supplied (null value), the field is not rendered and a “form must be completed” margin message is displayed.
The field is rendered with the appropriate blank field width.
tructural_required datapoints never generate a “form must be completed” margin message because, if the form renders, that means that an empty value is valid.
If a data value is not supplied (null value), the form will not render, thus negating the use of a margin message.