• Create an action
• Access the Reference tab
• Enter the script
• Compile and test the script
• Edit the script
• Review the lesson
• Do it on the Web

The script that you create in this lesson will run whenever the user clicks the action.

1. Open the "Learning LotusScript" database if it does not appear in the Design pane.

3. Choose Create - Action. The actions appear on the right of the screen, and the Action properties box appears.

4. In the Action properties box, name the action "Display title." Close the properties box.

6. Select "Click" from the list of programmable events on the Objects tab if it is not already selected.

Step B: Access the Reference tab

The Info List appears on the left-hand side of the Programmer's pane. It contains two tabs, the Objects tab and the Reference tab. If you can't see the Reference tab, drag the bar separating the two sides of the Programmer's pane to the right. The Objects tab contains events and objects that can be programmed and the Reference tab contains information about using Notes classes, properties, methods, and the LotusScript language. In this step you learn that:

• A Notes class is a way of representing something from the "real world" within a script. For example, a database is something from the real world that interacts with Notes; to represent it in a script, you use the NotesDatabase class.
• A property is an attribute of a class. For example, all databases have a title, so the NotesDatabase class has a Title property.
• A method is a behavior or action of a class. For example, a database can replicate with another database, so the NotesDatabase class has a Replicate method. When you use a particular class, its properties and methods are available to you.
• The LotusScript language is related to, but not the same as, the Notes classes. The classes provide an interface to Domino from within a script. The language provides you with a syntax for declaring variables, creating conditionals and loops, and performing operations such as arithmetic. Without the Notes classes, LotusScript is unable to access anything in Notes.

1. In the Programmer's pane, click the Reference tab.

2. Drag the edges of the Info List to the right and up, if you want to make the pane larger.

3. Select "Domino: Classes" from the drop-down menu. The Reference tab displays the classes available.

4. Use the scroll bars to look at the classes available to you. You should recognize many of the class names as things you have used in Domino.

5. Expand the NotesDatabase class by clicking the triangle.

6. Expand Properties under NotesDatabase class.

8. Now select "LotusScript Language" from the drop-down menu.

9. Expand All. The Reference tab displays different parts of the LotusScript language.

10. Scroll through the list of LotusScript functions. Find Dim and Messagebox.

Step C: Enter the script

You're ready to enter the script. Go to the right-hand side of the Programmer's pane and edit the subroutine so that it looks exactly like this. Case does not matter, but the Programmer's pane enforces initial capitals for LotusScript keywords (but not the names of classes, properties, and methods). The consecutive quotation marks (a set of two on line 3 and two sets of four on line 4) have no intervening spaces.

Sub Click(Source As Button)
   Dim db As NotesDatabase
   Set db = New NotesDatabase( "", "Learning LotusScript.nsf" )
   Messagebox """" + db.Title + """",, "Title of database"
End Sub

Compiling is the process by which a script is translated into executable code. Domino compiles the action script when you save, or close and save the document it's on.

1. Choose File - Save.

2. If you get the message "Data not saved due to script error(s)," check the error at the bottom of the Programmer's pane, then double-check your typing to make sure that the script looks exactly like the one in Step C.

3. Choose Design - Preview in Notes. Alternatively, you can open the database in the Notes client and open or create a document based on the "Main Topic" form.

4. Click the "Display title" action on the action bar. Notes displays a dialog box that says "Title of database" and "Learning LotusScript." Success!

A common error is to not specify the name of the database correctly. If you do that, "db" will represent an empty NotesDatabase object. If the Title property displays as an empty string, ensure that the file name of the database in the script is correct and the server name is two consecutive quotation marks (no spaces). Fix the script, recompile, and test it again.

Step E: Edit the script

You may not need to edit your script after saving it, but if you do, here's how.

1. Open the "Learning LotusScript" database if it does not appear in the Design pane.

2. Select "Forms" in the Design pane, then open the "Main Topic" form in the Work pane.

3. If the actions do not appear on the right, drag the right-hand edge of the pane to the left until you can see the names of the actions.

4. Select the "Display title" action.

Review: How did the script work?

The lines of script you entered mean: I want to access the "Learning LotusScript.nsf" database on my local computer, and I want to use the name "db" to refer to this database. Then I want to display the title of the database.

Line 1: Begin a subroutine

Sub Click(Source As Button) defines the beginning of the subroutine. Domino creates this line for you.

Line 2: Declare an object variable

Dim db As NotesDatabase declares a variable called db as an instance of the NotesDatabase class. Whenever a variable is declared as an instance of a class, it's called an object. The variable name db is your invention.

• Dim tells LotusScript that you are declaring an object variable. You use Dim (along with As) any time you declare a variable. For example:
  Dim x As Integer
  Dim name As String
  Dim view as NotesView
• db is the name of the object.
• NotesDatabase is the name of the class.

Set db = New NotesDatabase( "", "Learning LotusScript.nsf") sets the value of the object db so that it refers to the "Learning LotusScript.nsf" database on the local computer.

• Set db = tells LotusScript that you want to set db equal to the value returned by New.
• New tells LotusScript that you want to construct a new object.
• NotesDatabase tells LotusScript that the new object should be an instance of the NotesDatabase class.
• "" and "Learning LotusScript.nsf" are parameters that tell New how to create the object you want. The first parameter is the name of the server; here it's an empty string, which means that the database is on your local computer. The second parameter is the file name of the database.

