Partager via

Using the Events Manager of the InfoPath Hosted Control

  • Article

The InfoPath hosted control gives developers of third party hosted applications the ability to respond to events in the form.  The InfoPath event manager provides this functionality.  Through the event manager a host application can respond to 5 form events, 3 xml events and 1 control event:

Form Events

Xml Events

Control Events

Saving eventContext Changed eventSign eventMerging eventView Switched event

Changing eventValidating eventChanged event

Clicking event

How can third party host applications use the event manager?

Step 1: Implement an InternalStartup method

First, add code to handle the InternalStartup event. InternalStartup method will execute when a form loads.

 public Form1()
{
            InitializeComponent();

            //sync to the startup event where you can register for individual events
            formControl1.InternalStartup += new Microsoft.Office.InfoPath.FormControl.EventHandler<EventArgs>(InternalStartup);
}

Next, implement your InternalStartup method. The function signature should look similar to:

 void formControl1_InternalStartup(object sender, EventArgs e)

 

Step 2: Register to receive events

In your InternalStartup method add code to register for events. For form events this code looks like this.

 void InternalStartup(object sender, EventArgs e)
{           
       ((FormControl)sender).EventManager.FormEvents.ViewSwitched += new ViewSwitchedEventHandler(OnSwitchView);
       ((FormControl)sender).EventManager.FormEvents.Submit       += new SubmitEventHandler(OnSubmit);
       ((FormControl)sender).EventManager.FormEvents.Sign         += new SignEventHandler(OnSign);
       ((FormControl)sender).EventManager.FormEvents.Save         += new SaveEventHandler(OnSave);
       ((FormControl)sender).EventManager.FormEvents.Merge        += new MergeEventHandler(OnMerge);
 }

For xml events you must provide the XPath of the node whose events you wish to respond to. Below is a sample of how to register to receive xml events.

 

 void InternalStartup(object sender, EventArgs e)
{
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Changed    += new XmlChangedEventHandler(FieldChanged);
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Changing   += new XmlChangingEventHandler(FieldChanging);
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Validating += new XmlValidatingEventHandler(FieldValidating);
}

To receive the click event for a button you must specify the control id of the button. Below is a sample of how to register to receive control events.

 void InternalStartup(object sender, EventArgs e)
{
      ((ButtonEvent)((FormControl)sender).EventManager.ControlEvents["CTRL2_5"]).Clicked += new ClickedEventHandler(ButtonClicked);
}

 

Step 3: Implement methods to handle each event registered

The final step is to implement handlers for the events you have registered for.
The handlers for the events have the following method signatures.

Form Events

 public delegate void ViewSwitchedEventHandler(object sender, Microsoft.Office.InfoPath.ViewSwitchedEventArgs e)
public delegate void SubmitEventHandler(object sender, Microsoft.Office.InfoPath.SubmitEventArgs e)
public delegate void SignEventHandler(object sender, Microsoft.Office.InfoPath.SignEventArgs e)
public delegate void SaveEventHandler(object sender, Microsoft.Office.InfoPath.SaveEventArgs e)
public delegate void MergeEventHandler(object sender, Microsoft.Office.InfoPath.MergeEventArgs e)

Xml Events

 public delegate void XmlChangedEventHandler(object sender, Microsoft.Office.InfoPath.XmlEventArgs e)
public delegate void XmlChangingEventHandler(object sender, Microsoft.Office.InfoPath.XmlChangingEventArgs e)
public delegate void XmlValidatingEventHandler(object sender, Microsoft.Office.InfoPath.XmlValidatingEventArgs e)

Control Events

 public delegate void ClickedEventHandler(object sender, Microsoft.Office.InfoPath.ClickedEventArgs e)

Example: changed event, view switched event, button clicked event.

 void FieldChanged(object sender, XmlEventArgs e) {}
void OnSwitchView(object sender, ViewSwitchedEventArgs e) {}
void button1_Click(object sender, EventArgs e) {}

 

Things to know about handling events

  1. Events are handled first by the form’s business logic, then by others who register to handle events. Since events are handled asynchronously it is possible that the code in the business logic may cancel the event, and deny the host the opportunity to handle the event.
  2. In order to handle the submit, save and merging events, the designer of the form template must specify that the event is to be handled through the use of code. Without enabling this in the form template the event will not be handled in code.
  3. Buttons must specify that clicks be handled through code or the event will not be handled through code.
  4. The sign event will only take place when the form is fully trusted.
  5. The Loading and VersionUpgrade events are not available from third party hosted applications as these events occur before the form is loaded in the hosted application.

DeVere Dyett
Software Design Engineer in Test

Comments

  • Anonymous
    February 07, 2007
    The InfoPath hosted control gives developers of third party hosted applications the ability to respond...

  • Anonymous
    March 10, 2007
    The InfoPath hosted control gives developers of third party hosted applications the ability to respond

  • Anonymous
    August 22, 2007
    Form Loading event: Can we change the manifest in this event? I would like to hide several views and change the default view when certain conditions exist.

  • Anonymous
    September 01, 2007
    The InfoPath hosted control gives developers of third party hosted applications the ability to respond

  • Anonymous
    October 10, 2007
    TheInfoPathhostedcontrolgivesdevelopersofthirdpartyhostedapplicationstheabilitytorespo...

  • Anonymous
    January 14, 2010
    Concerning Internal Startup, I have non web-based InfoPath Project with Managed Code that contains a Change Event Handler for a date field within a Section.  The event handler is used to build rows and set dates and other default values in a repeating table.  After the user has finalized the form it is sent to their supervisor who digitally signs the form which locks all the fields within the section to include the field tied to the Change Event Handler.  In addition, within event handler's managed code, logic is in place within the Change Event to only allow users to change fields within the repeating table for conditions that only exist prior to the digital signature.  After the supervisor signs the form, an HR representative is responsible for reviewing what has been entered by the user and signed off by the supervisor.  Unfortunately, InfoPath will not let them open the form and returns an error stating "There was an error in Custom Validation Code", specifically "This value has been digitally signed and cannot be changed".  This error as it turns out is referring to the Change Event Handler field because the event handler is bound during Internal Startup.  My question is this, how can I bind my Change Event Handler while not having InternalStartup load it every time the form is opened?