Passing Data into a Form: Input Parameters
This blog article discusses a new feature of Microsoft InfoPath 2007 that makes it possible to pass data into an InfoPath form at load time. A typical example would be retrieving records from a database for a particular user. At load time a ‘userID’ can be passed into the form. This userID can then be used to query the database and load the form with the user's data.
Parameters can be passed into InfoPath form templates (XSNs) or InfoPath Forms (XMLs). The syntax for specifying input parameters is the same for both. This article focuses primarily on InfoPath client scenarios, but should apply for the most part to server scenarios as well.
How to Pass Parameters into an InfoPath Form:
There are two ways of launching an InfoPath form with parameters
1) URL
The syntax for passing parameters via the URL is the standard syntax for query parameters. For example:
http://www.foo.com/bar.xsn?baz=1&biz=2
Here two input parameters have been passed into the form namely 'baz' and 'biz'. Their respective values are 1 and 2. The 'Accessing Input Parameters in Form Code' section talks about how these values are stored and accessed in InfoPath code.
The URL syntax can be used in a number of places like
- Launching an InfoPath form in a browser by typing the URL into the address bar
- Pasting the URL to a form or a form template into an email
- Using the URL inside methods like NewFromFormTemplate, New, Open (XmlForms collection)
2) Command Line
The syntax for passing parameters via the command line is as follows:
infopath.exe “C:\foo\bar.xml” /InputParameters "baz=1&biz=2"
The switch /InputParameters is used to specify that parameters are being passed into the form, followed by the name/value pairs of input parameters.
Accessing Input Parameters in Form Code
Parameters passed into an InfoPath form template or form, are available during the Loading event as a read-only collection of name/value pairs. In order to access these parameters you will need to write code that reads from this collection. The InputParameters collection is exposed in all three InfoPath programming models – it is thus available in JScript, InfoPath 2003 SP1 managed code or InfoPath 2007 managed code. This example uses C# and the InfoPath 2007 managed object model. Syntax for the legacy models follows. The steps below outline how to add code that access the Input Parameters passed into a form.
- In the InfoPath designer, click on Tools menu -> Programming menu item.
- In the fly-out menu select the Loading event (will be On Load in older InfoPath versions).
- This will launch the appropriate IDE (MSE or VSTA or the Visual Studio Toolkit) with the code spit for the loading event inserted.
- Add the following code to access the input parameters ‘baz and ‘biz used in the examples above (example is in C# using InfoPath 2007 Managed Object Model)
public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
// Assign the value of the parameter 'baz' to the string 'bazValue'. bazValue = 1
string bazValue = e.InputParameters["baz"];
// Assign the value of the parameter 'biz' to the string 'bizValue'. bi000zValue = 1
string bizValue = e.InputParameters["biz"];
// Code that uses the parameters passed in to do whatever needs to be done
// Example would be to create a custom query using these values and populate a table based
// on the data returned
}
Input Parameter Syntax for Legacy Object models
The following two code samples contain code for the InfoPath 2003 SP1 Managed Object Model (C#) and Jscript (InfoPath 2003 Object Model)
1) C# InfoPath 2003 SP1
In the InfoPath 2003 SP1 Object Model the InputParameters collection is exposed off the XDocument object not off the eventArgs object. Also since this is a new feature the XDocument object needs to be cast to the newer _XDocument3 interface to get access to the InputParameters collection. Hence the first line of code in the sample below.
[InfoPathEventHandler(EventType = InfoPathEventType.OnLoad)]
public void FormEvents_OnLoad(DocReturnEvent e)
{
// Cast XDocument to _XDocument3 to get access to the InputParameters collection
_XDocument3 infopath2007XDocument = (_XDocument3)e.XDocument;
string bazValue = infopath2007XDocument.InputParameters["baz"].Value;
string bizValue = infopath2007XDocument.InputParameters["biz"].Value;
}
2) JScript
function XDocument::OnLoad(eventObj)
{
var bazValue = eventObj.XDocument.InputParameters["baz"].Value;
eventObj.XDocument.UI.Alert(bazValue);
}
Help
Comprehensive documentation and additional code samples for this feature can be found under MSE Help or VSTA Help.
Aditi Desai
Software Design Engineer in Test
