Professional Visual Studio 2005 (2006) [eng]

Chapter 54

initial code that is generated for a typical C# InfoPath project. The generated class in Visual Basic is identical in functionality:

public class InfoPathProject4

{

private XDocument thisXDocument; private Application thisApplication;

public void _Startup(Application app, XDocument doc)

{

thisXDocument = doc; thisApplication = app;

// You can add additional initialization code here.

}

public void _Shutdown()

{

}

}

In addition to these two code files, XML-based files are generated from the InfoPath template itself. At a minimum, you’ll have the following files:

As you continue to edit the form in InfoPath, additional files will be automatically added to the solution in Visual Studio, including additional view.xsl files for extra views of the form, and an upgrade.xsl file for upgrading an InfoPath document from a previous version.

766

InfoPath 2003 Toolkit

Switching Between Visual Studio and InfoPath

Unlike regular projects, to edit the user interface of an InfoPath project you have to go through a different process. This is because the actual user interface design is performed in InfoPath itself, rather than being housed inside the Visual Studio 2005 IDE.

Initially, when you first create or open the InfoPath project, Visual Studio automatically starts InfoPath and opens the form template, ready for user interface design. However, once you’ve closed it, there’s no immediately easy way to open the designer again. Instead you need to either use the Tools Open InfoPath menu command (see Figure 54-4) or right-click on the project’s entry in the Solution Explorer and choose Open InfoPath. This command not only opens InfoPath as it suggests, but also opens the form in Design view, ready for any customizing you need to perform.

Figure 54-4

All user interface design takes place inside InfoPath instead of Visual Studio 2005 (see Figure 54-5). This includes adding any data fields and binding them to a Data Source (although you can add a secondary Data Source with code later), as well as all aspects of the form’s layout, including additional views, controls such as buttons and text boxes, and the InfoPath-specific features such as repeating and optional sections.

Once the user interface is laid out the way you want, you can access any of the document’s components in your code, including views and data fields.

767

Chapter 54

Figure 54-5

Adding Code to InfoPath Forms

Adding code to respond to your InfoPath forms is convoluted because you hook the event handlers in via the InfoPath designer, and the events for different components are in a variety of locations in the application.

To help you find the different events you can use in your project code, the following discussion walks through the location of each type of event and describes each event’s purpose.

Form-Related Events

Form-related events are based on the whole document and are accessed through the Tools Programming submenu in InfoPath 2003 (see Figure 54-6).

768

InfoPath 2003 Toolkit

Figure 54-6

The four events listed here are associated with the document directly, and selecting any of them will switch to Visual Studio 2005 and generate a stub event handler. For example, the following code is generated when you choose the On Load Event option:

<InfoPathEventHandler(EventType:=InfoPathEventType.OnLoad)> _ Public Sub OnLoad(ByVal e As DocReturnEvent)

‘ Write your code here.

End Sub

This routine shows how the event handlers are hooked in Visual Basic code; an attribute of InfoPathEventHandler is prefixed to the subroutine definition, with the EventType value specifying which event should be connected to the managed code subroutine. Each of the four events has a particular argument object associated with it, as shown in the following table:

769

Chapter 54

You can also add code to control how the data associated with an InfoPath form is submitted. By default, submitting of forms is disabled, so you first need to enable it using the Tools Submitting Forms menu command in the InfoPath designer, which will display the Submitting Forms dialog (shown in Figure 54-7).

Figure 54-7

770

InfoPath 2003 Toolkit

To bind the Submit Request event to a managed code event handler, first select the “Enable Submit commands and buttons” radio button and then change the Submit To drop-down list to “Custom submit using form code.” Normally, like all the other events discussed here, this would generate a JavaScript routine to handle the event, but with the Toolkit it switches to Visual Studio 2005 and creates the event handler there, instead using the language you’ve chosen.

If you uncheck the Edit Form Code option, the event handler is added to your FormCode.vb file in the project, but the InfoPath designer remains active. As the generated code in the following listing illustrates, the OnSubmitRequest event is associated with submitting a form and contains a DocReturnEvent argument (the same object type used in the OnLoad event):

<InfoPathEventHandler(EventType:=InfoPathEventType.OnSubmitRequest)> _ Public Sub OnSubmitRequest(ByVal e As DocReturnEvent)

‘If the submit operation is successful, set

‘e.ReturnStatus = true

‘Write your code here.

End Sub

When you handle the OnSubmitRequest event, saving the data contained in the InfoPath form is left up to your code. However, because the InfoPath designer can display messages indicating whether the submission was successful or not (accessed through the Submit Options button shown in Figure 54-7), you should set the ReturnStatus property appropriately.

Rather than submit the form, what happens if the user edits and then saves the form? The answer is that there is yet another form-wide event called OnSaveRequest that you can intercept, and then perform your own functionality (including rejecting their changes).

To generate the event handler for this event, open the Form Options dialog and switch to the Open and Save tab (shown in Figure 54-8). Check the Save Using Custom Code option to generate the event handler routine and click the Edit button alongside it to switch to the Visual Studio IDE and locate the routine in the FormCode.vb module.

The automatically generated code for the OnSaveRequest event appears similar to the following listing:

<InfoPathEventHandler(EventType:=InfoPathEventType.OnSaveRequest)> _ Public Sub OnSaveRequest(ByVal e As SaveEvent)

‘Write the code to be run before saving here.

