Lesson 1: Printing the title of a database

Lesson 1 creates a script that displays the title of a database when a user clicks an action. You should already have created a sample discussion database called "Learning LotusScript®."

Step A: Create an action

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.

    Work pane displaying a design list with the Main Topic form highlighted

  2. Select "Forms" in the Design pane, then open the "Main Topic" form in the Work pane. The form appears at the beginning of the Work pane. The Programmer's pane appears.
  3. Choose Create - Action. The Action properties box appears.
  4. In the Action properties box, name the action "Display title." Close the properties box.

    Action Properties box

  5. Select LotusScript® from the Run menu in the Programmer's pane.
  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 in 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. 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®.

The following steps do not create anything. They are just to familiarize you with the Domino® classes.

  1. In the Programmer's pane, click the Reference tab.
  2. Drag the edges of the Info List 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 twistie.
  6. Expand Properties under NotesDatabase class.

    Reference tab displaying the properties of the NotesDatabase class

  7. Expand Methods 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 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

This is how the code looks in the Programmer's pane.

Programmer's pane displaying the LotusScript code for an Action button

Step D: Compile and test the script

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 end 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.

  5. When you are finished, go back to Domino® Designer and close the "Main Topic" form.

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, adjust the edge of the pane 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.

Line 3: Set the value of the object

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.

Line 4: Display a property of the object in a dialog box

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.

Line 5: End the subroutine

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

In an agent, use Sub Initialize for the executable code. The Dim and Set lines are the same as in the action you wrote to run on the Notes® client. The Print line differs.

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.

Adjust the agent properties

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)")

Test it on the Web

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 end 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.

  5. Click the "Display title" action on the action bar. The browser opens a new page that says "Title of database" and "Learning LotusScript®." Success!

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