Working with $$Return Fields
When Web clients submit a document, Domino returns a generic confirmation message of “Form processed” by default. $$Return is a reserved field name that you can use to customize the generic Form Processed Confirmation message.
By adding a text—computed for display and field named $$Return—to a form, you can add HTML to the Value event of this field. Table 16.11 lists and explains some examples of $$Return.
| Type of Custom Message | Code to Be Placed in the Programmer's Pane of the Field's Value Event |
|---|---|
| Thank You | “Thank you for your suggestion.” |
| Personalized Thank You—with Users Name | If the site has forced authentication, then the users name is available and can be added to the formula to personalize it. “Thank you “ + @UserName + “ for your suggestion.” |
| Thank You with Link to a New Page | HTML link code can be included in the $$Return field to give the user a way out of the Form Processed Confirmation document. “Thank You” +”<br><a href http://www.lotus.com> Lotus Web Site</a>” |
| Redirect to another Web site | If Designers want the Form Processed Confirmation to automatically redirect to another Web page or site, enclose the URL in brackets. “[http://www.mycompany.com]” |
You may encounter other reserved $$Return names associated with forms rather than with fields. $$Return form names, like $$Return fields, allow you to display custom messages that include links or redirections instead of HTTP error messages. If an application requires authentication, a Web user would receive an Error 401 User not authenticated message if they failed.
Creating a $$ReturnAuthenticationFailure form is a method you can use to create a custom notification that the user could not validate; you also can use this method to provide a link to retry or redirect to a registration page. Table 16.12 lists and describes the four reserved form names that create custom error messages.
| Form Name | Description |
|---|---|
| $$ReturnAuthenticationFailure | Username and password could not authenticate with the server. |
| $$ReturnAuthorizationFailure | Database access is insufficient for what the user is trying to do. |
| $$ReturnDocumentDeleted | Validation that a document was successfully deleted. |
| $$ReturnGeneralError | All other error conditions. |
To create a Custom Error Message Form to display non-generic messages if a user could not authenticate, follow these steps:
1. | Create a form named $$ReturnAuthenticationFailure. |
2. | Create links, text messages, or computed redirection fields. |
3. | On the Security tab of the Form Properties, check Available to Public Access Users. |
4. | In the Database ACL, make sure Default and Anonymous access have Read Public Document privileges. |
Optionally, you can choose to create a MessageString field option. MessageString is a reserved field name and displays the HTTP generated default error. This field could be used in conjunction with a Computed for display field, which contains a formula that creates the custom message based on the value in the MessageString field. MessageString can be referred to without adding the field to the form.
Other reserved field names are listed in Table 16.13.
| Type | Description |
|---|---|
| HTML | HTML contained in this field is passed directly to the browser and Domino ignores all other fields. |
| $$HTMLHead | Information in this field is HTML code and will be passed to the browser as part of the <HEAD> tag for a document. |
 | For the exam, familiarize yourself with the reserved fields used to create custom error messages (as listed in Table 16.12) and the reserved HTML fields (listed in Table 16.13). |