e.IsCancelled = e.PerformSaveOperation

‘Write the code to be run after saving here.

e.ReturnStatus = true End Sub

The SaveEvent argument contains a number of useful properties when saving the form. Because intercepting the event means that InfoPath won’t perform its own default Save (or Save As) functionality, you need to set the ReturnStatus property to indicate whether your own save process worked. If you do not set this property to True, InfoPath displays an error message to the end user indicating that the save was unsuccessful.

771

Chapter 54

Figure 54-8

The IsSaveAs flag indicates whether the user chose Save or Save As. The flag is set to True if the function is Save As, allowing you to perform different functionality, including showing a dialog box to specify the new document name. The IsCancelled flag is used to indicate whether the save function was cancelled by the user, so you should set this to True if they cancel the Save As functionality you implement.

The PerformSaveOperation method performs the intrinsic InfoPath save functionality based on whichever option (Save or Save As) is chosen by the user. As the generated code shows, this function returns a Boolean value indicating success or failure.

A few other form events are used when upgrading the InfoPath form layout from a previous version, and when data is imported or merged. These are not likely to be used often, but they can still be useful in certain situations.

To add a routine to handle the OnVersionUpgrade event, open the Advanced tab of the Form Options dialog in InfoPath and select Use Custom Event from the drop-down list labeled On Version Upgrade. You can switch to the generated event handler by subsequently clicking the Edit button.

If you need to intercept the OnAfterImport or OnMergeRequest events, you need to hook them up manually in the FormCode.vb module. The syntax for the OnAfterImport event handler routine (which will be fired when an import or merge action in InfoPath is successfully performed) is as follows:

772

InfoPath 2003 Toolkit

<InfoPathEventHandler(EventType:=InfoPathEventType.OnAfterImport)> _ Public Sub OnSubmitRequest(ByVal e As DocEvent)

‘ Write your code here.

End Sub

The OnMergeRequest is fired when a request is made to merge InfoPath forms and data. The syntax for a routine that handles this event appears like this:

<InfoPathEventHandler(EventType:=InfoPathEventType.OnMergeRequest)> _ Public Sub OnSubmitRequest(ByVal e As MergeEvent)

‘ Write your code here.

End Sub

You should set the ReturnStatus flag to True upon successful merging of the data.

Field Events

Fields such as textboxes, checkboxes, option buttons, and lists can fire three different events that you can intercept in your managed code project:

OnBeforeChange: This is fired when changes have been made to the underlying XmlDocument for an InfoPath form but before they’ve been accepted.

OnValidate: Raised after the changes have been accepted. However, the XmlDocument is in a read-only form and you normally only use this event to handle any errors that may have occurred when the data was changed

OnAfterChange: Raised last, this is used to change the data in the form in response to the underlying XmlDocument changes.

All three have their event handler routines generated in the same way. Select the field you need to handle and then select the Format fieldname Properties menu command. You can also use the keyboard shortcut Alt+Enter to display the Properties dialog, or right-click the field in question and select the Properties command from the context menu that is displayed.

On the Data tab, click the Data Validation button. The location of this button varies depending on which control type you’re editing but it will be present somewhere. When clicked, this button displays the Data Validation dialog (see Figure 54-9).

From the Events drop-down list in the Script section of the dialog window, you can choose from the three events. Select the event you need to handle and then click the Edit button to have Visual Studio generate the event handler routine (shown in the following listing) and switch to the IDE so you can add your own code:

<InfoPathEventHandler(MatchPath:=”/my:myFields/my:ReviewPeriodStart”, EventType:=InfoPathEventType.OnBeforeChange)> _

Public Sub ReviewPeriodStart_OnBeforeChange(ByVal e As DataDOMEvent)

‘Write your code here. Warning: ensure that the constraint you are enforcing is

‘compatible with the default value you set for this XML node.

End Sub

773

Chapter 54

Figure 54-9

The values found in the InfoPathEventHandler attribute prefixed to the subroutine definition are slightly different from the events you’ve looked at previously. In addition to the EventType, which is set to whichever event you chose in InfoPath, there is a MatchPath value that contains the unique XPath string to identify the field.

In the preceding sample routine, the MatchPath value tells Visual Studio to hook the routine to the OnBeforeChange event for the ReviewPeriodStart field in the myFields data collection. The corresponding field can be seen in Figure 54-10 in both the form’s user interface design and the Data Source pane on the right.

The Button Click Event

Buttons are a special case, having their own event. To generate a subroutine to handle the OnClick event of a button, bring up the Button Properties dialog (see Figure 54-11). This dialog is accessed by first selecting the Button and then choosing the Format Button Properties menu command or rightclicking the Button and selecting Button Properties from the context menu.

The ID field specifies the name of the button and can be changed to suit your own naming conventions. To create the event handler routine, click the Edit Form Code button. It will be automatically generated in the FormCode.vb file and you will be switched to the Visual Studio IDE, positioned in the routine and able to write your own program logic.

The event handler attributes are similar in structure to the field events just discussed. The following code shows a sample OnClick event handler for the button being edited in Figure 54-11:

<InfoPathEventHandler(MatchPath:=”SubmitReview”, EventType:=InfoPathEventType.OnClick)> _

Public Sub SubmitReview_OnClick(ByVal e As DocActionEvent)

‘ Write your code here.

End Sub

774

InfoPath 2003 Toolkit

Figure 54-10

Figure 54-11

775