HotDocs.VarMap Object

This object represents a variable mapping object. VarMaps are used to map HotDocs variables in a template to source names in a data source. The VarMap object represents three collections:

The VarMap object also includes some user interface to allow users to assign Mappings between Variables and SourceNames.

The purpose for mapping is to easily create associations between HotDocs variables and data fields in your application. HotDocs does not use these associations internally, but provides this mechanism for the integration to access them. For example, if your application contains a data store with information about customers, and the user wants to assemble a document using the HotDocs integration with data from your data store, you need to know how fields in your data store map to the HotDocs variables.

For example, you could hard code variable names into your application. This would work, as long as the HotDocs templates never changed and every reference field in the data store used that variable name.

An alternate solution would be to use the HotDocs mapping API. Using the mapping API, you can present a dialog with a list of all the fields in the data store and all the HotDocs variables in the template. Then the fields in the data store can be mapped to HotDocs variables. VarMap objects can be stored in HotDocs map (.HMF) files so the mapping only needs to be done once.

Finally, when your application is loading data into an answer collection for assembly, or when HotDocs queries the application for a value, you can look at the map collection to determine which field in your data store to use to provide the data element for the variable.

General Information

The following table shows the name and IID for each interface, as well as the version of HotDocs in which it was introduced. The primary interface and the main public interface exposed by this object is _VarMap2.

Methods

Method	Description
HDVariablesAdd	This method adds a new item to the HDVariables collection. However, it does not add a new HotDocs variable to the component file—it simply creates a new item representing a variable.
HDVariablesItem	This method retrieves a variable item from the HDVariables collection. A HotDocs variable is identified by a name (varname) and type (vartype). The index parameter is a number which will return the indexth variable from the collection.
MappingAdd	This method adds a new mapping and associates the variable name (varName) with the source name (srcName).
MappingAdd2	This method is similar to MappingAdd; it adds a new mapping and associates the variable name (varname) with the source name (srcname). The difference is that it also allows you to specify the write-back mode for the mapping using a value from the HDMappingBackfill enumeration. (See also MappingAddEx2.)
MappingAddEx2	This method is similar to MappingAdd; it adds a new mapping and associates the variable name (varName) with the source name (srcName). The difference is that it also allows you to specify the write-back mode for the mapping using a value from the HDMappingBackfill enumeration, and variable types for the variable and source from the HDVARTYPE enumeration. (See also MappingAdd2.)
MappingItem	This method retrieves the variable name (varname) and source name (srcname) for a mapping in the collection.
MappingItem2	This method, like MappingItem, retrieves the variable name (varName) and source name (srcName) for a mapping in the collection. The Index parameter can either be an index number or the name of a HotDocs variable. It also allows you to retrieve variable types for the variable and source, and the current write-back mode for the mapping.
MappingRemove	This method removes a mapping from the Mapping collection.
OpenComponentFile	This method opens a component file and populates the HDVariables collection with the components from the component file. (Any existing variables in the HDVariables collection are not erased.)
OpenMapFile	This method opens a HotDocs map file, reads in the mappings, and populates the collections. Any existing members of the collections will not be erased.
SaveMapFile	This method saves the mappings to the filename file. If a file already exists, it is overwritten.
ShowUserInterface	This method shows the mapping user interface where users can assign mappings between HotDocs variables and source names.
SourceNamesAdd	This method adds a new source to the SourceNames collection. (See also SourceNamesAdd2.)
SourceNamesAdd2	This method adds a new source to the SourceNames collection. It is similar to SourceNamesAdd, but it accepts a third parameter, backfill, which allows you to specify the write-back mode for the source.
SourceNamesItem	This method retrieves the source name and source type from the SourceNames collection. The Index parameter is the index number for a position in the SourceNames collection. (See also SourceNamesItem2.)
SourceNamesItem2	This method retrieves the source name and source type from the SourceNames collection. The Index parameter is the index number for a position in the SourceNames collection. It is similar to SourceNamesItem, but it accepts a fourth parameter, backfill, which returns the write-back mode for the source.
SourceNamesRemove	This method removes the Indexth mapping from the SourceNames collection.

Properties

Property	Description
Application	[Read-only] This property returns a reference to the Application object.
DefaultBackfill	[Read/Write] This property indicates the default write-back mode for mapped variables.
HDVariablesCount	[Read-only] This property returns the number of items in the Variables collection.
MappingCount	[Read-only] This property returns the number of items in the Mappings collection.
MapTextAndMultipleChoice	[Read/Write] This Boolean property allows variable mapping between Multiple Choice and Text values. (If it is true, Text values may be mapped to Multiple Choice values and vice versa.)
ShowBackfillColumn	[Read/Write] This Boolean property is used to hide (false) or show (true) the "Write Back" column in the mapping interface. This column allows users to select the write-back mode for each variable mapping.
SourceNamesCount	[Read-only] This property returns the number of items in the SourceNames collection.