You may encounter unwanted validation or required error dialogs when designing an XPage with events and partial updates.
If the Events view just contains an Open Page action, you can avoid all validation by using a simple link instead of the action.
If you do need the Events view, there is an option to disable validation just for this event. When validation is disabled,
the values submitted from the page are not saved to the document, and if you need to access them during the partial update
then you must use some special API methods that are only needed for this kind of event.

Suppose you have some fields in an XPage which have associated validation; values are required or must be in a certain range.
As expected, when you click a Save button, it will check that the required fields are present and display errors if they are not present.
However, if you click any other link or button on the page, it will also display those errors, which may not be the desired behavior.

To avoid validation, either:

• Use links that do not submit the page
• Or disable validation for the event in the Events tab.

You should not change the "Client Validation" setting to "Off", as the server-side validation will still occur (see Scenario D below).

Article structure:

• Using a link with a value instead of the Events view
• Disable data validation in the Events view
• Accessing submitted values when validation is disabled
• Details of the behavior when validation is disabled
  • How "No Data Validation" works in the JSF Lifecycle
  • The input immediate property
• Example scenarios for "No Data Validation"
  • Scenario A, Cancel button or open page without saving
  • Scenario B, Check Box that causes different page content to appear by Partial Update
  • Scenario C, Partial Update when Combo Box onchange occurs
  • Scenario D, Client Validation is Off or disableClientSideValidation but the action does not occur

Using a link value instead of the Events view.
If the only action associated with a link is an Open Page Action, then you can remove the action and configure the link to navigate directly to the XPage.
That will avoid the data validation, and will give performance improvements,
because it prevents submitting the contents of the page to the server and the processing of the current page before the action moves to the next page.

Choose the XPage to open on the right of the main panel of the Link Properties.
If you would like some further information to be available in the navigated page, you can use the parameters option in the All Properties tab.

Those parameters are available in the opened page by referencing "param.action" or "param.documentId" etc.
Also, the data sources in the opened XPage will use values passed in as request parameters,
for example, the Domino Document data source will use request parameters named "action", "documentId" or "parentId".


Disable data validation in the Events view

There is an option in the Events tab which will prevent data validation and updating during that submission. It is often used with Cancel buttons.
You should not attempt to save the document when that option is enabled, as the submitted values are not updated into the document.
If you need to access submitted values during the server action, or when the page is redisplaying (as in a partial update),
then the code is more complicated - attempting to reference the field in the document will not work,
as the values are not saved from the control to the data binding.

The option to disable validation is named "Do not validate or update data" since release 8.5.1.
It was renamed; in 8.5 the option was known as "No data validation".
In the Source tab of the XPage, the option is the "immediate" property on the xp:eventHandler tag.

In Domino Designer 8.5.1, choose "Do not validate or update data"

In Domino Designer 8.5, choose the "No Data Validation" option.


That option is sufficient if you are creating a cancel link, or doing a Partial Update of an area that does not depend on other values in the page.
To access values from the submitted page is more complicated.


Accessing submitted values when validation is disabled

The Domino APIs for accessing current field values will not work during a submission when validation is disabled.
The code to access a field value is like so:


You may need to use that code in the Events tab, or in "compute value" scripts within the Partial Update area.
When using "getSubmittedValue", the result will be a String; if the field is a Date or Number
you may need to convert from String to that type - see the section on "The input immediate property".
For more details and an example, see Scenario C below.


Details of the behavior when validation is disabled

There are many side effects of the JSF "immediate" property, other than preventing the error dialogs.

