Tips for designing Notes® and Web applications

Security

The security model is different for Notes® and Web users. Manager and Designer access to databases is not available for Web users as it is for Notes® client users. Therefore, do not include LotusScript® actions or agents that require a user to have Manager or Designer access to complete the task.

Authenticating users requires extra planning for applications available via Web browsers. Most Web applications provide some level of access for Anonymous users. For higher levels of access, you must match Web users to the names in the Domino® Directory. Because Web users generally login to an application using an abbreviated name, consider using the @UserName command to return their fully distinguished Notes® name for proper authentication.

Forms

Many times the same form will work in both a Notes® client application and a Web application. You can compensate for minor differences in functionality using hide-when formulas for design elements on a form. At times you may want to display one subform for a Notes® client and another for a Web browser. In this example, the formula calls one of two computed subforms named NS and IE that include browser-specific code by using the CGI variable for browser type in @BrowserInfo:

@If(@BrowserInfo("BrowserType")="Netscape";"NS";"IE")

Each subform has its own JavaScript™ Header, so you can selectively include JavaScript™ as well as other data types in your forms by using computed subforms.

All subforms open simultaneously with the main form. You can't display a computed subform on the basis of calculations after the page opens.

Forms are quite flexible in a mixed-client environment. Using programming designed to support multiple clients, you can program a form event to execute one set of commands when accessed by a Notes® client and another set of commands when accessed by a Web client. In some cases, you may find it easier to design two completely separate forms -- one for a Notes® client, and another for a Web client. In this case, you assign the same alias to the two forms, hide one from the Notes® client, and the other from the Web client, so that the correct form displays in the correct context.

Fields

Consider that not all field types that are supported in a Notes® application are supported in a Web application. For example, the Web does not support a multivalue keyword field that allows users to enter choices not in the list. The workaround for this is to use two fields in a Web application -- one field to accept new choices for the list and the other field to build and display the list. If users can access the application from either the Notes® client or the Web, you must synchronize the field values so that all users see the same values.

If you can solve a problem with two versions of a field formula, one that works in Notes® and the other that works on the Web, then include both in the form and use the "Hide from Notes/Hide from Web browsers" selection in the Field Properties box to display one or the other.

If you're using the same form for both Notes® clients and browsers, the "Hide from Notes/Hide from Web browsers" attribute on a design element's properties can be very useful. However, note that "hidden" has a different meaning for each client. In Notes®, hidden fields are still present in the document and can be used in scripted calculations. Fields hidden from Web browsers, on the other hand, are cut out of the document by Domino® before the page is served to the browser. The field contents are not available to be used by JavaScript™.

Tip: If you want to make fields invisible in a browser, but keep their contents available to JavaScript™, don't use the "Hide from Notes/Hide from Web browsers" and don't put "type=hidden" into the fields' HTML Body Attributes objects. Make sure that:

• Their hide-when properties are set correctly for the Notes® client.
• "Use JavaScript™ when generating pages" is set in the Database Properties box.
• "Generate HTML for all fields" is selected in the Form Properties box.

Domino® will generate the appropriate <type=hidden> tags in the HTML page:

<input type="hidden" name="fieldname" value="fieldcontents">

Be aware that names and values treated this way are not secure. They can still be seen by any user who clicks on the browser's "View Page Source" function.

