Sunday, September 16, 2018

Configure your form template to detect the connection state of a form

Configure your form template to detect the connection state of a form

If you are designing a form template whose forms rely upon a network connection to process or return data, and you are familiar with writing script, you can write a script that detects the network connection state of forms based on your form template. You can use this script to have Microsoft Office InfoPath check if a new form is connected to a network and if the form can connect to an external data source before the form sends a query to the external data source. This article provides Microsoft JScript and Visual Basic Scripting Edition (VBScript) examples for determining if forms based on your form template are connected to the network and if those forms can connect to an external data source.

In this article

Overview

JScript example

VBScript example

Use the script example in a form template

Overview

To determine the network connection state of a form based on your form template, you can use the MachineOnlineState property of the Application object. Then you can use the IsDestinationReachable method of the same Application object to determine if the form can find the external data source. The MachineOnlineState property contains a value that represents the connection state of the form. This property can have the following values:

Value

Description

0

The computer is not connected to a network. The property can have this value if the computer is not connected to a network or if the network card in the computer is disabled.

1

The computer is connected to a network. If the computer is connected to a network using a network cable, this value indicates that the computer is on a network. If the computer has a working wireless network card, this value indicates that the wireless network card is working. However, the computer may not be connected to a wireless network.

2

The computer is connected to a network, but Windows Internet Explorer is configured to work offline. When Internet Explorer is configured to work offline, the data connection to a database or Web service may not work correctly.

After you have determined that the user's computer is connected to a network, you can use the IsDestinationReachable method to determine if the form can communicate with the external data source. This method takes the Uniform Resource Locator (URL) or Uniform Resource Name (URN) of the external data source as a parameter and returns one of the following Boolean values:

True    The form has found the external data source on the network.

False    The form cannot find the external data source. The external data source may be offline or may be on the network, but unavailable.

The script examples in this article only determine if the form is connected to the network. In this article, the script examples are used when the user first opens the form. However, you can also use this script whenever you want to check the network connection prior to performing an action. For example, you can use this script when a user clicks a particular button in the form to determine if there is a network connection to the external data source. Regardless of when you choose to use this script, you can also add script that performs an action, based on whether the form is connected to the network or not. For example, if the computer is offline or cannot connect to the external data source, you can have InfoPath display a warning message to the user that indicates that the external data source is not available. You can customize the warning message to tell users what to do if the external data source is unavailable. For example, you could tell them to try filling out the form later, or have the user contact their support service.

Top of Page

JScript example

var machineState = Application.MachineOnlineState;
var displayMessage = machineState;
switch(machineState)
{
case 0:
{
displayMessage = "The computer is not connected to a network.";
break;
}
case 1:
{
if (!Application.IsDestinationReachable("http://example"))
{
displayMessage = "The computer is connected to a network, "
+ "but the external data source is not "
+ "available. Contact the data source "
+ "administrator for more information.";
}
else
{
displayMessage = "The computer is connected to a network.";
}
break;
}
case 2:
{
displayMessage = "The computer is connected to a network, but "
+ "Internet Explorer is in offline mode. Some "
+ "data connections may not work until you "
+ "set Internet Explorer to online mode. To "
+ "switch to online mode, on the File menu in "
+ "Internet Explorer, click Work Offline.";
break;
}
default:
{
displayMessage = "An unknown error occurred: Error: "
+ machineState;
}
}
XDocument.UI.Alert(displayMessage);

Top of Page

VBScript example

Dim machineState, displayMessage, returnValue
machineState = Application.MachineOnlineState
displayMessage = machineState
returnValue = False
Select Case machineState
Case 0
displayMessage = "The computer is not connected to a network."
Case 1
returnValue = Application.IsDestinationReachable("http://example")
If returnValue = False Then
displayMessage = "The computer is connected to a network, but "
displayMessage = displayMessage + "the external data source is "
displayMessage = displayMessage + "not available. Contact the "
displayMessage = displayMessage + "data source administrator "
displayMessage = displayMessage + "for more information."
Else
displayMessage = "The computer is connected to a network."
End If
Case 2
displayMessage = "The computer is connected to a network, but "
displayMessage = displayMessage + "Internet Explorer is in "
displayMessage = displayMessage + "offline mode. Some data "
displayMessage = displayMessage + "connections may not work "
displayMessage = displayMessage + "until you set Internet "
displayMessage = displayMessage + "Explorer to online mode. "
displayMessage = displayMessage + "To switch to online mode, "
displayMessage = displayMessage + "on the File menu in "
displayMessage = displayMessage + "Internet Explorer, click "
displayMessage = displayMessage + "Work Offline."
Case Else
displayMessage = "An unknown error occurred: Error: "
displayMessage = displayMessage + machineState + "."
End Select
XDocument.UI.Alert(displayMessage)

Top of Page

Use the script example in a form template

If you would like to test a script example before using it in your form template, you can use the following procedure to create a blank form template, and then copy one of the script examples from this article to the OnLoad event. The script in the OnLoad event runs whenever a new form based on the form template is created. You can then preview your form template to test the script example with your computer connected to a network, disconnected from the network, or connected to the network but with Internet Explorer set to offline mode.

  1. Copy one of the script examples listed earlier in this topic, and then paste it into a text editor, such as Microsoft Notepad.

    Note: Copying the script example to a text editor before you add it to your form template prevents Hypertext Markup Language (HTML) formatting marks from appearing in the script.

  2. In InfoPath, on the File menu, click Design a Form Template.

  3. Under Design a new, in the Design a Form Template dialog box, click Form Template, click Blank, and then click OK.

  4. By default, new form templates are configured to use JScript as the scripting language. To use VBScript as your scripting language, change the scripting language of the form template.

    How?

    1. On the Tools menu, click Form Options.

    2. In the Category list, click Programming.

    3. In the Form template code language list under Programming language, click VBScript, and then click OK.

  5. On the Tools menu, point to Programming, and then click On Load Event. The Microsoft Script Editor starts with the cursor at the OnLoad event.

  6. In the OnLoad event in the Microsoft Script Editor, replace the // Write your code here (JScript) or ' Write your code here (VBScript) text with the script example that you copied to the text editor.

  7. Modify the script example to suit your environment. For example, you can modify the messages and change http://example to the URL or URN of your external data source.

  8. In the Microsoft Script Editor, on the File menu, click Save.

  9. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

Top of Page

No comments:

Post a Comment