• Values in the submitted html page are not saved to the document. That is, dominoDocument1.firstName will not contain the updated value.
• Values in the submitted html page are not saved to the control value. That is, getComponent('inputText1').getValue() will not contain the updated value.
• Values in the submitted html page are saved to the control "submittedValue" field. That is, getComponent('inputText1').getSubmittedValue() will contain the updated value.
• You should not put Save actions in "No data validation" events.
• If you put a Save action in a "No data validation" event, then the document will be saved with the old values, without performing validation, and without the updated values that were present in the browser.
• Required fields may be missing.
• Values that were entered in the browser will not be present in the document, so fields may appear blank even though the user typed in a value.
• The fields are not necessarily blank, just unchanged by the current submission. So if you are editing an existing document, the values that were already present in the fields will remain. Also, if you have done a previous submit (not necessarily save) of the current new document, where validation was not disabled during that submit, then values that were entered during that submit will be present.
• Validation does not occur. The dialog in the browser is known as client validation. That does not occur. There is also server validation, used with Display Error(s) controls, where the error appears in the returned HTML page. Server validation does not occur either.

The next section explains why the side-effects occur. If you don't care, you can skip down to the example scenarios below.

How "No data validation" works in the JSF Lifecycle
The explanation for all of this requires an understanding of the JSF(Java Server Faces) lifecycle.
When the user submits a page to the server, the submission is processed in different phases, where in each phase it goes through all the controls and processes them.
When you submit a page, on the server it first restores the server-side control tree (Restore View phase), then it goes through all controls and copies the values from the browser form into each control's "submittedValue" field (Apply Request Values phase). Then it validates each control in the Process Validations phase, adding an error message to a list if not valid. Also if the field is configured as a non-string type, like Date, it'll convert it to a Date object, adding an error message to the list if there's a conversion problem. If the control is valid and converts OK, then the conversion will delete the value from the "submittedValue" field, and put the converted value into the control's "localValue". Then the Update Model Values phase will save the converted value into the underlying document field and remove the control's "localValue". Next the Invoke Application phase will process any actions associated with the event that submitted the page. Finally, if the action did not move to a different page, then the control tree is output as a HTML page that's returned to the browser (Render Response phase).
There are other explanations and diagrams of the JSF lifecycle on the web if you want to look into it more, e.g. an article on the JSF lifecycle.

The "No data validation" option means that the lifecycle skips the Process Validations phase and the Update Model Values phase. The side-effects listed are because it will not validate the controls nor copy the value into the document.
Also note, the "submittedValue" fields are only available in the Invoke Application phase during in a "No data validation" event, so any visibility or formula item computation will usually need to check both the "submittedValue" and also the getValue() for the control, so the computation will work in both a "No data validation" page display and a normal page display.

