Guidelines for Creating InfoPath 2007 Converters
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Summary: Learn how to create InfoPath 2007 converters for importing data from other types of forms and data sources, and for importing and exporting form templates from other form file formats. (24 printed pages)
Microsoft Corporation
May 2007
**Applies to:**Microsoft Office InfoPath 2007
Contents
Overview of Converters in InfoPath 2007
Converter Types and Examples
Converter Development Scenarios
Converter Requirements
Accessing Converters
Creating Form Template Importers and Exporters
Creating Form Data Importers
Conclusion
Additional Resources
Microsoft Office InfoPath 2007 includes enhancements that enable you to access external converter applications within InfoPath. Converter applications can import data into forms as they are filled out and import and export form templates as they are designed. At Microsoft Office Marketplace, customers can obtain converters and other products and services that work with Microsoft Office products.
Benefits of using InfoPath converters include the following:
The converters can be accessed from within InfoPath.
The InfoPath framework provides information to help import forms and data.
The imported forms and data are available immediately after import.
InfoPath converters fall into two categories:
Form template importers and exporters
Data importers
This article describes the goals of InfoPath converter applications, how converters are built, and how you can access them in Office InfoPath 2007.
Form template importers were introduced in Microsoft Office InfoPath 2003 Service Pack 1, and support for them has been expanded in Office InfoPath 2007. A form template importer enables an external application to create an InfoPath form template by converting a file from another format. For example, a form template importer could create an InfoPath form template from a paper form, an HTML page, or another application's format.
Office InfoPath 2007 includes form template importers for Microsoft Office Word forms and Microsoft Office Excel forms. Both importers were created by using the InfoPath converter framework described in this article. To use these importers, start designing a form template in InfoPath, and then click Import in the Design a Form Template dialog box. Alternatively, if you are already designing a blank form template, click Import Form on the File menu. For more information about using the Word importer, see Convert a Word document to an InfoPath form template.
Form template exporters are new to InfoPath 2007. You can use them to export InfoPath form templates into third-party file formats.
Data importers bring data from completed forms in other formats into an InfoPath form. Examples of data that can be imported include scanned paper forms, faxes received electronically, and forms or documents in another file format.
Form template importers and data importers can be designed to work with the same formats: one creates a blank form, and another imports filled-in forms. They can also be designed to do only one of the two tasks.
Wingtip Toys has many paper forms that track factory floor production information. They want to deploy portable computers that contain InfoPath forms to collect this information. To create matching InfoPath forms quickly, they use a form template importer. It is designed to scan paper forms and create InfoPath form templates that have a similar layout and also have InfoPath features such as editing controls.
Wingtip Toys also has many completed paper forms in storage. They want an easy way to move these forms into their new computer system as InfoPath forms. They create an InfoPath form template that matches their existing paper form. Using a data importer, they can scan existing paper documents and insert the recognized text into InfoPath forms.
Microsoft wants users who currently have forms and data in other formats to be able to easily move their processes into InfoPath forms. Importers should have broad appeal to InfoPath users, and they should accurately import the formats they support. Importers should extend and add value to the InfoPath system.
InfoPath 2007 does not give users functionality that helps them directly interact with paper forms. But with an appropriately designed form template importer, you can treat a paper form as a template for creating an InfoPath form template. Similarly, with an appropriately designed data importer, you can convert paper forms that contain data into InfoPath forms.
You can scan a paper form as part of the import process and then create an InfoPath form template that has a similar layout. The boxes on the paper form would be replaced with controls, and a data source would contain fields with names derived from names on the paper. You could also create a data importer to scan matching paper forms and copy recognized text from the paper forms into corresponding InfoPath electronic forms.
Users can create electronic forms in several applications. These applications can have specific form design functionality. An InfoPath form template importer for the application's form file format interprets the layout and functionality of the form, such as controls or typing areas, and creates an InfoPath 2007 form template.
Likewise, you could use a data importer to move information into InfoPath forms from completed electronic forms in other applications.
You could also have an importer for HTML or ASP.NET forms. A form template importer could create an InfoPath form template with the same layout, connect the form to the same data sources, and perhaps preserve some business logic in the form. In this scenario, you probably would not need to convert existing data because that data would already be in a database.
Anyone can apply to have a product listed on Office Marketplace. For an overview, including how to join, see Become an Office Marketplace provider. For an introduction to the requirements for products on the Office Marketplace, see Requirements and instructions for applying to the Office Marketplace.
Figure 1 shows an example of how you can connect to the Office Marketplace from InfoPath.
Figure 1. Linking to install a new converter
In addition to meeting all the requirements set forth by Office Marketplace, InfoPath converter applications must provide the following:
A Web site where users can obtain the software.
An installer application to configure the software for use in InfoPath.
Customer support for troubleshooting problems with the converter.
Support for the application in future versions of Microsoft Office.
Regarding testing, converter providers must do the following:
Test the behavior of their importer software, Web site, and installer application.
Provide a copy of the software, with any necessary licenses, to be used by Office testers to enable them to provide feedback before its release.
Converter providers must provide a dedicated contact for questions that arise while the functionality of the importer is being verified. When the product is released to customers, converter providers must also provide online or telephone customer help and easy-to-use Help content.
Converters must be able to reliably import or export at least one file format, and they should provide useful error messages whenever necessary. Converters must also meet the following user expectations of InfoPath forms:
Original form layout should be preserved.
Forms can make use of relevant InfoPath features, such as binding text values to Text Box controls, and binding dates to Date Picker controls.
Forms can be further designed and completed in InfoPath.
The converter should not disclose personal information in unauthorized ways. In addition, all COM objects exposed by your converter should be marked as unsafe for initialization and scripting so that they cannot be used by a malicious Web page.
You can access form template importers and exporters while you are designing form templates, and you can access data importers while you are completing forms. InfoPath provides a similar user experience for both kinds of importers. Figure 2 shows the Import Wizard dialog box with the Microsoft Office Word Form form template converter selected.
Figure 2. Form Template Import Wizard
Figure 3 shows the Import Form Data dialog box, which provides access to form data importers after a user installs them.
Figure 3. Import Form Data dialog box
The installation process for both types of importers is very similar. You should install importers through an installer application. The installer is responsible for putting the relevant applications and libraries on your system, registering them for use with Microsoft Windows, and registering those libraries for use with InfoPath.
Tali has a stack of paper forms that take up space in filing cabinets and are difficult to find information in. She recently installed InfoPath 2007 and wants to move those forms and their data into InfoPath. She uses the Import Form command on the File menu to connect to Office Marketplace, where she discovers a variety of importers.
Tali successfully downloads and installs a converter that promises to import her paper forms. After installation, she restarts InfoPath, opens the Import Wizard, and sees the Contoso importer, as shown in Figure 4.
Figure 4. Selecting the Contoso Paper to InfoPath Form Importer
Tali can then select a file to import. In this case, she selects a scanned image in TIFF format, as shown in Figure 5. She can also set options by using the dialog box provided by the importer.
Figure 5. Selecting the file to import
After Tali clicks Finish, the importer interprets the source file and creates an InfoPath form template. The template opens so that she can continue editing. After she creates the form template, she installs a data importer, which can accept a scanned paper form as input. It uses the data from the form to complete an instance of the InfoPath form.
Tali opens a blank form and starts the Import Form Data wizard. She selects the data importer that she installed, and clicks Next. When prompted, she scans in the form to be converted. In the data importer user interface, she can correct the scanned-in data as needed. She clicks a button, and the importer fills the empty InfoPath form with the data from the paper form. Tali saves the InfoPath form and continues to import the rest of her paper forms.
Form template converters specify a list of file types they support, and they parse those file types to produce an InfoPath form template with manifest (.xsf), view (.xsl), and other files that make up an InfoPath form template file (.xsn).
To view the kinds of files that an InfoPath form template contains, create or open a form template in design mode, and then click Save as Source Files on the File menu. For information about the schema of the InfoPath form definition file (manifest.xsf), see the InfoPath 2007 XSF Schema Reference.
Figure 6 shows the workflow for an InfoPath form template importer.
Figure 6. Form template importer workflow
The form template converter should be a standard Automation object. The IPDESIGN.dll that is installed in C:\Program Files\Microsoft Office\Office12 provides the type library that exposes the interfaces that are required to create a form template converter. InfoPath 2007 should be able to create the converter object by using the CoCreateInstance function with the ProgID stored in the registry. The form template converter implements the interfaces provided by the InfoPath converter framework to create the basic functions of the converter such as Initialize(), Import(), Export(), and UnInitialize().
To show or hide converters in a given version of InfoPath, InfoPath must be able to determine the versions of the converter framework that are supported by the converter. A converter can support multiple versions of the converter framework.
Supporting a version of the converter framework implies that the converter does the following:
Implements a specific COM interface.
Produces a specific file format version when called through that interface.
Table 1 lists the versions of the framework that exist with InfoPath 2007.
Table 1. Converter framework versions
Converter Framework Version |
Interface Version |
File Format Version |
Included With |
---|---|---|---|
11.0 |
InfoPath 2003 |
InfoPath 2003 Service Pack 1 and later |
|
12.0 |
InfoPath 2007 |
InfoPath 2007 |
InfoPath 2007 can use converters that support either version 11.0 or version 12.0 of the framework. For converters that support both versions, only the IFormTemplateConverter2 (version 12.0) interface is used.
InfoPath 2003 supports only version 11.0 of the framework. Because framework versioning is new in InfoPath 2007, InfoPath 2003 displays all converters regardless of version; however, converters that do not implement the IFormTemplateConverter interface will not function correctly.
Future versions of InfoPath will support one or more versions of the converter framework. Converters that correctly register their supported versions will be shown in the versions of InfoPath that also support that version of the framework. InfoPath has not determined an deprecation policy for framework versions.
When the converter is installed on a user's computer, it should add registry information in addition to the standard COM registration entries. Installation of converters is in the HKEY_LOCAL_MACHINE branch of the registry, so users are expected to have software installation permissions. InfoPath uses the information in the registry to load the converter and display converter properties.
Converters can be installed in one or both of the registry branches, depending on their capabilities.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Infopath\Converters\Import\ConverterProgID
or
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Infopath\Converters\Export\ConverterProgID
Converters are symmetrical, so both the import key and the export key must contain the following information.
@DefaultLCID
\LCID
@Name
@Description
@Extensions
@ExtensionsDescription
\Versions
Table 2 describes the registry entries for an InfoPath converter.
Table 2. Converter registry entries
Name |
Type |
Max Len |
Description |
---|---|---|---|
ConverterProgID |
key |
39 (COM limit) |
COM ProgID of the converter. InfoPath uses this information to load the converter. |
DefaultLCID |
REG_DWORD |
LONG |
Default LCID to use if the converter does not support the current LCID used in InfoPath. For example, the DefaultLCID is 1033 and the current LCID is 1034, so InfoPath loads the strings stored under key 1033. |
LCID |
key |
LONG |
Locale ID. For example, the US English LCID is 1033. Gives the converter an option to support multiple languages. |
Name |
REG_SZ |
64 |
Display name of the converter. |
Description |
REG_SZ |
128 |
Description of the converter |
Extensions |
REG_SZ |
32 |
File name extensions that the converter can handle, separated by a space, for example, "doc dot." |
ExtensionsDescription |
REG_SZ |
64 |
Description of the file name extensions that the converter can handle, for example, "Microsoft Office Word forms." |
Versions |
key |
Not applicable |
The Versions key contains one REG_SZ value for each version of the converter framework supported by the converter. For example, a converter that supports version 11.0 and version 12.0 of the framework would contain the following \Versions @11.0 @12.0 The value of these string values is not significant and should be left blank. InfoPath considers only the name of the string value when determining the converters to display. If the Versions key is omitted, the converter is assumed to support only version 11.0 of the framework. If the Versions key exists but is empty, the converter is not displayed in InfoPath 2007 or future versions. |
![]() |
---|
When a form template converter is uninstalled, it should remove these registry keys and any program files that were created during installation. |
All form template converters must implement the IFormTemplateConverter2 interface.
The following listing shows the Interface Definition Language (IDL) definition for the IFormTemplateConverter2 interface.
[
object,
uuid(096cd705-0786-11d1-95fa-0080c78ee3bb),
dual, nonextensible,
helpstring("IFormTemplateConverter2 Interface"),
pointer_default(unique)
]
interface IFormTemplateConverter2 : IDispatch
{
[id(DISPID_IFORMTEMPLATECONVERTER2_INITIALIZE)]
HRESULT Initialize(
[in] IConversionManager* pConversionManager);
[id(DISPID_IFORMTEMPLATECONVERTER2_UNINITIALIZE)]
HRESULT UnInitialize();
[id(DISPID_IFORMTEMPLATECONVERTER2_IMPORT)]
HRESULT Import(
[in] BSTR srcPath,
[in] BSTR destPath,
[in] VARIANT_BOOL vfShowUI,
[out] BSTR* pMessage);
[id(DISPID_IFORMTEMPLATECONVERTER2_EXPORT)]
HRESULT Export(
[in] BSTR srcPath,
[in] BSTR destPath,
[in] VARIANT_BOOL vfShowUI,
[out] BSTR* pMessage);
[id(DISPID_IFORMTEMPLATECONVERTER2_SHOWOPTIONSDLG)]
HRESULT ShowOptionsDialog(
[in] long lHwnd,
[in] VARIANT_BOOL fExporting);
[id(DISPID_IFORMTEMPLATECONVERTER2_SETLCID)]
HRESULT SetLcid(
[in] UINT lcid);
};
![]() |
---|
The IFormTemplateConverter2 interface supersedes the IFormTemplateConverter interface from InfoPath 2003 Service Pack 1. IFormTemplateConverter is deprecated in InfoPath 2007, but it is still present. Existing converters that implement IFormtemplateConverter will continue to work in InfoPath 2007. New converters should implement IFormTemplateConverter2, and optionally, they can implement IFormTemplateConverter if InfoPath 2003 compatibility is desired. IFormTemplateConverter is documented in Build a Custom Importer [InfoPath 2003 SDK Documentation]. |
Table 4 provides links to topics that document the methods of the IFormTemplateConverter2 interface.
Table 4. IFormTemplateConverter2 interface methods
Method |
Description |
---|---|
Converts an InfoPath form template to a provider-defined format. |
|
Converts a provider-defined format to InfoPath form template files. |
|
Initializes the custom importer or exporter. |
|
Displays a custom Import Options dialog box to the user when the Options button is clicked in the last step of the wizard. |
|
Sets the language used by the custom importer or exporter. |
|
Uninitializes the custom importer or exporter. |
The IConversionManager interface is implemented by InfoPath and is available to converters during import or export.
The following listing shows the IDL definition for the IConversionManager interface.
enum ConversionPreference
{
prefSupportProgressDialog = 1,
prefSupportOptionsDialog = 2,
};
[
object,
uuid(096cd703-0786-11d1-95fa-0080c78ee3bb),
nonextensible,
helpstring("IConversionManager Interface"),
pointer_default(unique)
]
interface IConversionManager : IUnknown{
[propget] HRESULT ProductVersion(
[out, retval] BSTR* pProductVersion);
HRESULT SetPreference(
[in] ConversionPreference conversionPreference);
HRESULT SetProgressDialogPosition(
[in] UINT position);
HRESULT SetProgressDialogCaption(
[in] BSTR caption);
};
[
object,
uuid(096cd704-0786-11d1-95fa-0080c78ee3bb),
nonextensible,
helpstring("IConversionManager2 Interface"),
pointer_default(unique)
]
Table 5 provides links to topics that document the members of the IConversionManager interface.
Table 5. IConversionManager interface members
Property/Method |
Description |
---|---|
Gets the current version of InfoPath. |
|
Sets the preferences of the custom importer. |
|
Sets the caption of the Import Progress dialog box. |
|
Sets the value of the Progress bar in the Import Progress dialog box. |
![]() |
---|
The IConversionManager interface exists in both InfoPath 2003 and InfoPath 2007. |
The IConversionManager2 interface was added in InfoPath 2007. It extends the IConversionManager interface to enable callers to set the status text in the Import Progress dialog box.
interface IConversionManager2 : IUnknown{
HRESULT SetProgressDialogStatus(
[in] BSTR caption);
}
Table 6 provides a link to the single method topic of the IConversionManager2 interface.
Table 6. IConversionManager2 interface member
Method |
Description |
---|---|
Sets the window text of the Import Progress dialog box in the InfoPath 2007 Import Wizard. |
If errors occur during conversion, converters should return an error code and populate the IErrorLog object. Users can view the error information stored in the IErrorLog object.
Form template import converters can specify messages to be shown in the Design Checker task pane after a successful import. Messages appear in the Design Checker task pane any time it is shown, until you remove the ImportErrors.xml file from the form template using the Resource Files command on the Tools menu.
An importer typically uses Design Checker messages to warn the user about parts of the form template that might not have imported as expected, or to give the user instructions for the next steps in creating a form template.
InfoPath reads Design Checker messages from the ImportErrors.xml file, which the converter includes in the form template. If the file is not present, InfoPath does not show import errors. If the file is present, InfoPath displays messages in the Design Checker task pane, subject to the following limits:
Maximum Errors per file: 200
Maximum text in an error: 512 characters
The following listing shows a sample ImportErrors.xml file.
<importErrors xmlns="http://schemas.microsoft.com/office/infopath/2006/ImportErrors">
<view name="View 1">
<errorCategory categoryId="0" name="">
<importError shortErrorString="Object of type OLEObject was replaced by a placeholder">
The embedded object of type Word.Picture.8 in the Microsoft Office Word file cannot be imported.
</importError>
<importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
</importError>
<importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
</importError>
<importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
</importError>
<importError shortErrorString="Object may be positioned incorrectly">
The correct position of the floating object cannot be determined.
</importError>
<importError shortErrorString="Error importing page borders">
InfoPath does not support setting borders for the page.
</importError>
</errorCategory>
</view>
</importErrors>
Figure 7 shows how the resulting messages are displayed in the Design Checker task pane.
Figure 7. Import messages in the Design Checker task pane
Table 7 describes the elements and attributes in the ImportErrors.xml file.
Table 7. Elements and attributes of the ImportErrors.xml file
Name |
Type |
Description |
---|---|---|
importErrors |
element |
Root element for the file. The target namespace must be http://schemas.microsoft.com/office/infopath/2006/ImportErrors |
view |
element |
Specifies the view that the enclosed errors apply to. |
view/@name |
Attribute |
Name of the view. |
errorCategory |
element |
Category for the errors. In InfoPath 2007, only one category is allowed per file. |
errorCategory/@categoryId |
attribute |
Must be "0". |
errorCategory/@name |
attribute |
Name of the error category. Reserved for future use; ignored in InfoPath 2007. |
importError |
element |
Specifies one Design Checker warning. The content of this element is the text shown when the short error string is clicked in the Design Checker task pane. |
importError/@shortErrorString |
attribute |
The short error string shown in the Design Checker task pane. |
The following code listing shows the InfoPath form definition file (manifest.xsf) entries to expose the ImportErrors.xml file.
<xsf:file name="ImportErrors.xml">
<xsf:fileProperties>
<xsf:property name="fileType" type="string" value="resource">
</xsf:property>
<xsf:property name="filePurpose" type="string" value="ImportErrors">
</xsf:property>
<xsf:property name="displayOnLoad" type="string" value="yes">
</xsf:property>
</xsf:fileProperties>
</xsf:file>
![]() |
---|
You can copy the manifest.xsf file entry for ImportErrors.xml from this example. |
Form data importers are used to bring data from a completed form in another format into an InfoPath form. An example might be a stack of paper forms that you need to scan and then insert the text into an InfoPath form.
Figure 8 shows the workflow for a data importer to import data from paper forms.
Figure 8. Form data importer workflow
Form template importers receive limited control over the user experience. They have access only to an Options dialog box and an Import Progress dialog box. However, to allow for importing data directly from a source, form data importers allow the importer to display whatever user interface is necessary: File Open dialog boxes, custom data import dialog boxes, and progress dialog boxes.
The IPEDITOR.dll installed in C:\Program Files\Microsoft Office\Office12 provides the type library that exposes the interfaces required to create a form data importer.
Data importers must be registered by creating a registry key with the ProgID of the importer. They must register under the HKEY_LOCAL_MACHINE registry branch. The importer itself should be a standard COM object.
InfoPath uses the list of ProgID values at this location to determine the importers that are available to the user, and to create the COM object.
HKEY_LOCAL_MACHINE
\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ImporterProgID
Table 8 describes the InfoPath data importer registry key.
Table 8. InfoPath data importer registry key
Name |
Type |
Length |
Description |
---|---|---|---|
ImporterProgID |
key |
39 |
COM ProgID of the importer. InfoPath uses this information to load the importer. |
InfoPath uses the name and description data under each importer's ProgID to display information to the user. InfoPath looks for an LCID key for the current Office language to retrieve the name and description.
There can be any number of LCID values to provide localized resources to the Import Form Data wizard. If there is no LCID for the current Office language, InfoPath references the DefaultLCID value to determine what language to use. If there is no DefaultLCID, the converter is not listed.
Used Name/Value pairs:
HKEY_LOCAL_MACHINE
\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ImporterProgID\
@DefaultLCID
and
\SOFTWARE\Microsoft\Office\12.0\InfoPath\Data Importers\ ImporterProgID\LCID
@Name
@Description
Table 9 describes the InfoPath data importer LCID registry keys and values.
Table 9. InfoPath data importer LCID registry keys and values
Name |
Type |
Length |
Description |
---|---|---|---|
DefaultLCID |
REG_SZ |
LCID to retrieve localized names and descriptions from if current Office language is not supported. |
|
LCID |
Key |
No limit on number of supported locales. There must be an LCID entry for the DefaultLCID value. |
|
Name |
REG_SZ |
64 |
Used to display the name to the user. |
Description (Optional) |
REG_SZ |
255 |
Displays information about the converter being used. |
Long Strings Names longer than 64 characters are not listed, and descriptions longer than 255 characters are truncated.
Missing Name The importer is not listed.
Missing Description No text is shown.
Implement the IInfoPathDataImporter interface to create a custom data importer.
The following listing shows the IDL definition for the IInfoPathDataImporter interface.
[
object,
uuid(096cd6d9-0786-11d1-95fa-0080c78ee3bb),
helpstring("IInfoPathDataImporter Interface"),
pointer_default(unique),
nonextensible
]
interface IInfoPathDataImporter : IUnknown
{
HRESULT Initialize(
[in] UINT lcid);
HRESULT Import(
[in] IPropertyBag* pPrintSettings,
[in] IEnumUnknown* punkViewControls );
HRESULT Uninitialize();
};
After the user selects the importer to use, InfoPath starts it by calling the required Initialize method. The importer could fail at this point because of missing system resources, invalid license, or other checks.
To allow each importer to target multiple locales, InfoPath provides the locale as an Initialize method parameter for the importer. The importer can choose to display a localized user interface or implement a fallback locale, such as English – International.
The Import method provides access to the form's controls collection and print settings. This method is called one time per importer instance.
The converter might not support the current locale, but the developer of the converter must determine whether it is appropriate to fall back to the default language, fall back to another language, or fail to run.
The property bag that is implemented using the IPropertyBag interface passes print setting information to the converter. It has read-only access.
The following listing shows the IDL definition for the IIPropertyBag interface.
Interface IPropertyBag
{
HRESULT Read(
LPCOLESTR pszPropName,
VARIANT* pVar,
IErrorlog* pErrorLog);
// This will return E_ACCESSDENIED
HRESULT Write(
LPCOLESTR pszPropName,
VARIANT* pVar);
}
The print settings allow a data importer to make assumptions about how the form might be printed from InfoPath to paper. Because the user can change the values at print time, only the form's default print settings are given and not the actual print-time settings.
Table 10 describes the properties provided for print settings.
Table 10. Print settings properties
Property |
Description |
---|---|
PageSize |
Returns an unparsed string that corresponds to the current page size: A4, B4, Letter, and so on. |
TopMargin |
numeric |
BottomMargin |
numeric |
LeftMargin |
numeric |
RightMargin |
numeric |
MarginUnitsType |
in or cm |
![]() |
---|
These values might not be available if the user has no installed printers. |
The controls collection provides an ENUM for accessing individual IInfopathViewControl objects that represent the controls in the current view. The collection is generated at the time that the importer is created. It is not updated during the import process.
The controls collection does not provide access to higher-level InfoPath controls, such as Optional Section, Repeating Section, or Repeating Table controls. Table 11 provides the complete list of included and excluded controls in the collection.
Table 11. Included and excluded controls
Included Controls |
Excluded Controls |
---|---|
Textbox |
Section |
Rich Text Box |
Optional Section |
Drop-Down List Box |
Repeating Section |
List Box |
Repeating Table |
Date Picker |
Master/Detail |
Check Box |
Expression Box |
Option Button |
Vertical Text |
Bulleted List |
Button |
Numbered List |
Hyperlink |
Plain List |
Scrolling Region |
Picture |
Choice Group |
Ink Picture |
Repeating Choice Group |
File Attachment |
Choice Section |
Combo box |
Repeating Recursive Section |
Custom Controls (ActiveX) |
|
Multi-select |
Implement the IInfoPathViewControl interface to represent a control present in the imported view.
The following listing shows the IDL definition for the IInfoPathViewControl interface.
[
object,
uuid(096cd6da-0786-11d1-95fa-0080c78ee3bb),
helpstring("IInfoPathViewControl Interface"),
pointer_default(unique),
nonextensible
]
interface IInfoPathViewControl : IUnknown
{
[propget]
HRESULT Left(
[out, retval] long* plLeft);
[propget]
HRESULT Top(
[out, retval] long* plTop);
[propget]
HRESULT Width(
[out, retval] long* plWidth);
[propget]
HRESULT Height(
[out, retval] long* plHeight);
[propget]
HRESULT ControlType(
[out, retval] BSTR* pbstrControlType);
[propget]
HRESULT DataType(
[out, retval] BSTR* pbstrDataType);
[propget]
HRESULT NodeName(
[out, retval] BSTR* pbstrNodeName);
[propget]
HRESULT Value(
[out, retval] BSTR* pbstrValue);
[propput]
HRESULT Value(
[in] BSTR bstrValue);
};
Table 12 describes the properties of an IInfopathViewControl object.
Table 12. Properties of an IInfopathViewControl object
Property |
Type |
Limit |
Description |
---|---|---|---|
Top |
LONG |
None |
Offset of the control from the top of the view. |
Bottom |
LONG |
None |
Offset of the control from the bottom of the view. |
Left |
LONG |
None |
Offset of the control from the left of the view. |
Right |
LONG |
None |
Offset of the control from the right of the view. |
DataType |
BSTR |
None |
XSD Type of the XML value. |
ControlType |
BSTR |
None |
xd:xctname attribute from the XSL. |
NodeName |
BSTR |
None |
XML Node name for the current field (base name, not fully qualified name). |
Value |
BSTR |
None |
Current XML value of the control (read/write). |
InfoPath lets the importer set the Value property of a control. The return is only success or failure (HRESULT). Failures could result from a value that was rejected by business or schema logic in the form. InfoPath ignores failures.
Values that are passed to the importer could differ from the final value that is stored in the XML because of the data formatting functionality in InfoPath. Therefore, passing a date value of "1/1/2000" stores the UTC value in the XML. If the actual stored value is needed, you should check the Value property after setting it.
Calculations that modify field values, rules that set values, or custom code could affect the value of other fields as values in the importer are changed. Some controls are limited to certain values, as if a user were entering data. Table 13 contains the appropriate values for specific controls.
Table 13. Control values
Control |
Type |
Description |
---|---|---|
Text Box |
BSTR |
Any xsd:string value. |
Rich Text Box |
BSTR |
XHTML string with XHTML namespaces on top level elements. This XHTML string will be parsed into a tree and tree will be inserted into the XML DOM. |
Drop-down List Box |
BSTR |
Any xsd:string value. |
List Box |
BSTR |
Any xsd:string value. |
Date Picker |
BSTR |
Any xsd:string value. |
Check Box |
BOOL |
BSTR, values accepted are "CHECKED," "SELECTED." Any other value indicates unselected. |
Option Button |
BSTR(set_value), BSTR(get_value) |
Values accepted are "CHECKED," "SELECTED." Any other value indicates unselected. |
Bulleted List Numbered List Plain List |
BSTR |
Any xsd:string value. |
Picture Ink Picture |
BSTR |
Any xsd:base64Binary data. |
After the data importer has returned from the Import method call, InfoPath calls the importer's UnInitialize method to perform any necessary cleanup.
You can create an external converter application that can be accessed from InfoPath by creating a COM object that implements the appropriate interfaces exposed by the type libraries in IPDESIGN.dll and IPEDITOR.dll. These applications can import data into InfoPath forms as they are filled out, or they can import and export form templates from InfoPath design mode. You can create InfoPath converters and have them listed on Microsoft Office Marketplace, the Web site that customers visit to obtain products and services that work with Microsoft Office products.
For more information about developing with InfoPath, see the following resources:
-
Information about InfoPath developer resources.
Microsoft Office InfoPath Portal
Office Online site that provides information about InfoPath form design, declarative logic, and other features available through the InfoPath user interface.
InfoPath 2007 Developer Reference
Information about developing form templates and applications for Office InfoPath 2007 using scripting and COM languages.
Welcome to the InfoPath Developer's Reference for Managed Code Form Templates
Information about developing form templates and applications for Office InfoPath 2007 using managed code.
Welcome to the Microsoft Office Forms Server 2007 SDK
Information about developing applications for InfoPath Forms Services, which is available as part of either Microsoft Office Forms Server 2007 or Microsoft Office SharePoint Server 2007.