Messagebox """" + db.Title + """",, "Title of database" gets the title of the database and displays it in a dialog box.

• Messagebox is a LotusScript language statement. The commas separate parameters. The plus signs concatenate strings. Messagebox displays the first parameter in a dialog box and displays the third parameter as a header for the box. The second parameter is not used.
• db.Title returns a string containing the title of the database. Title is a property defined in the NotesDatabase class. To access or modify a property in a script, you need three things:
  • The name of the object, such as db
  • A dot, or period (.)
  • The name of the property, such as Title
• """" + db.Title + """" puts quotation marks around the title. Quotation marks delineate string literals. If you want a quotation mark inside a string literal, you double it. The plus sign means concatenation. So this means one quotation mark followed by the title followed by one quotation mark.
• "Title of database" is a string literal. It will appear as the header of the dialog box.

End Sub defines the end of a subroutine. This is where the script finishes. Domino creates this line for you.

Do it on the Web

LotusScript cannot run in a browser. If you preview the "Main Topic" form in a browser, you will see that the "Display title" action is missing. This is because it is in LotusScript and Domino will not transmit it to a browser.

The only way you can run LotusScript through a browser is to write a Domino agent and activate it from the browser with the RunAgent or ToolsRunMacro @commands or the OpenAgent URL command. However, it is important to know that the agent executes on the Domino server containing the agent, not in the browser.

Create an agent

Agents constitute another category of design elements, independent from forms.

1. Select "Agents" in the Design pane, then click "New Agent." The Agent Properties box appears. The Programmer's pane appears next to it.

2. Name the agent "Display title."

3. Select the "Shared" option.

4. In the Runtime section click the "On event" trigger and select "Agent list selection" from the drop-down box.

5. Select "None" for the target.

6. Select LotusScript from the Run menu in the Programmer's pane.

7. Select "Initialize" from the list of programmable events on the Objects tab.

Enter the script

Edit the subroutine so that it looks exactly like this.

Sub Initialize
   Dim db As NotesDatabase
   Set db = New NotesDatabase( "", "Learning LotusScript.nsf" )
   Print "<B>Title of database<HR>""" + db.Title + """</B>"
End Sub

When you activate a LotusScript agent from a browser, its Print statements write back to the browser on a new page. The Print statement in this script:

• Opens a new page in the browser
• Displays in bold "Title of database" followed by the title of the database on the next line. Since this text is going to a browser, the HTML tags <B> (bold), <HR> (hard return), and </B> (end bold) are interpreted.

You should adjust several properties for Web agents.

1. Save and close the agent. Notice that the name of the agent is "(Display title)." The title is in parentheses because the agent is hidden from the user, the result of selecting the trigger "Agent list selection."

2. Ensure that the agent is highlighted and choose Agent - Agent Properties. The properties box for the agent opens.

3. Click the Design tab.

4. Check "Run Agent as Web user." For identification and security, you usually want the agent to run with the browser login name. This is Anonymous or a user name in the Domino Directory. Otherwise, the agent runs with the name of its creator.

5. Close the Agent properties box.

Create an action

Now you need to create the form action.

1. Open the "Main Topic" form.

2. Choose Create - Action.

3. In the Action properties box, name the action "Display title." (You can have multiple actions with the same name.)

4. On the "Action Hide When" tab, check "Notes R4.6 or later" so this action does not show up in the Notes client. Close or move the properties box.

5. Select Formula from the Run menu in the Programmer's pane.

6. Add the following formula to the Programmer's pane. Ensure that the name of the agent is exact and includes the parentheses.

@Command([Runagent]; "(Display title)")

You can test a local database in a browser by using "localhost" for the host name. If you use a proxy server, ensure that "localhost" is on the list of hosts that do not use the proxy server.

1. Choose File - Save.

2. If you get an error at the bottom of the Programmer's pane, double-check your typing to make sure that the formula is correct.

3. Choose File - Database - Access Control. Select "Anonymous" from the list of people, servers, and groups. Change the access to "Author" and check "Create documents." Click OK.

4. Choose Design - Preview in Web and the name of your browser. Alternatively, you can open the browser and enter the OpenForm URL command, for example:

 http://localhost/Learning+LotusScript.nsf/MainTopic?OpenForm

You may have to use Design - Preview twice or follow the URL command with one Design - Preview to force the browser to access your test database.

Challenge: Displaying the file name of a database

Using what you have learned, write a script that prints the file name of the "Learning LotusScript" database.

1. Open the "Main Topic" form in the "Learning LotusScript" database.

2. Create an action and give it a name.

3. In the Programmer's pane, select LotusScript from the Run menu.

4. On the Reference tab, select Domino: Classes.

5. Find a property in the NotesDatabase class that allows you to get the file name of a database.

6. Using what you have learned, write the script.

Solution: Displaying the file name of a database

The FileName property in the NotesDatabase class provides you with the information you need. You can access it the same way that you accessed the Title property: with an object, followed by a dot, followed by the property name. One way to complete the script is like this:

Sub Click(Source As Button)
   Dim db As NotesDatabase
   Set db = New NotesDatabase( "", "Learning LotusScript.nsf" )
   Messagebox db.Filename,, "File name of database"
End Sub

Glossar