1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<html dir="ltr"><head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<META HTTP-EQUIV="assetid" CONTENT="HV06246519"><META NAME="lcid" CONTENT="1033"><title>Script-based validation in the Data Validation developer sample form</title><link rel="stylesheet" type="text/css" href="office10.css"><script type="text/javascript" language="Javascript" src="ExpCollapse.js"></script><script type="text/javascript" language="JavaScript" src="inline.js"></script></head><body><p id="ExpandAllLine" class="ExpFav"><a href="#" onclick="ExpandAll()" onkeypress="ExpandAll()" class="DropDown"><img id="picHeader" border="0" src="expandtri.gif" alt="Show All"><span id="ExpandAll">Show All</span></a></p><h1>Script-based validation in the Data Validation developer sample form</h1><div class="ofvbanav"><span class="ofvbanavreuse" id="seealso" onclick="toggleList()" onkeypress="toggleList()"></span><span class="ofvbanavreuse" id="specifics" onclick="toggleList()" onkeypress="toggleList()"></span></div><p>Script-based validation is specified in the business logic script
file associated with a Microsoft Office InfoPath 2003 form, and it provides more
flexibility than custom validation or schema-based validation. Using
script-based validation, you can specify when a field should be validated (for
example, when the user first types data into a field, after the user leaves a
field, or after data is validated by the schema). You can also write script
that runs when a form is opened or when the user switches views. The script you
write can perform a variety of functions, including comparing fields,
calculating values, showing error messages, updating values, and revising other
fields.</p><p><b>Note</b> InfoPath supports writing script in Microsoft
<a href="#" class="glossary" onclick="AppendPopup(this,'ofVBScript')" onkeypress="AppendPopup(this,'ofVBScript')">VBScript</a> and Microsoft
<a href="#" class="glossary" onclick="AppendPopup(this,'ofjscript')" onkeypress="AppendPopup(this,'ofjscript')">JScript</a>. However, you cannot mix the
scripting languages used within a single form. </p><p>To
create script-based data validation, you use InfoPath
<a href="#" class="glossary" onclick="AppendPopup(this,'xddesignmode')" onkeypress="AppendPopup(this,'xddesignmode')"> design mode</a> to
create an <a href="#" class="glossary" onclick="AppendPopup(this,'xdeventhandler')" onkeypress="AppendPopup(this,'xdeventhandler')">event handler</a> (also called an event function), and then you
write scripting code for the event handler using the <a href="#" class="glossary" onclick="AppendPopup(this,'xdmicrosoftscripteditormse')" onkeypress="AppendPopup(this,'xdmicrosoftscripteditormse')">Microsoft Script Editor
(MSE)</a>. For each event handler that you create, InfoPath places
an entry in the <a href="#" class="glossary" onclick="AppendPopup(this,'xdformdefinitionfilexsf')" onkeypress="AppendPopup(this,'xdformdefinitionfilexsf')">form definition
(.xsf) file</a>
that
contains
the name of the event handler and the XML <a href="#" class="glossary" onclick="AppendPopup(this,'ofdocumentobjectmodeldom')" onkeypress="AppendPopup(this,'ofdocumentobjectmodeldom')">Document Object Model (DOM)</a> node that the event handler is
associated with.</p><p>Because the event handler is referenced in the .xsf
file, you cannot create a new event handler entirely
from within MSE<nbsp />— you must initially create the event handler in InfoPath
design mode. Since InfoPath is used to create the declaration of the event
handler, you cannot modify the event handler name or its arguments once it
has been created. </p><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Event handlers in the form definition
file</a></p><div id="ExpCol" class="collapsed" border="0">
<p>In the Data Validation developer sample form, InfoPath
created a <b class="bterm"><a href="xsfelmdomEventHandler.htm" id="HV01021469" lcid=" ">domEventHandler</a></b> element within the
<b class="bterm"><a href="xsfelmdomEventHandlers.htm" id="HV01021470" lcid=" ">domEventHandlers</a></b> section of the .xsf file for each event
handler. The following is an example of the event handlers created in the
.xsf file of the Data Validation developer sample form: </p>
<pre><code><xsf:domEventHandlers>
<xsf:domEventHandler handlerObject="msoxd__itemB_quantityListB"
match="/sampleData/listB/itemB/quantityListB">
</xsf:domEventHandler>
<xsf:domEventHandler handlerObject="msoxd__shippingDates"
match="/sampleData/shippingDates">
</xsf:domEventHandler>
<xsf:domEventHandler handlerObject="msoxd__total"
match="/sampleData/listB/total">
</xsf:domEventHandler>
<xsf:domEventHandler handlerObject="msoxd__creditLimit"
match="/sampleData/creditCardInfo/creditLimit">
</xsf:domEventHandler>
<xsf:domEventHandler handlerObject="msoxd__creditCardInfo"
match="/sampleData/creditCardInfo">
</xsf:domEventHandler>
</xsf:domEventHandlers>
</code></pre>
<p>As shown in this example, for every event handler created in
InfoPath design mode, a <b class="bterm">domEventHandler</b> element was created
in the .xsf file; each of these elements contains a
<b class="bterm"><a href="xsfatrhandlerObject.htm" id="HV01021551" lcid=" ">handlerObject</a></b> attribute that
specifies the name of the event handler and a <b class="bterm"><a href="xsfatrmatch_2.htm" id="HV01021564" lcid=" ">match</a></b> attribute that
specifies the XML DOM node that the event handler is associated with.</p>
<div class="ind"><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Viewing event handlers in the form
definition file</a></p><div id="ExpCol" class="collapsed" border="0">
<p>To view the event handlers that were used to implement the
script-based validation constraints in the Data Validation developer sample
form, do the following:</p>
<ol>
<li>Open the Data Validation developer sample form in design
mode.</li>
<li>If you do not see the <b class="bterm">Data Source</b> task pane,
click <b class="bterm">Data Source</b> on the <b class="bterm">View</b> menu.</li>
<li>In
the
<b class="ui">Data Source</b> task pane, right-click
the field whose validation you want to view or modify, and then click the
<b class="ui">Properties</b> menu item to open the
<b class="bterm">Field or Group Properties</b> dialog box.</li>
<li>Click the <b class="bterm">Validation and Script</b> tab.</li>
<li>In the <b class="bterm">Events</b> box, select the event that you
wish to edit, and then click <b class="bterm">Edit</b> to open MSE. The script code
for the selected event appears in the code editor window.</li>
</ol>
<p><b>Note</b> While it is necessary to create event handlers in design mode
using these steps, once you have created an event handler, you can open MSE
from InfoPath by clicking the
<b class="ui">Tools</b> menu, pointing to
<b class="ui">Script</b>, and clicking
<b class="ui">Microsoft Script Editor</b>, or
by pressing ALT+SHIFT+F11.</p></div></div></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Script-based event handlers and functions</a></p><div id="ExpCol" class="collapsed" border="0">
<p>In the Data Validation developer sample form, a number of
event handlers and functions are used for script-based validation. The following table lists each
of these event handlers and functions and describes how they are used.</p><table>
<tr><th>Function</th><th>Description</th>
</tr>
<tr><td><code>msoxd__shippingDates::OnBeforeChange</code></td><td>An event handler that is used to validate shipping dates. It
returns a True or False value depending on
whether the dates are valid according to business rules, and it sets the
<b class="bterm"><a href="xdproReturnMessage.htm" id="HV01021325" lcid=" ">ReturnMessage</a></b>
and <b class="bterm"><a href="xdproReturnStatus_1.htm" id="HV01021327" lcid=" ">ReturnStatus</a></b>
properties of the
<b class="bterm"><a href="xdobjDataDOMEvent.htm" id="HV01021239" lcid=" ">DataDOMEvent</a></b> object to return an error message to the user.</td>
</tr>
<tr><td><code>msoxd__itemB_quantityListB::OnValidate</code></td><td>An event handler that is used to validate the quantity values
within each block. It uses the <b class="bterm"><a href="xdmthReportError.htm" id="HV01021405" lcid=" ">ReportError</a></b> method of the
<b class="bterm">DataDOMEvent</b> object to return an error message to the user.</td>
</tr>
<tr><td><code>msoxd__itemB_quantityListB::OnAfterChange</code></td><td>An event handler that is used to update the
Total field based on the number of block quantities entered.
This event occurs after the data has been validated in the
<b class="bterm"><a href="xdevtOnValidate.htm" id="HV01021372" lcid=" ">OnValidate</a></b> event. It calls the general-purpose
GetTotal function to do the calculations.</td>
</tr>
<tr><td><code>msoxd__total::OnValidate</code></td><td>An event handler that is used to validate the value in the
Total field. It uses the <b class="bterm">ReportError</b> method of
the <b class="bterm">DataDOMEvent</b> object to return an error message to the user.</td>
</tr>
<tr><td><code>msoxd__creditCardInfo::OnValidate</code></td><td>An event handler that is used to validate the credit card
limits for each credit card type. It calls the ValidateCreditInformation general-purpose function to perform the validation.</td>
</tr>
<tr><td><code>msoxd__creditLimit::OnBeforeChange</code></td><td>An event handler that is used to validate the credit card limit value. It uses the <b class="bterm">ReturnMessage</b> and <b class="bterm">ReturnStatus</b> properties of the <b class="bterm">DataDOMEvent</b> object to return an error message to the user.</td></tr><tr><td><code>ValidateCreditInformation</code></td><td>A general-purpose function that is used to validate the credit card
limits for each credit card type. It uses the <b class="bterm">ReportError</b> method
of the <b class="bterm">DataDOMEvent</b> object to return an error message to the user.</td></tr><tr><td><code>GetTotal</code></td><td>A general-purpose function that is used to add all of the
quantity values. It returns the total value of all the quantities.</td>
</tr><tr><td><code>BtnSubmitShipDates::OnClick</code></td><td>An event handler that is used to simulate the connection to a back-end application
that validates the order and shipping dates entered in the form. It uses the <b class="bterm"><a href="xdmthAlert.htm" id="HV01021376" lcid=" ">Alert</a></b> method of the <b class="bterm"><a href="xdobjUI.htm" id="HV01021247" lcid=" ">UI</a></b> object to provide information to the user.</td></tr>
</table></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Using the DataDOMEvent object</a></p><div id="ExpCol" class="collapsed" border="0">In the Data
Validation developer sample form, the <b class="bterm"><a href="xdobjDataDOMEvent.htm" id="HV01021239" lcid=" ">DataDOMEvent</a></b> object is used in
the
<code>msoxd__itemB_quantityListB::OnValidate</code> event handler to validate the number of blocks entered in the
<b class="bterm">Quantity</b> field. It returns an error message to the
user if the data does not meet the specified criteria, which in this case is a
numerical value that is greater than 50 or less than 0.
<p>The <b class="bterm"><a href="xdproSite.htm" id="HV01021332" lcid=" ">Site</a></b> property
of the <b class="bterm">DataDOMEvent</b> object is used to return a pointer to the XML DOM
node for the <b class="bterm">Quantity</b> field, and the
<b class="bterm">nodeTypeValue</b> property of
the XML DOM is used to access the value of the field. If the value of the
field does not match the data validation criteria, then the
<b class="bterm"><a href="xdmthReportError.htm" id="HV01021405" lcid=" ">ReportError</a></b> method of the <b class="bterm">DataDOMEvent</b> object is used to
return an error message to the user. The following is the JScript code used to
implement the
<code>msoxd__itemB_quantityListB::OnValidate</code> event handler:</p>
<pre><code>function msoxd__itemB_quantityListB::OnValidate(eventObj)
{
if (parseInt(eventObj.Site.nodeTypedValue, 10) > 50)
eventObj.ReportError(eventObj.Site, "Invalid quantity. The total number
of each type of block cannot exceed 50.", false);
if (parseInt(eventObj.Site.nodeTypedValue, 10) < 0)
eventObj.ReportError(eventObj.Site, "Invalid quantity. The total number
of each type of block cannot be less than 0.", false);
}</code></pre>
<p>As shown in this example, multiple data validation constraints
can be checked against a single field, and you can create a custom error
message for as many validation constraints as needed. </p></div><script type="text/javascript" language="JScript" src="ofvbanl.js"></script><span id="ofVBAISpan" class="ofvbaispan"><iframe id="ofVBAIFrame" frameborder="0" marginheight="0" marginwidth="4" scrolling="auto" width="100%" src="../links/inconScriptValInDVForm_l.htm"></iframe></span><center><a href="XMLSchemaCopyright_HV01147162.htm">©2003-2004 Microsoft Corporation. All rights reserved.</a>
Permission to copy, display and distribute this document is available at: <a
href="http://r.office.microsoft.com/r/rlidAWSContentRedir?AssetID=XT010988631033&CTT=11&Origin=HV011232471033"
target="_new">http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp</a></center></body></html>
|
