Adding Power with Domino URLs

Domino URLs are a way of extending the power of Domino objects to a Web browser. In its simplest form, the basic syntax of a Domino URL is the following:

http://Host/DominoObject?Action&Arguments

Typically, this is the syntax you use to access Domino database objects such as forms, views, pages, and so on. A more complete version of the syntax is the following:

http://Host/Database/DominoObject?Action&Arguments

This syntax is pretty straightforward. It tells the browser the names of the host, database, and Domino object and then what action to take. Some actions have arguments; some arguments, such as Login , can be universally used.

Domino URLs cannot have spaces in them, so you must replace any spaces with the + symbol. For example, views and forms often have spaces in their names. To open them, you need to construct the URL in this manner:

http://hostname/SAMS/Chapter20.nsf/By+Title?OpenView

The parts of a Domino URL are separated by a forward slash. For example, the previous URL refers to a database in the SAMS subdirectory under the NOTESDATA directory on a Domino server (hostname).

Working with Host and Database

Host can be either a DNS entry or an IP address. DominoObject can be any one of a number of server and design elements, such as pages, forms, views, and databases. For example, Figure 20.4 uses a Domino URL to access a Cascading Style Sheet stored in a document.

TIP

Domino URLs can be self-referencing. If you need to access an object in the current database, you can safely omit the Host argument. Listing 20.6 uses this technique to build a dynamic Domino URL.

 

The next several sections elaborate on the various parts of Domino URLs as shown in Listing 20.6.

Listing 20.6 Creating a Dynamic Domino URL That Opens a Style Sheet

REM "/host/database/style.css?OpenFileResource";
cLink := "

"

?OpenFileResource is a new Domino 6 URL command that can be used to access any shared resource in the database. The technique illustrated in Listing 20.6 can also be used with all Domino URLs that relate to the same database. In fact, if you need to access other databases on the same host, you can still omit the Host argument and simply use the filename or the replica ID preceded by two underscores. If you need to access a database on a different server, you need to provide that server's hostname or IP address. The formula in Listing 20.6 dynamically obtains the name of the database by the following:

cDBName := @ReplaceSubstring(@Subset(@DbName;-1);"";"/")

@DbName returns a text list that contains the server name and the database. To get the database name, use the argument shown in the previous example. You might know that @Subset(@DbName; -1) produces the name of the server. However, the name of the server and the hostname are not the same. The hostname is the name associated with the server's IP address in DNS, or the IP address. You can find the name of a Domino server in the HTTP section of the Server document under Internet Protocols. If the entry is blank, it uses the name of the machine on which the server runs. The @ReplaceSubstring command flips the backslash to a forward slash to support Web addressing if the database contains a long path , such as DDriveMyapp.nsf.

If you really need to get the hostname, the code shown in Figure 20.6 shows one technique via JavaScript. You can also use the CGI Server_Name variable to obtain the current hostname or IP address.

Using Domino Objects and Actions

When you've determined the host and the database name in a Domino URL, you are ready to work with the database objects. An action followed by optional arguments tells the Domino server what to do with the object. Actions are usually preceded by a question mark ( ? ), although an exclamation point ( ! ) is also permissible. The default action is ?Open , and actions can be explicit or implied . An example of an explicit action is ?EditDocument , and its implicit counterpart is ?Edit . Table 20.6 lists the Domino objects you can access with Domino URLs and their associated actions.

Table 20.6. Domino Objects and Actions

Object	Actions
Agent	OpenAgent
Shared resource	OpenFileResource
Database	OpenDatabase , OpenAbout , OpenHelp , OpenIcon , SearchDomain , SearchSite
Document	OpenDocument , CreateDocument , DeleteDocument , EditDocument , SaveDocument
Form	OpenForm , ReadForm , OpenElement
Frameset	OpenFrameset
Navigator	OpenNavigator
Page	OpenPage
Server	OpenServer , Redirect
View	OpenView , SearchView

Referring to Domino Objects

You can refer to Domino objects in a number of ways. You can refer to them by name or alias. You can also refer to an object by its universal ID (UNID) or by the NoteID. Some special objects also can be referenced in Domino URLs through the use of special identifiers. These identifiers enable you to access objects such as the default view, the "About This Database" and "Using This Database" documents, and so on. These are listed in Table 20.7 for your convenience.

Table 20.7. Special Domino URL Identifiers

URL Identifier	Reference
$defaultView	The default view
$defaultForm	The default form
$defaultNav	The default navigator
$searchForm	A form used to search databases
$file	Used to access a file attachment in a document
$icon	The database icon
$help	The "Using This Database" document
$about	The "About This Database" document
$first	The first document in a view

You can use these identifiers in Domino URLs to perform actions such as opening the Help documents. The following is an example that opens the About document in the database Chapt20.nsf located in the Book subdirectory.

http://SAMS/chapter20.nsf/$About?OpenAbout

The following example opens the default view:

http://SAMS/chapt20.nsf/$defaultview?OpenView

Opening Documents by Key

To open documents with a Domino URL, it's pretty apparent that you use the OpenDocument action. So how do you specify a document? You have to reference it with a key value, or the document's UNID or NoteID. It's often much easier to use a key value rather than the UNID or NoteID. The NoteID is an 8-character hexadecimal number, and the UNID is a 32-digit hexadecimal number that Notes generates internally when the document is saved. A key value is a string that locates a document in the first sorted column of a view. Because you can specify the field or fields to sort on in the view, it is easy to determine which document to open. For example, Listing 20.4 opens a document based on a key value. The Domino URL that is constructed looks like the following:

This URL looks in the database for a particular document via the (AllDocs) view and opens it.

This is not only easier to code, but it is more user -friendly than using either the UNID or the NoteID to go searching for the file or image resource. Domino URLs can appear in the Address field (or the Location field in Netscape Navigator). A URL with a 32-digit hexadecimal number included is not very readable, as you can see from the following example:

Working with Domino URL Arguments

Many of the actions listed in Table 20.7 have arguments that can further refine the URL. Arguments are appended to the action with the ampersand character ( & ). Rather than present an exhaustive listing of all arguments, I discuss a few here so that you understand how to use them.

One of the simplest and most common arguments is the Login argument. You can append this to almost any Domino URL, and it enforces user authentication. For example, you can provide a login button or hotspot with a Domino URL such as the following:

http://MyHome.nsf?OpenDatabase&Login

When the user clicks the button or hotspot in the browser, Domino returns a challenge with a username and password dialog box.

OpenView has a number of arguments, as you can see in Table 20.8.

Table 20.8. OpenView Arguments

Argument	Description
Collapse=n	Where n is the row number. Displays the row in collapsed format.
CollapseView	Displays the view collapsed.
Count=n	Limits the number of rows to display.
Expand=n	Where n is the row number. Expands the view at row n .
ExpandView	Displays the view expanded.
Start=n	Where n is a row number. Starts the display of the view at row n .
StartKey=key	The view must be sorted. Starts the display of the view at the document that matches the key.
RestrictToCategory=category	Sets the category for Show Single Category object, where all documents containing the exact category are to be displayed in the view.

To open the default view in the database in collapsed mode, use the following code:

http://MyData.nsf/$defaultview/?Openview&CollapseView

To open a view and display only 10 rows, use the following code:

http://MyData.nsf/$defaultview/?Openview&Count=10

Adding arguments to Domino URLs is pretty simple and can produce some powerful results. In contrast to the simple examples in this section, you can use arguments to submit requests for SSL certificates or to create sophisticated domain and site searches.