Remember, too, that not all fields can be passed to a browser this way -- the password field, for example, "$Updatedby," "$HtmlHead," and any objects that contain NULL characters (which includes users' public keys) because NULLs cannot be expressed in HTML.

Actions

Actions play a more significant role in Web applications because Web browser users do not have access to the Notes® menu commands. You must supply an action for tasks such as creating a document, switching to Edit mode, switching views, or forwarding documents. Therefore, in many cases you must design an action bar specifically for a Web application that you hide from Notes® client users.

Views

Displaying Notes® views in a Web application results in a loss of some display attributes unless you first embed the view on a page. You can embed multiple views on a page to achieve a sophisticated layout. You can also specify a view template that will apply uniform style properties to embedded views for use in Web applications.

For more information, see Displaying views in Web applications.

Navigation

Using an outline for navigation can provide a uniform structure for Notes® client and Web browser users. An outline lets users open views, pages, or URLs. Embed the outline on a page to preserve all of the display properties for Web browser users.

You might also consider an imagemap as a navigation tool.

For more information, see Outlines, navigators, and imagemaps.

Agents

Programming with agents provides all of the processing power for an application. Using agents is where you will encounter the most significant differences in developing applications for Notes® client and Web browsers. Although you should be able to share a lot of code, there will be instances when you need to write certain agents for the Web, and certain agents for the Notes® client. The key programmable server events for Web applications are WebQueryOpen and WebQuerySave. To avoid performance problems, use these events to perform key tasks, and use background agents to perform more complex processing. Agents can be run from the Web using @Command([ToolsRunMacro]) or @URLOpen formulas.

By default, Web agents run under the identity of the agent author (the person who saved the agent). To run agents under the identity of the Web user, open the Agent Properties box, click the Design tab, and select "Run Agent as Web user" option in the For Web Access section. This option can provide more security, because when a Web user tries to run an agent with this property set, Domino® prompts the user for a name and password and checks them against the invoker's rights in the database ACL.

In the Notes® client, many form, field, and button events can be scripted in either JavaScript™ or LotusScript® (or, to be sure, @formulas). Depending on how your application uses scripted events, this may mean that you write your agents using JavaScript™ and use the same form for both Notes® and Web clients. There are differences in the capabilities, however. JavaScript™ in the Notes® client has access only to the data in the currently open form -- it lacks the access to the front-end and back-end Domino® Objects of LotusScript®. Your application may work best if you write LotusScript® for execution in the Notes® client and JavaScript™ for browsers, and use hide-whens or separate forms to keep the execution straight.

Keep in mind that many @functions and @commands don't work in a browser. The @functions that don't work fall into three major categories:

• They work only in the Notes® client interface. There are no browser counterparts to @DialogBox, @Picklist, and @Prompt, for example. And several advanced mail-handling functions are unique to the Notes® client, such as @MailSend and @IsDocBeingMailed.
• The much simpler structure of Web views doesn't support many functions, including @DocChildren, @DocLevel, @DocNumber, @IsCategory, or @Responses.
• Many features associated with Notes® access, preferences, and the workstation environment don't carry over to a browser -- @Certificate, @IsAgentEnabled, @MailEncryptSavedPreference, and @UserPrivileges, for example.

Most @commands are associated with controlling the Notes® client interface, so they don't work in Web applications. The handful that do work on the Web work hard, though, because they're used often. @Command([FileSave]) and @Command([FileCloseWindow]), for example are used frequently together to simulate a Submit button.

For the complete list, see Domino® @functions that are not supported on the Web

Replacing dialog boxes for Web applications

You should consider designing forms for your application to replace error messages and Help dialog boxes that are missing on the Web. Particularly if you require users to authenticate in order to use your application, you should create a $$ReturnAuthenticationFailure form to inform users that authentication failed and give them links they can use to navigate back to familiar territory in the application.

Create your form and save it with the name $$ReturnAuthenticationFailure. In order to make this form available for public access, you must do two things. First, you must set the Default role in the Access Control List to read public documents.

Second, set the form's security properties to make it available to public users by choosing "Available to public Access Users" on the Security tab of the Form Properties box.

There are four reserved form names that you can use to create customized error messages for browser users: $$ReturnAuthenticationFailure, $$ReturnAuthorizationFailure, $$ReturnDocumentDeleted, and $$ReturnGeneralError.

For more about these fields and how to use them, see Displaying a customized error message.

Programming for multiple platforms

You can now program the same event in Designer for the Notes® client and the Web browser. You can optimize the code in an event -- for example, the Click event of a button -- for the platform it will run on. Code you supply for the Client platform executes when a user runs the application in the Notes® Client. Code you supply for the Web platform executes when a user runs the application in a browser. These dual platform events are available for selected events on Forms, Pages, Subforms, Fields, Buttons, Actions, and Hotspots.

Planning for browser differences