[There's also an oddity for any advanced users who write code against the JSF APIs. During "No data validation" events the Apply Request Values and Invoke Application processing both occur in the "Apply Request Values" phase. It doesn't make much difference normally, unless you're configuring listeners to the JSF lifecycle, or debugging a new data-bound Java control.]

The input immediate property
It is possible to configure individual controls to do validation during a "No data validation" event. That feature is not used often. The control value is not saved to the document.
There is an "immediate" property available on every input control, e.g. the Edit Box. That property is known as the input immediate property.
The "No data validation" property is known as the command immediate property (the Event Handler is a command control).
They do 2 different things. The command immediate property behaves as outlined above.
When input immediate is set to true, it will not make much difference during a normal page submit (without the "No data validation" check box).
During a "No data validation" submit, an Edit Box with input immediate true will perform server data validation of the edit box.
Then, if the value is valid [getComponent('inputText1').isValid()], the input control "localValue" will contain the updated value [getComponent('inputText1').getValue() will have changed].
The value in the input immediate edit box is not saved to the document. That is, dominoDocument1.firstName will not contain the updated value.
So the input immediate property does not allow the value to be saved, just validated.
In this case, the "Process Validations" phase does not occur exactly as above. It gets as far as putting the converted value into the control's "localValue", but does not copy the value into the underlying document. While the control's "localValue" is set, the behavior of the "getValue()" method changes. It returns the "localValue" instead of retrieving the value from the underlying document. Using the input immediate property during a command immediate event is the only case where getValue() and dominoDocument1.firstName do not return the same result.


Example scenarios for "No data validation"

Scenario A is just a Cancel button. Scenario C is the most interesting option, where you are doing a partial update when a control value changes and you use the value of that control to determine what is shown after the update. Scenario B is a simplified version of Scenario C, when you don't need to access the control value during the update. Scenario D is a common mistake where you disable client validation and it seems that the events stop working.


Scenario A Cancel button or open page without saving.
As mentioned above, you may be attempting to create a Cancel button or link for when you do not wish to save your changes,
but it doesn't work because you keep seeing error dialogs in the browser.
For this you can just use the "No data validation" check box without any additional coding.
If you want to use a control value during this event, then you'll need the extra coding outlined in Scenario D.

To run this example, first create an XPage named "page2" which you will navigate to.
Then create a new XPage, switch to the Source tab of the editor, and paste in this contents.

Source for example A


The first button, with label "Cancel", was created by changing the Button type from "Button" to "Cancel".
That action causes the "No data validation" check box to be checked in the Events panel.
When you leave the edit box blank and click the Submit button, a dialog appears indicating that the value is required.
When you click the Cancel button, the dialog does not appear, and the browser navigates to page2.

Since the Link label does not say Cancel, the link was created with a Confirm Action,
so the user knows that when they click the link, their changes to the document will be discarded.
If the confirm dialog is not always needed, put the Confirm Action in a conditional Action Group.
When you click on the Link, a dialog appears to confirm that you want to navigate,
and when you click OK, it navigates to the other page.
The required dialog does not appear because the link "No data validation" check box was checked.



Scenario B Check Box that causes different page content to appear by Partial Update
You may have a link where the event action does not use the document data,
but the action can cause the page to appear differently, e.g. by changing a variable controlling visibility.
Again in this case you can just use the "No data validation" check box without any additional coding.
The submitted information about which event occurred is passed to the server,
and the action response is executed. In this case, where you are not using data from the browser page,
the only effect of the "No data validation" option is to ensure that the browser Required dialog does not appear.

This is less complicated than when the control is bound to document data [see Scenario C below]

For example, Create a new XPage, in the Source tab paste the source below, and Preview the XPage.
If you click the submit button, an error dialog appears with the text "Field is required".
If you click on the link, the error dialog does not appear, and the submit is allowed,
because in the link Events view, the check box "No data validation" is checked.
The Partial Update area then refreshes, and the blue div is shown or hidden.

Source for example B




Scenario C Partial Update when Combo Box onchange occurs
In this case you have a combo box where the option chosen determines what other values are displayed in the page.
You would use the "No data validation" check box for the "onchange" event, so that the page can update
and display the other values even when required fields are not present.
However the "No data validation" option means you will have to change the code referring to the value in the check box.
Even though the combo box is bound to a document field, you cannot refer to the value of the field in the document
when deciding what other values to show. Instead when "No data validation" is checked,
you must instead get the value using "getSubmittedValue()" on the control.

Try out this example. Create a new XPage and paste in the source below. Preview.
If you click the submit button, an error dialog appears with the text "Field is required".
If you choose an option in the first combo box, the error dialog does not occur, and the submit is allowed
because in the onchange Event for that combo box, "No data validation" is checked.
The second combo box then refreshes with different contents, depending on the selection in the first combo box.
The value selected in the first combo box during a "No data validation" event,
is only available by calling getComponent('comboBox1').getSubmittedValue()
The value from the browser is not saved to the underlying document.

Source for example C


The important thing to note here is that you cannot write normal domino code
where you just refer to the value of a field to get the combo box value.
Instead you usually need a snippet of code, like this in the example:

You should get the submittedValue from the combo box instead of getting the field from the document,
because the value is not copied into the document. You should also allow for when the submittedValue is null,
because in a non-"No data validation" page display, either the submittedValue is cleared when it is saved to the document,
or this is the first time displaying so nothing has been submitted.

This scenario also has a complication caused by the issue PHAN7PRL37,
where you get an error complaining that the combo box value is required, even though the required check box is not checked.
The error appears in a Display Errors control on the page, not in a browser pop-up dialog.
That issue occurs for any control that has a "Values" tab in the Properties view of Domino Designer, not just combo boxes.
The problem is that those controls have a hard requirement that the control value must be an item listed in the Values tab,
so when nothing is selected in the combo box, you get an error message.
The work-around is to add an item for the empty string "". The Values tab doesn't allow the empty string as a value,
so type a space into the Values tab and then switch to the Source tab and change itemLabel=" " to itemLabel="".
The example uses that work-around.


Scenario D Client Validation is Off or disableClientSideValidation but the action does not occur
This issue occurs through a misunderstanding of Client Validation.
If a person developing an XPage isn't aware of the "No data validation" option,
but they see error dialogs when attempting Partial Update, they may attempt to prevent those
dialogs by disabling Client validation in the browser.
That does not fix the issue, because all Client Validation is matched by corresponding
Server validation, which prevents the action configured in the Events view.
If you disable Client validation, then you should add a "Display Errors" control to every XPage.
The control displays the server validation error messages.
If that control is not present, then the server validation message is not visible,
and it seems strange because page appears to refresh without any server action occurring.
The solution for this to re-enable Client Validation, as it is not necessary to disable it,
then in the Events view for the action, check the "No data validation" check box.
Also, read the section above outlining the side-effects for that option.Validation does not occur. The dialog in the browser is known as client validation. That does not occur. There is also server validation, used with Display Error(s) controls, where the error appears in the returned HTML page. Server validation does not occur either.The next section explains why the side-effects occur. If you don't care, you can skip down to the example scenarios below.

How "No data validation" works in the JSF Lifecycle
The explanation for all of this requires an understanding of the JSF(Java Server Faces) lifecycle.
When the user submits a page to the server, the submission is processed in different phases, where in each phase it goes through all the controls and processes them.
When you submit a page, on the server it first restores the server-side control tree (Restore View phase), then it goes through all controls and copies the values from the browser form into each control's "submittedValue" field (Apply Request Values phase). Then it validates each control in the Process Validations phase, adding an error message to a list if not valid. Also if the field is configured as a non-string type, like Date, it'll convert it to a Date object, adding an error message to the list if there's a conversion problem. If the control is valid and converts OK, then the conversion will delete the value from the "submittedValue" field, and put the converted value into the control's "localValue". Then the Update Model Values phase will save the converted value into the underlying document field and remove the control's "localValue". Next the Invoke Application phase will process any actions associated with the event that submitted the page. Finally, if the action did not move to a different page, then the control tree is output as a HTML page that's returned to the browser (Render Response phase).
There are other explanations and diagrams of the JSF lifecycle on the web if you want to look into it more, e.g. an article on the JSF lifecycle.

The "No data validation" option means that the lifecycle skips the Process Validations phase and the Update Model Values phase. The side-effects listed are because it will not validate the controls nor copy the value into the document.
Also note, the "submittedValue" fields are only available in the Invoke Application phase during in a "No data validation" event, so any visibility or formula item computation will usually need to check both the "submittedValue" and also the getValue() for the control, so the computation will work in both a "No data validation" page display and a normal page display.

[There's also an oddity for any advanced users who write code against the JSF APIs. During "No data validation" events the Apply Request Values and Invoke Application processing both occur in the "Apply Request Values" phase. It doesn't make much difference normally, unless you're configuring listeners to the JSF lifecycle, or debugging a new data-bound Java control.]

The input immediate property
It is possible to configure individual controls to do validation during a "No data validation" event. That feature is not used often. The control value is not saved to the document.There is an "immediate" property available on every input control, e.g. the Edit Box. That property is known as the input immediate property.
The "No data validation" property is known as the command immediate property (the Event Handler is a command control).
They do 2 different things. The command immediate property behaves as outlined above. When input immediate is set to true, it will not make much difference during a normal page submit (without the "No data validation" check box). During a "No data validation" submit, an Edit Box with input immediate true will perform server data validation of the edit box. Then, if the value is valid [getComponent('inputText1').isValid()], the input control "localValue" will contain the updated value [getComponent('inputText1').getValue() will have changed]. The value in the input immediate edit box is not saved to the document. That is, dominoDocument1.firstName will not contain the updated value. So the input immediate property does not allow the value to be saved, just validated. In this case, the "Process Validations" phase does not occur exactly as above. It gets as far as putting the converted value into the control's "localValue", but does not copy the value into the underlying document. While the control's "localValue" is set, the behavior of the "getValue()" method changes. It returns the "localValue" instead of retrieving the value from the underlying document. Using the input immediate property during a command immediate event is the only case where getValue() and dominoDocument1.firstName do not return the same result.

Example scenarios for "No data validation"
Scenario A is just a Cancel button. Scenario C is the most interesting option, where you are doing a partial update when a control value changes and you use the value of that control to determine what is shown after the update. Scenario B is a simplified version of Scenario C, when you don't need to access the control value during the update. Scenario D is a common mistake where you disable client validation and it seems that the events stop working.

Scenario A Cancel button or open page without saving.
As mentioned above, you may be attempting to create a Cancel button or link for when you do not wish to save your changes, but it doesn't work because you keep seeing error dialogs in the browser.
For this you can just use the "No data validation" check box without any additional coding.
If you want to use a control value during this event, then you'll need the extra coding outlined in Scenario D.

To run this example, first create an XPage named "page2" which you will navigate to.
Then create a new XPage, switch to the Source tab of the editor, and paste in this contents.

Source for example A


The first button, with label "Cancel", was created by changing the Button type from "Button" to "Cancel".
That action causes the "No data validation" check box to be checked in the Events panel.
When you leave the edit box blank and click the Submit button, a dialog appears indicating that the value is required.
When you click the Cancel button, the dialog does not appear, and the browser navigates to page2.

Since the Link label does not say Cancel, the link was created with a Confirm Action,
so the user knows that when they click the link, their changes to the document will be discarded.
If the confirm dialog is not always needed, put the Confirm Action in a conditional Action Group.
When you click on the Link, a dialog appears to confirm that you want to navigate,
and when you click OK, it navigates to the other page.
The required dialog does not appear because the link "No data validation" check box was checked.



Scenario B Check Box that causes different page content to appear by Partial Update
You may have a link where the event action does not use the document data,
but the action can cause the page to appear differently, e.g. by changing a variable controlling visibility.
Again in this case you can just use the "No data validation" check box without any additional coding.
The submitted information about which event occurred is passed to the server,
and the action response is executed. In this case, where you are not using data from the browser page,
the only effect of the "No data validation" option is to ensure that the browser Required dialog does not appear.

This is less complicated than when the control is bound to document data [see Scenario C below]

For example, Create a new XPage, in the Source tab paste the source below, and Preview the XPage.
If you click the submit button, an error dialog appears with the text "Field is required".
If you click on the link, the error dialog does not appear, and the submit is allowed,
because in the link Events view, the check box "No data validation" is checked.
The Partial Update area then refreshes, and the blue div is shown or hidden.

Source for example B




Scenario C Partial Update when Combo Box onchange occurs
In this case you have a combo box where the option chosen determines what other values are displayed in the page.
You would use the "No data validation" check box for the "onchange" event, so that the page can update
and display the other values even when required fields are not present.
However the "No data validation" option means you will have to change the code referring to the value in the check box.
Even though the combo box is bound to a document field, you cannot refer to the value of the field in the document
when deciding what other values to show. Instead when "No data validation" is checked,
you must instead get the value using "getSubmittedValue()" on the control.

Try out this example. Create a new XPage and paste in the source below. Preview.
If you click the submit button, an error dialog appears with the text "Field is required".
If you choose an option in the first combo box, the error dialog does not occur, and the submit is allowed
because in the onchange Event for that combo box, "No data validation" is checked.
The second combo box then refreshes with different contents, depending on the selection in the first combo box.
The value selected in the first combo box during a "No data validation" event,
is only available by calling getComponent('comboBox1').getSubmittedValue()
The value from the browser is not saved to the underlying document.