Академический Документы
Профессиональный Документы
Культура Документы
Preview
Copyright, Disclaimer of Warranties and Limitation of Liability
IBM, LearningSpace, Lotus, Lotus Notes, LotusScript, Sametime, and TeamRoom are registered trademarks and
Domino, Domino.Doc, Domino Extended Search, Domino Workflow, K-station, Notes, QuickPlace, and the e-business
logo are trademarks of International Business Machines Corporation. All other product or brand names may be
trademarks of their respective companies.
You must purchase one copy of the appropriate kit for each student and each instructor. For all other education products
you must acquire one copy for each user.
You may not copy, reproduce, translate, or reduce to any electronic medium or machine-readable form, in whole or in
part, any documents, software, or files provided to you without prior written consent of IBM Corporation, except in the
manner described in the documentation.
While every reasonable precaution has been taken in the preparation of this manual, the author and publishers assume
no responsibility for errors or omissions, nor for the uses made of the material contained herein and the decisions based
on such use. Neither the author nor the publishers make any representations, warranties, or guarantees of any kind,
either express or implied (including, without limitation, any warranties of merchantability, fitness for a particular purpose,
or title). Neither the author nor the publishers shall be liable for any indirect, special, incidental, or consequential
damages arising out of the use or inability to use the contents of this book, and each of their total liability for monetary
damages shall not exceed the total amount paid to such party for this book.
The term ‘Preview’ in the document header, denotes that this education manual has not been copyedited,
formatted or otherwise quality tested for final print production. This manual has been prepared for the purpose
of providing you with a preliminary version of the final courseware. This manual shall become obsolete with the
availability of the final version of the courseware.
IBM offers the widest range of server platforms for Lotus Domino, including the Intel processor-based Netfinity server
family. With Netfinity servers, solutions ranging from simple e-mail to unified messaging to Web site hosting and
collaborative applications such as distance learning and knowledge management are confidently executed. Both the
Quality Assurance Engineering and Curriculum Development departments, within Lotus' education line of business,
utilize Netfinity servers to develop and test the company's education offerings. Domino's functionality combined with the
IBM mark of reliability on the Netfinity product family differentiates Lotus from its competition. With more than 70% of
the world’s data residing on IBM systems, and with the innovative software products and services from Lotus
Development, IBM and Lotus are taking connectivity to a new level in all aspects of business — from document
management to e-business.
Preview
Table of Contents
T o pi c Page #
Table of Contents
T o pi c Page #
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 1
© Cop yr ig ht IB M Co rpo ratio n 200 2. All rig hts re serv ed.
Preview
Cou rs e D escr ip tio n an d Strate gy
Course Description
Target audience
The target audience for Using LotusScript in IBM Lotus Domino Applications is
Application developers who will be using LotusScript in their Domino applications.
Summary description
Students will learn the techniques of programming in LotusScript while they learn
to access and work with objects in the Domino Object Model.
This course:
Introduces students to the LotusScript language
Instructs how to retrieve properties of a database
Introduces the use of the LotusScript Debugger
Uses methods of NotesDatabase
Traverses down the Document Object Model to ACL classes.
The skill of navigating the Document Object Model is continuously reinforced
throughout the course as students learn to work with front-end and back-end
classes.
Course Description...(continued)
Course goals
Topics covered
The Using LotusScript in IBM Lotus Domino Applications course covers the following
topics:
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 3
Preview
Cou rs e D escr ip tio n an d Strate gy
Course Strategy
Approach
Recommended agenda
The tables on the following two pages describe the recommended agenda for
delivering the material over the three days.
Course Strategy...(continued)
Day 1
1 hour Lunch
Day 2
1 hour Lunch
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 5
Preview
Cou rs e D escr ip tio n an d Strate gy
Course Strategy...(continued)
Day 3
1 hour Lunch
Instructor Preparation
Course Materials
Preparation Checklist
CLI Certification Requirements
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 7
© Cop yr ig ht IB M Co rpo ratio n 200 2. All rig hts re serv ed.
Preview
In stru cto r Pr ep aration
Course Materials
Instructor kit
The following table lists and describes the content of the instructor kit.
Student kit
The following table lists and describes the content of the student kit.
Preparation Checklist
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 9
Preview
In stru cto r Pr ep aration
Preparation Checklist...(continued)
For more information on how to teach this course, refer to the CLI Private Site
locate at http://www.lotus.com/cli.
If you have already registered, enter your user name and password to access the
Instructor Lounge and other private areas of the Web site to gain additional
information for teaching this course.
If you have not registered, visit the Education Zone located at http://
www.lotus.com/educationzone and follow the instructions to register for the
certified community. After registering, you will be able to access the CLI Private
Site using your user name and password.
The Interactive Instructor Guide (IIG) is an IBM® Lotus® Domino™ database that
contains constructive comments from Certified Lotus Instructors (CLIs) who have
taught this course. Consult the IIG to learn about courseware issues, resolutions,
tips, and techniques for teaching this course. If you have insights you would like to
share with other CLIs after teaching this course, please include your comments in
the IIG so that other instructors may benefit from your experience.
The IIG is structured so that instructors can:
Provide feedback on courseware.
Submit courseware problem reports.
Share course delivery tips and tools.
Lotus software monitors this site to provide:
Responses to feedback.
Solutions to courseware problems.
Courseware updates.
You can access the link to the IIG from the CLI Private Site located at http://
www.lotus.com/cli.
Preparation Checklist...(continued)
In the table below, list and describe any additional resources the instructor can
use to prepare to teach this course. Information can include Web sites, white
papers, Redbooks, and so on.
http://www-10.lotus.com Domino 6
Go to LDD Today Domino Designer 6
Iris Today Archives
By Product Version
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 11
Preview
In stru cto r Pr ep aration
CLI Certification
Requirements
To learn about the requirements for becoming a CLI or to upgrade your current
certification, visit the IBM Software Services for Lotus Certification Web site at
http://www.lotus.com/certification.
Classroom Setup
The following system specifications and setup procedures were used to
develop and test this course. If the classroom setup does not match these
specifications, Lotus software makes no guarantee that the learning processes
in this course will perform as stated.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 13
Preview
Classr oo m Se tup
Machine Requirements
The following table identifies the number of Notes/Domino license types required
for the instructor machine(s) for this class.
The following table identifies the number of Notes/Domino license types required
for the student machines for this class.
Machine Requirements...(continued)
The following table lists the software and hardware required per instructor and
student machine to deliver this course.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 15
Preview
Classr oo m Se tup
Classroom Setup
Instructions
Complete the tasks in the following table to set up the classroom prior to the start
of class. Detailed procedures for each task appear on the following pages.
Task Procedure
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 17
Preview
Classr oo m Se tup
Follow these steps to properly set up the server machines for this class.
Step Action
5 Assign the new user to the Administrators group by doing the following:
Select Groups.
Double-click the Administrators group.
Click ADD.
Double-click db2admin. Click OK.
Click OK.
Step Action
Follow these steps to install the configuration and data files for this course.
Step Action
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s 19
Preview
Classr oo m Se tup
Follow these steps to set up the Lotus Domino 6 server and client applications on
the same system.
Step Action
4 Start the Domino server and verify that it works. Verify that the DIIOP task
runs.
Note: It is recommended that you start the Lotus Domino R5 server as an NT
service.
5 Register a fictitious user for the students to work with in the labs.
8 Once you verify that the server works, shut it down for the remainder of the
setup procedures.
1
Introducing LotusScript
1
Introducing LotusScript
This lesson describes LotusScript and introduces some basic syntax. It describes
how to store data in variables, how to comment code, and how to use the
LotusScript debugger to track down errors in the code.
Objectives
Introducing LotusScript
Start by asking students why they want to use LotusScript. Discuss where, when,
and why to use LotusScript. If students suggest using it to access objects, ask
what Domino objects are.
Introducing LotusScript
Advantages of LotusScript
Developers should use LotusScript for Domino applications when they need to do
the following:
Develop sophisticated scripts with conditions, branches, loops, and
subroutines.
Place scripts in a variety of objects and events.
Debug complex code.
Use OLE to access other applications.
Introducing LotusScript...(continued)
Explain that LotusScript does not run in Web browser. There are other options for
applications that will be run in both the Notes Client and Web browsers.
Introducing LotusScript...(continued)
LotusScript does not run in Web browsers, but a Web user can invoke LotusScript
code that runs on the Domino server. Using events or a Domino URL command,
users can execute LotusScript agents that access data stored in the application,
but cannot manipulate the user interface of the application.
LotusScript datatypes
Ask students the following types of questions as you present the table from the
Student Guide.
What types of data contain text?
What types of data contain numbers?
What is the difference between integer and long?
What is the difference between integer and single or double? What is the
difference between currency and single or double? Answer: There are only
four significant digits in the decimals.
Scripts use variables to store values and work with the data. A variable is a named
location in memory. Each variable is declared as a certain data type. The data
type determines how much space is reserved for the data. Once the variable is
declared, data can be stored in it.
Before declaring a variable, consider what type of data it will hold, then choose the
best available data type. Data types can be scalar (numeric and string) or more
complex types like an array, variant, or an object reference. We will discuss these
more complex data types later in this course.
The following table describes the scalar data types available in LotusScript.
Declaring variables
You cannot name variables using keyword names, such as string and integer.
Address case sensitivity
To declare a variable in LotusScript explicitly, use the Dim keyword to define the
name and type of the variable. Dim stands for dimension. When you declare a
variable, you are reserving a piece of memory. The amount of memory you
reserve depends on the data type you use to declare the variable.
Syntax
Dim varName as data type
Examples
The following examples define the variable partNumber as an integer and the
variable firstName as a string of text.
Dim partNumber As Integer
Dim firstName As String
Note: When using the Dim statement, you can specify the data type with either
the appropriate keyword (Single) or suffix (!). Data type suffixes are listed in the
data types table on the previous page.
Example
Dim counter As Integer
or
Dim counter%
The following rules apply to constructing a valid name or identifier for a variable:
The first character must be a letter.
The remaining characters must be letters, digits, or underscores ( _ ).
The maximum length of a name is 40 characters.
Names are not case-sensitive. For example, firstName is the same name as
FIRSTname.
Review the answers with students by doing one or more of the following:
Ask students to provide answers and generate a discussion. Each description
may have more than one correct answer.
Write answers on the whiteboard.
Ask students if currency automatically formats the result or not.
In this exercise, choose the best data type to represent the variable described.
Then, write the declaration in the space provided.
Describe the assignment operator and explain the example from the Student
Guide.
Use the assignment operator (=) to set the value of a variable. The data type of
the value and the variable must be compatible.
Example
'Declare variables
Dim partNumber As Integer
Dim msg As String
Dim msg2 As String
In this Guided Practice, you will write LotusScript code that declares variables and
assigns values to them. Add the code to a button and use the built-in MessageBox
function to display the values of the variables.
Follow these steps to assign values to variables.
Step Action
1 Open the Demos and Activities database in Domino Designer. Open the
Variables Activity form.
3 In the Programmers pane, select the Click event of the button and select
LotusScript from the Run menu.
Step Action
5 Enter the following code to assign each variable a value. (You may substitute
any valid value for those given here.)
MyFavMovie = "Metropolis"
rating = 5
7 Choose File Æ Save to compile the script and save the form.
If any compile-time errors are found, fix them and repeat this step.
8 Preview the form in Notes and click the button. Observe the values as the
message box appears.
Use the Variables Demo form in the Demos and Activities-Instructor database
to illustrate implicit variable declarations.
Show how the suffix, $, declares the variable for the phone number.
myphone$="617-123-9876"
Uncomment the statement that changes the phone number. Save the form
and explain the compiler error that results because the suffix is missing.
'myphone="941-472-2112"
Ask students why implicitly declaring variables can be difficult to troubleshoot.
Note: Data type suffixes are listed in the Data Types table on page 7 or use
Domino Designer Help to find the suffix for each data type.
Open the (Options) Event for the Variables Demo button on the Variables
Demo form and add the following line of code:
Option Declare.
Show how Designer automatically puts the statement in the Options event of
the button.
Save the form to show that the compiler does not allow the implicit declaration
for the variable myphone$.
Add the explicit declaration and preview the form.
Although implicit variable declarations may save some time and typing, they are
not recommended for large or complex code because it is easy to forget the suffix
character. If you omit the suffix, the LotusScript compiler will think the variable is of
type Variant. A variant is a general-purpose data type that can hold almost any
type of data (such as a string, number, array, or object reference).
To force code to use explicit variable declarations, specify the following statement
in the (Options) script of an object:
Option Declare
This statement causes the compiler to flag any variable that is not explicitly
declared. This helps eliminate potential data type mismatches at run time.
Commenting Code
Add each type of LotusScript comment to an existing form, like the Variables
Demo form. Explain why students might pick one method over another.
Commenting Code
Examples of comments
'Calculate commission
commission = totalSales * commissionRate
%Rem
msg$ = "hello world"
Messagebox msg$
%End Rem
LotusScript errors
Describe the two types of errors that occur when working with LotusScript.
Types of errors
The following table describes the two types of errors that LotusScript recognizes.
Debug pane
Script area
Utilities pane
Part Function
Continue button Runs the current script and stops only if an error
is found.
Step Over button Executes the current statement and steps to the
next.
Step Exit button Executes the current subroutine and, upon exit,
resumes debugging.
Step Action
3 Execute the code. For example, run the agent or click the button.
Result: The script pauses and the debugger opens.
4 Use the contents of the debugger window and its functions to identify
problems in the code.
Step Action
1 Open the Variables Activity form in your Demos and Activities database.
2 Select the Variables Activity button and add the following code before the
first Dim statement:
'Declare movie and rating variables
8 The debugger will automatically stop processing the script at the first
assignment statement. In the Utilities pane, click the Variables tab and
notice that the variables have default values.
9 Click Step Over and examine the Variables tab again. Notice that after the
statement executed, the MyFavMovie variable has a new value.
10 Continue to click Step Over and notice the values of the variables change.
Once the message box displays, click OK.
2
Accessing Database
Information
2
Accessing Database
Information
In this lesson, you will start using LotusScript to access a NotesDatabase object.
At the same time, you will learn more LotusScript techniques, such as using an
If...Then statement to check the value of a method or property.
Objectives
Use this section to review the concept of the Domino Object Model that students
learned in Domino Application Architecture.
Ask students to name Domino objects. Ask students what an object is. LotusScript
lets you write a program to work with these discrete entities just as a user works
with the discrete entities through Notes and Domino Designer. For example, a
user or a LotusScript program can open a document and change a field value.
The NotesDatabase class represents a Domino database, its properties, and
things that it can do, such as open or create a copy of itself.
Ask students to describe the difference between the back-end and front-end
classes, reviewing what they learned in Domino Application Architecture.
Present the concept of containment in the Domino Object Model. You want
students to be able to identify that the containment model identifies the path they
need to use to access their objects.
Domino objects
Domino objects are a set of classes that represent the elements of a Domino
application. Each class has properties and methods that allow developers to script
their behavior.
The Domino objects are grouped into the following two sets of classes:
Back-end classes represent databases and elements as they appear on-disk,
without regard for what users are doing.
Front-end, or user interface (UI), classes represent the database or element as
it appears to the current user.
A containment hierarchy is the relationship that the Domino object classes share.
Certain classes contain other classes. This relationship provides a path through
the objects that a script can take to access the object data or function it needs.
Consider the Domino containment model. A Domino server contains Domino
databases. Domino databases contain notes, and notes contain items. To access
an item value, you must access a database, and a note. You cannot access
document or a view without a database.
Use the diagram to illustrate how to identify the path and containment.
Declaring an object
In addition to the scalar data types described in the previous section, LotusScript
also provides more complex data types. For example, the Domino objects
represent sets of different data types and procedures that are wrapped into a
particular type of class. To use the Domino objects in a script, define object
reference variables and assign them values through documented properties and
methods.
Use the Dim keyword to declare an object reference variable in the same way you
declared scalar values.
The following statements are examples of declaring object reference variables:
Dim db As NotesDatabase 'declare a NotesDatabase object
Dim doc As NotesDocument 'declare a NotesDocument object
Dim v As NotesView 'declare a NotesView object
Develop a set of standard variable names for referencing Domino object classes,
and use them consistently. It will make your code easier to read and maintain.
To set the value of an object, use the Set keyword. Set works with a method or
property of one of the Domino objects that contains the class you want to create.
Syntax
Set objectRef = classMethod or classProperty
Examples
'use property from the session object
Set db = s.CurrentDatabase
If an object has a method called New, you can use it to construct an instance of
the object. You do not have to use other properties or methods from other classes.
In other words, it is a shortcut to that point in the containment path.
Describe the various methods of instantiating a NotesDatabase as listed in the
table from the Student Guide.
Open Domino Designer Help to the NotesDatabase class. Scroll through its
methods and locate New.
In order to use New, you need to know enough information about the object. For
example, with NotesDatabase, you need to know the server and file names.
Ask students to provide examples of database properties that they might want to
access programmatically.
Explain that the Title property contains the name of the database.
Step Action
2 In the Programmers pane, select LotusScript from the Run drop-down list.
3 In the click event of the button, add the following code to create the object
reference variable for the database:
Dim db As NotesDatabase
Set db = New NotesDatabase ("","Inventory.nsf")
4 Continue adding the following code to the button script to display the
database title:
Messagebox "Database title is " & db.Title
5 Continue adding the following code to display the name of the server
containing the database:
Messagebox "Database server is " & db.Server
Note: This will be blank if the server is local.
6 Continue adding the following code to display the file name of the database:
Messagebox "Database filename is " & db.FileName
7 Add the following code to change the title of the database and to display the
new title:
db.Title = "My Local Directory"
Messagebox "Database title is " & db.Title
8 Choose File Æ Save to compile the code and save the form.
Code should always check for errors and have a route to exit gracefully. You can
check the results of actions performed by the script by using an If…Then
statement. If something goes wrong, you can notify the user, try again, or stop the
script.
Example
The following example will show the first message if the value for x is greater than
zero or the second message if the value is less than zero.
If x > 0 Then
Messagebox "The number is positive. "
Else
Messagebox "The number is not positive."
EndIf
The Exit Sub statement stops the execution of the current subroutine. If there is an
error that prohibits the script from continuing (such as not finding the specified
database), you can use this statement to stop the subroutine before it starts to
open views and documents.
Example
If db.IsOpen = False Then Exit Sub
In this guided practice, you will add code to the DB Properties form to verify that
the database opens before displaying the properties. You will use the IsOpen
property of the NotesDatabase class to determine if the database opened
successfully. You will also use an If…Then statement that exits the subroutine if
the database is not open.
Follow these steps to complete this guided practice.
Step Action
1 Open the DB Properties form in your database and click the Properties
Activity button you created in the last guided practice.
2 After the code statement that instantiates the database (set db = ...), add the
following statements:
'if database is not opened, exit the sub
If (db.IsOpen = False) Then
Messagebox "Could not open database"
Exit Sub
End If
3 Choose File Æ Save to compile the code and save the form.
Open Domino Designer Help and point out some commonly used properties and
methods.
Show the code in the Using Properties button on the DB Properties form.
Preview the form with the debugger running. Show the Variables tab in the
debugger.
When writing a script that manipulates data in the same database, use the
NotesSession class to access it. Once you have the current database, you can
access all of its data.
Explain the code in the Using Methods button of the DB Properties form.
Preview the form and click the button.
Ask students how many database references exist when a copy of the database is
created, to reinforce the idea that variables are references to an object.
The user opens the database, and then chooses a menu option to create a
New Copy.
Then the user enters the server and file name of the new database.
The program must also open the database, but instead of using a menu, it
uses a method to create the new copy.
Students will use this method in the next exercise, Creating a New Copy of a
Database.
The NotesDatabase class provides a method for creating a new database based
on another database. The other database may or may not be a template.
Use the following syntax to use the CreateCopy method to create a new
database based on an existing one.
Syntax
Set newNotesDatabase = currentNotesDatabase.CreateCopy
(newServer$, newDbFile$, [, maxsize% ])
Example
The following example creates a copy of discuss.nsf, located on the Anchorage
server. The new copy, named suggest.nsf, will be placed on the Juno server and
its title will be changed.
'Declare object reference variables
Dim db As NotesDatabase
Dim newDb As NotesDatabase
'Instantiate object reference variables
Set db = New NotesDatabase("Anchorage", "discuss.nsf")
Set newDb = db.CreateCopy ("Juno", "suggest.nsf")
'change the title of the new database
newDb.Title = "Suggestions for Giving Campaign 2001"
In this exercise, students will create a button that copies the Inventory database
from the server to their local machines. Students will use this database in future
exercises.
Present the exercise by:
Identifying which database and form students will use.
Asking if students have any questions before starting the exercise.
(Optional) Demonstrating the completed code using the Create a database
button on the Create DB form in the Demos and Activities-Instructor database.
You must add the name of your server to the code before it will work.
After completing the exercise: Have students copy the course documents from the
Inventory - Instructor database and paste them into their student Inventory
databases. This action will:
Illustrate the point that no documents are copied when using the CreateCopy
method.
Prepare the student Inventory database for use in the Interacting with Users
Programmatically Exercise in Lesson 5: Working with NotesUIDocument.
In this exercise, you will create a new database and access its properties. Then,
you will open it in the Notes client and examine its contents.
3
Navigating the Domino
Object Model to Access
ACL Information
3
Navigating the Domino
Object Model to Access
ACL Information
This lesson focuses on finding a path through the Domino object hierarchy to
access the data you need. The lesson uses the NotesACL and NotesACLEntry
classes as an example. While explaining how to access the ACL, the lesson
introduces LotusScript techniques such as constants and Select...Case
statements.
Objectives
Use properties of the NotesACLEntry class to retrieve the access level of an ACL
entry using LotusScript.
The following diagram shows the path for accessing the NotesACLEntry class.
Work out the path of an object using the object model. Explain what to look for and
how to get started. It may be best to work backwards, starting with ACLEntry and
working up the hierarchy. Draw the path on the whiteboard.
Ask students to identify the methods and properties for retrieving the ACL levels.
Add the answers to the path you drew on the whiteboard.
Once you determine the object path, search the list of properties and methods of
each class that retrieve each object in the path.
In this demonstration, first show what the GetEntry method does in the Notes
Client, then show the code behind the method in Designer.
In the Notes Client, open the Select and ACL Access form.
Click the Get the first ACL Entry-demo button.
Open the Select and ACL Access form in Domino Designer.
Select the Get the first ACL entry-demo button.
Explain each line of the code
Relate the path on the whiteboard that retrieves the ACL entry to the
LotusScript statements.
Add the code that retrieves the level of the ACL entry to the Get the first ACL
Entry-demo button.
Ask how you get the name of the current user.
For example:
The NotesACLEntry represents an entry in the access control list. Each entry is
identified by the name of the user or group.
To retrieve the level associated with the user or group, use the Level property. The
Level property returns a constant.
Introduce constants
Using constants
Explain where constants are defined and how to incorporate them in scripts.
Constants
Defining constants
The ACLEntry class provides a set of constants that represent each possible
access level. You do not need to include LSCONST.LSS or any other file to use
these constants.
The following table describes the constant and integer values for each access
level.
This construct is like an iterative If statement. We will use the Select Case
construct to convert integer constants to strings that hold meaningful text for a
user.
Use the Select and ACL Access form and explain the code in the Select Case
button. The code is also the example in the Student Guide.
In the Notes Client, open the Select and ACL Access form.
Click the SelectCase-demo button.
Open the form in Designer and change the value of num to 2.
Preview the form in the Client and re-select the SelectCase-demo button.
As a review, and to get students more familiar with traversing the object model,
ask students to find the path to some other objects or piece of information. For
example, remove a form from the current database or access the creation date of
a view. Then, as a class discussion, determine the properties and methods of all
the objects.
The Select Case statement is useful when you need to execute a block of
statements based on the value of an expression.
Syntax
Select Case selectExpr
[Case condList [statements]]
[Case condList [statements]]
...
[Case Else [statements ]]
End Select
Example
The following example displays a message with the num value and the
appropriate suffix, such as 1st or 2nd.
'Declare variable for number between 1 and 10
Dim num As Integer
'Declare variable for concatenation
Dim ord As String
'Set value of number
num = 1
Select Case num
Case 1
ord = "st"
Case 2
ord = "nd"
Case 3
ord = "rd"
Case Else
ord = "th"
End Select
Messagebox "You made the : & num & ord & " selection."
In this exercise, you will use LotusScript and the Domino objects to retrieve your
access level to a database on the instructor’s server and display it in a message
box.
For example, if Molly Kennedy has Author access to the database, the script
displays the following message:
The level of access for Molly Kennedy is Author.
4
Working with
NotesUIWorkspace
4
Working with
NotesUIWorkspace
This lesson introduces the user interface (UI) or front-end classes. It focuses on
interacting with the user through the NotesUIWorkspace class. It also
differentiates between functions and subroutines.
Objectives
The user interface classes define information and functionality available to the
Notes client. Using these classes, application developers can write scripts that run
as users interact with the application and manipulate the elements that users
actually see.
The following diagram shows the user interface (UI) class hierarchy.
It is important to note that LotusScript does not work in Web browsers, but it can
be invoked on the server based on a Web client request.
LotusScript does not affect the Web user interface, because browsers do not
interpret LotusScript. To manipulate the user interface of a Web browser, use
JavaScript. Lotus Notes and Domino Designer support JavaScript, which allows
application developers to work with one language when developing applications
that exist on the Web and in Notes.
AddDatabase method
Ask students to give you the code to add a database to the workspace.
Many user functions can be scripted using the NotesUIWorkspace class. For
example, adding a database to the workspace and opening a database.
AddDatabase method
OpenDatabase method
Invoking subroutines
Describe the two ways of invoking subroutines. The course manual typically uses
the Call statement because it is easier to read. Advise students to pick a way and
be consistent.
Invoking subroutines
Use the Call statement to invoke LotusScript subroutines. For example, use Call
to invoke the AddDatabase and OpenDatabase methods of the
NotesUIWorkspace class.
In this guided practice, write a small script to add the database created in the
Creating a New Copy of a Database Exercise in Lesson 2 to the workspace.
Follow these steps to complete this guided practice.
Step Action
3 Add the following code after the statement that sets the database title and
before the End Sub statement:
Dim w As NotesUIWorkspace
Set w = New NotesUIWorkspace
Call w.AddDatabase ("", "Inventory.nsf")
5 Delete the Inventory database you copied during the exercise in Lesson 2.
6 Remove the icon and/or bookmark for this database in your Notes client.
7 Preview the form in Notes and click Create a Database. Check the
workspace (or list of bookmarks) for the new icon.
Describe the prompt method. It works the same as the @prompt function. It is a
good way to gather small amounts of information from users.
Briefly explain the table of dialog box options. The types of dialog boxes available
to the prompt method are the same as the @prompt function.
Either explain the code behind the NotesUIWorkspace, Prompt Practice button or
delete the code before class and enter it in front of the students. Preview the form
and click the button.
The Prompt dialog box can be one of several types. The types are defined by
constants. Each type of prompt allows the user different options and returns
values to indicate the user’s choice.
The following table shows the types of Prompt dialog boxes and their return
values.
PROMPT_OK 1
In this exercise, students use the prompt method and If...Then...Else statements
to ask users a question and confirm the response.
The goal of the exercise is to use the prompt and capture the user response. How
to mail the description is of no concern at this point.
In this exercise, you will add a button requesting that a course description be
delivered by mail or by e-mail.
To complete this exercise, create a button on the Course form in the Inventory
database. Add code to the button that does the following:
Displays a message asking if the course description should be sent by mail,
and three buttons (Yes, No, and Cancel).
Displays another message based on the button the user clicks.
The following table describes the desired behavior of the script.
Note: In the final application, the document would be sent to the user's e-mail
address. We will examine how to do that later in this course.
5
Working with
NotesUIDocument
5
Working with
NotesUIDocument
Objectives
Ask students to provide the code to access the Current Document property and
write their answers on the whiteboard.
The current document is the one being displayed in the Notes client at the time the
script executes. It is accessible through the NotesUIWorkpace and is represented
by the NotesUIDocument class.
To access the current document, use any of the following from the
NotesUIWorkspace class:
CurrentDocument property
ComposeDocument method
EditDocument method
Define NotesUIDocument. Open Domino Designer Help to show the complete list
of properties and methods.
Open Domino Designer Help and display the document describing the
ComposeDocument method of the NotesUIWorkspace class. Describe the
parameters.
Ask students about the benefits of windowWidth and windowHeight. The answer
is that you can simulate a dialog box, which uses a form that you have already
built.
Use the Call statement to invoke a function when the function’s return value is not
important. The Call statement does not return the function’s value.
Example
The following example creates a new document based on the Main Topic form
located in the discuss.nsf database
Call w.ComposeDocument ("server01", "discuss.nsf", "Main
Topic")
Present the syntax and the example from the Student Guide. Note that the field
can be referenced with a variable.
Ask students to find the method for updating a field value. They will have to refer
to the NotesUIDocument class in Help. Ask them to identify the arguments.
Point out that the method returns a string value. Regardless of what field type the
data is coming from, it is returned to LotusScript as text.
Open Domino Designer Help and show some examples of the conversion
functions.
LotusScript can read values from the currently displayed document by referencing
the fields.
As the name implies, this method returns a text value from a specified field. If the
value needs to be used in a calculation it must be explicitly converted to a numeric
or datetime data type.
Syntax
textValue$ = notesUIDocument.FieldGetText([fieldName$])
Example
The following example returns data entered in the FirstName field.
fname$ = uidoc.FieldGetText("FirstName")
Before you can set the value of a field on the current document, you must place it
in edit mode. To do this in LotusScript, set the EditMode property to True.
Point out that variables can represent the argument values, which allows you to
pull data from other sources and automatically update the document.
The current document must be in edit mode in order to change its field values.
Once the document is in edit mode, the script can modify the field values with text.
The FieldSetText method sets the value of a specified field. The value must be a
text value.
Syntax
Use the following syntax to set a field value on the current document.
Call notesUIDocument.FieldSetText(fieldName$, textValue$)
Example
The following code statement sets the value of the FirstName field, on the current
document, to Molly.
Call uidoc.FieldSetText("FirstName", "Molly")
In this guided practice, students will concatenate two field values together and
place the result in a third field.
Review the purpose of the Entering event.
Review the guided practice with students to make sure they understand. Make
sure they understand why they used the plus sign instead of the ampersand.
If some students finish early or need an additional challenge, have them add a
Salary field of type currency. Assign a value to it in its Entering event to
demonstrate FieldSetText and how to convert the value to a string.
In this guided practice, you will write a script that concatenates the values in the
first and last name fields and places that value in the FullName field.
Follow these steps to set the field values.
Step Action
5 Choose File Æ Save to compile the code and save the form.
6 Preview the form in Notes.
7 Enter text in the FirstName and LastName fields.
8 Place the cursor in the FullName field (click or tab) and observe the
results of the Entering script.
Describe the NotesUIDocument events and provide some examples for using
them.
Events occur when the user performs an action within the user interface. The
NotesUIDocument provides several events that can be used to trigger scripts.
NotesUIDocument events
The following NotesUIDocument events are triggered in the Notes client and
accept LotusScript code:
Queryopen
PostOpen
Querymodechange
Postmodechange
Postrecalc
QuerySave
Postsave
Queryclose
Use code from the ValidateField-demo form, the QuerySave event, to illustrate a
simple field validation routine that runs when the form is saved.
Use the QuerySave event for functionality that must run before the document is
saved. This event is commonly used to validate several field values before
allowing the user to save a document.
Example
The following script checks the value in the LastName field before saving the
document. If the value is null, it displays a message to the user and stops the save
procedure.
Sub QuerySave(Source As NotesUIDocument,Continue As Variant)
Dim lname As String
lname = Source.FieldGetText ("LastName")
If lname = "" Then
Messagebox "Please enter your last name. "
Continue = False
End If
End Sub
Use the PostOpen event for functionality that should run before the user has
access to the document but after it is loaded into memory. This event is commonly
used to inform the user about the document or to warn of any restrictions for using
the document.
Example
The following script examines the CheckedOut field of the current document and
displays a message to the user if the document being opened has already been
checked out.
Sub PostOpen (Source As NotesUIDocument)
If (Source.FieldGetText ("CheckedOut") = "Yes") Then
Messagebox "This document is currently checked out. "
End If
End Sub
In this guided practice, students will write code that displays a prompt if the
document is new.
Review the purpose of the PostOpen event.
Describe the behavior of the IsNew property.
In this guided practice, you will write a script to determine if the document that the
user is opening is a new document. If the document is new, display a message to
the user that this is a new document.
Follow these steps to complete this guided practice.
Step Action
3 Choose File Æ Save to compile the code and save the form.
In this exercise, students will display a personalized thank you message when a
user saves a document.
Demonstrating the completed exercise.
You may elect to perform the first three bullet items in the exercise as a group
discussion.
Review the exercise with students by displaying and reviewing the answer to
make sure they understand.
In this exercise, add some user interaction to the Student form in the Inventory
database. Add code displaying a message to the users, thanking them for signing
up for a particular course. For example:
Thank you Frank Grimes for signing up for the Ceramics course.
The message should use the current user’s name and the course name from the
current document. When they test the code, students should be told to open a
course document in the Course Summary view, and click Add a student.
6
Accessing Data in
Documents
6
Accessing Data in
Documents
This lesson starts by showing how to retrieve a document and how to locate its
properties and item values. It then moves on to looping through a view to find a
particular document. Then, the lesson introduces the NotesViewEntry class for a
more direct route to application data.
Objectives
Ask students to give you the steps that a user would use to access a document in
a client.
The steps a program must execute are essentially the same.
Creating a session
The NotesSession class represents the environment in which the script runs. It is
very similar to a user being in the Notes client. From the session, a script can
open a database and read information about the environment (such as the current
user name and the version of Notes).
To create a session object, use the following syntax:
Dim s As NotesSession ' declare variable for the session
Set s = New NotesSession ' instantiate object
Opening a database
There are several options for opening a database in LotusScript. From a session
object, you can use the CurrentDatabase property to retrieve the database in
which the script is currently executing. To open another database, use the
GetDatabase method.
Example
' Declare object ref variables
Dim s As NotesSession
Dim db As NotesDatabase
Dim db2 As NotesDatabase
' Instantiate session object
Set s = New NotesSession
' Instantiate database objects
Set db = s.CurrentDatabase
Set db2 = s.GetDatabase ("server01", "discuss.nsf")
Describe the GetView method and how to access a view from a database.
Opening a view
Once a database object is instantiated, you can use the GetView method of the
NotesDatabase class to open any view within the database.
Example
The following code retrieves the Topics view from the current database.
' Declare object ref variables
Dim s As NotesSession
Dim db As NotesDatabase
Dim v As NotesView
' Instantiate session object
Set s = New NotesSession
' Instantiate database object
Set db = s.CurrentDatabase
' Instantiate view object
Set v = db.GetView ("Topics")
The NotesDocument class provides access to the information that appears in the
Document Properties box.
The properties of the NotesDocument class represent the data available through
the Document Properties box. For example:
NoteID
Created
LastModified
Size
The NotesDocument class provides other properties that describe the document.
For example:
IsNewNote
IsResponse
ParentDocumentUNID
Before we can access item values, review with students that items (with the
exception of rich text) are stored as lists or arrays. That means there could be
multiple values. To read item values, we must first look at reading array elements.
Then we will examine the extended class syntax for accessing items and, finally,
the GetItemValue method.
Each item (except rich text items) may contain multiple values. For this reason, all
items store their values as arrays, even if there is only one value.
The following diagram shows the structure of items and how the items are
accessed.
Make sure that students understand that even if the item is not a multi-value field,
Domino still stores the value as an array. Therefore, always refer to the value in a
single-value item as fieldname(0).
Make sure that students understand that when reading an item, you do not need
to build arrays.
Access array elements using an index. The first element of an array has an index
of 0.
Example
The following code displays the 1st, 5th and 37th elements in the Students array.
Dim myList As Variant
' code to retrieve document object
myList = doc.GetItemValue ("Students")
' display first (1st) element of array
Messagebox myList(0)
' display fifth (5th) element of array
Messagebox myList(4)
' display thirty-seventh (37th) element of array
Messagebox myList(36)
The extended class syntax provides a shorthand method for reading the values of
an item. The following code sample displays the value of the LastName item.
Dim lname As Variant
' read value of LastName item and copy into variable
lname = doc.LastName
' display last name
Messagebox lname(0)
Explain that GetItemValue and the extended class syntax provide the same
functionality, but the extended class syntax is easier to deal with. Later in the
course, students will learn that it can be used to set item values as well.
Note: When demonstrating this method, show that to access the value, you can
index the variant as an array. For example, the following code will display the
value of the LastName field:
Messagebox lname(0)
Introduce the Do While and Do Until loops. The loops are basically the same. The
difference is how you write the loop condition.
Using methods of the NotesView class, you can search each document in a view
one by one. This is effective if the information you need to access in the document
does not appear in a view. If the data appears in a view, it is more efficient to use
the NotesViewEntry class to access the data.
The NotesView class provides the following methods for stepping through the
documents represented in the view:
GetFirstDocument
GetNextDocument
The Do…While construct allows you to execute a block of statements for as long
as a condition is true.
Syntax
Do While <condition>
[statements]
Loop
Example
The following code moves through a list of documents and stops at the first
document without data.
Set doc = v.GetFirstDocument
Do While Not (doc Is Nothing)
count = count + 1
Set doc = v.GetNextDocument (doc)
Loop
The Do Until loop is another construct that executes a block of statements. This
loop iterates as long as the condition is false, or until the condition is true.
Syntax
Do Until <condition>
[statements]
Loop
Example
The following code displays the value of the Subject item from each document in
the Examples view.
Dim s As NotesSession
Dim db As NotesDatabase
Dim v As NotesView
Dim doc As NotesDocument
Set s = New NotesSession
Set db = s.CurrentDatabase
Set v = db.GetView ("Examples")
Set doc = v.GetFirstDocument
Messagebox doc.Subject(0)
Do Until doc Is Nothing
Set doc = v.GetNextDocument(doc)
Messagebox doc.Subject(0)
Loop
In this guided practice, students will create a button on the Document Retrieval
form. When clicked the button will count all the movies stored in the database and
display the value in a messagebox.
In this guided practice, you will count the number of documents in a view that
contain an item that matches a certain value. You will use a loop construct,
NotesView methods, and extended class syntax to read item values from the
documents in a view.
Follow these steps to complete this guided practice.
Step Action
2 Create a button named Count Movies and add the following code button to
access the current database:
'We are accessing a document in the same
'database the script lies.
'Therefore, get the session, and
'the current database.
Dim s As NotesSession
Set s = New NotesSession
Dim db As NotesDatabase
Set db = s.CurrentDatabase
3 Add the following code to access the Get Document By Key View (alias
GDBK):
'locate the GDBK view to get the document
Dim v As NotesView
Set v = db.GetView("GDBK")
Step Action
This section offers a more efficient way to access application data if it is displayed
in a view. You can pull the data directly from the view rather than accessing the
document first. If the data you need does not reside in a view, you may consider
building a new view to contain it (if that is practical), or you must access the
document as discussed previously in this lesson.
Ask students what class contains the NotesViewEntry class. Then, ask them what
NotesView method gives them access to the NotesViewEntry.
If data appears directly in a view it is more efficient to use this data than to open a
document to access the item value.
NotesViewEntry class
The NotesViewEntry class represents a single row in a view. This class contains
properties that represent the column values displayed in the entry and the
document represented by the entry. It also contains properties indicating if the
entry is a document, category, or total.
Use the GetEntryByKey method of the NotesView class to access a view entry.
Given a key (or array of keys), this method returns the first view entry found that
matches the keys.
Example
The following code retrieves the view entry whose first sorted column displays the
value Dogs.
Dim s As NotesSession
Dim db As NotesDatabase
Dim v As NotesView
Dim ventry As NotesViewEntry
Set s = New NotesSession
Set db = s.CurrentDatabase
Set v = db.GetView("By Category")
' Access the view entry
Set ventry = v.GetEntryByKey("Dogs")
Explain that the ColumnValues property allows you to retrieve data from a view
column or columns.
Make sure students realize that child documents are considered part of the
returned view entry.
In this guided practice, students create a button to count the number of movies
listed under a particular media type. This information is gathered from the View
Entry View (VEV).
This code will use the NotesViewEntry class to count the responses of a particular
media type.
Step Action
1 In the Demos and Activities database, open the View Entry form.
3 Continue adding the following code to read the media type from the current
document.
'get objects to get information from current document
Dim w As NotesUIWorkspace
Set w=New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Set uidoc=w.CurrentDocument
Dim doc As NotesDocument
Set doc=uidoc.Document
Dim ventrydef As String
ventrydef=doc.MRef(0)
7
Le sso n 7 Acc essin g Data in Doc ume nts
7
L es son 7 Acce ssing D ata in D ocu men t s
Step Action
4 Continue adding the following code to access the view entry that matches the
media type and display the number of children.
'get view entry
Dim ventry As NotesViewEntry
Set ventry=v.GetEntryByKey(ventrydef)
'display result
Messagebox "The total number of movies in " & __
ventrydef & " is: " &ventry.siblingcount
7
Writing Data to Documents
7
Writing Data to Documents
This lesson focuses on adding data to existing documents and creating new
documents. It begins with adding and replacing item values in a document using
the extended class syntax as well as the AppendItemValue and ReplaceItemValue
methods. The lesson covers saving a document and synchronizing any changes
with the user interface. This lesson also presents a procedure for creating a new
document with LotusScript, in which items for the application and for Domino
(such as authors, readers, and forms) are added.
Objectives
Explain the extended class syntax for creating new items or setting existing item
values.
The extended class syntax provides a shorthand method for adding new item
values. The following LotusScript statements add new items to documents and set
their values, if the item name does not already exist on the document.
' add Region item and set value to Asia Pacific
doc.Region = "Asia Pacific"
' add Author item and set value to the current user
doc.Author = s.UserName
If the item already exists in the document, the above statements will
overwrite the original value of those items.
Caution
Explain the example from the Student Guide to make sure students know what
each line of the code is doing. Caution students to make sure that their code
appends values of the correct data type.
Ask students to tell you what the example code from the Student Guide is doing.
The ReplaceItemValue
Discuss the results of using the ReplaceItemValue method to create a new item.
The ReplaceItemValue method overwrites the value of an existing item with the
value specified. If the item name specified does not exist in the document, a new
item is added to the document.
Syntax
Call notesdocument.ReplaceItemValue (itemName$, value)
Example
The following code changes the value of the item named Region and saves the
document.
Dim s As NotesSession
Dim db As NotesDatabase
Dim v As NotesView
Dim doc As NotesDocument
Set s = New NotesSession
Set db = s.CurrentDatabase
Set v = db.GetView ("By Location")
Set doc = v.GetDocumentByKey ("Korea")
Call doc.ReplaceItemValue ("Region", "Asia Pacific")
Call doc.Save (False, True)
Results of ReplaceItemValue
Explain that changes do not appear in the database until the document is saved.
Once you make changes to a document in script, you must save the document for
those changes to take effect in the application.
Saving a document
The Save method of the NotesDocument class saves any changes made to the
document.
Syntax
flag = notesDocument.Save (force, createResponse)
Example
The following code saves the document even if another user edits and saves the
document while the script is running.
Call doc.Save (True, True)
When saving a document, you must consider that another user may have edited
the document while the script was running. The parameters of the save method
allow you to control how the document is saved in this case.
If the force parameter is True, the createResponse parameter has no effect.
If the force parameter is False and another user edits and saves the
document, the createResponse parameter determines how the document is
saved:
If createResponse is True, the current document becomes a response to
the original document.
If createResponse is False, the save is canceled.
Describe reasons why it is sometimes necessary or easier to work with the back-
end document.
Describe situations when changes made to the back-end must be reflected in the
UI.
Scripts that execute in the current document may have to access the version of
the document stored in the database.
Work with numeric and time variables. (You can only use text to update a
document in the UI.)
Changing item values in the document is faster than changing fields and
saving the document from the front end.
Update the current UI document when a script does both of the following:
Executes from the UI document (by means of a form action, button, or event).
Changes values in the document (NotesDocument).
Automatic synchronization
Forcing synchronization
Automatic synchronization
Forcing synchronization
You must call the Reload method of the NotesUIDocument when a script changes
items in NotesDocument that were not accessed through the Document property
of NotesUIDocument, and the AutoReload property is disabled.
The Reload method of the NotesUIDocument class updates the current document
with any changes made to the corresponding document stored in the database.
Example
Dim ws As NotesUIWorkspace
Dim uidoc As NotesUIDocument
Set ws = New NotesUIWorkspace
Set uidoc = ws.CurrentDocument
uidoc.EditMode = True
Set doc = uidoc.Document
doc.Subject = "New Subject"
doc.Save (False, True)
uidoc.Reload
Disabling AutoReload
When a script uses both the NotesDocument class and the NotesUIDocument
class, the interactions between the user interface and the database can slow
down the script’s execution. When AutoReload is enabled in the
NotesUIDocument, every time a script changes an item in the document (using
the NotesDocument class), the values are automatically loaded into the user
interface.
If a script makes many changes to the document, you may improve the
performance of the script by doing the following:
Disable the AutoReload property of the NotesUIDocument before making the
changes to the NotesDocument with the following code statement:
uidoc.AutoReload = False
At the end of the script, enable the property again with the following statement:
uidoc.AutoReload = True
In this guided practice, you will update an item in a movie document that indicates
the number of movies in the same category as the current movie. The code
determines the value by counting the responses of the view entry for the current
category. It then updates the item in the document and refreshes the user
interface.
In this guided practice, you will update an item in a movie document that indicates
the number of movies in the same category as the current movie. The code
determines the value by counting the responses of the view entry for the current
category. It then updates the item in the document and refreshes the user
interface.
Follow these steps to complete this guided practice.
Step Action
1 Open the Movie form in your database and create a button named Update
Number in Same Category.
2 Add the following code to initialize the session, database, and view
containing the documents to count:
'Declare variables
Dim s As NotesSession
Set s = New NotesSession
Dim db As NotesDatabase
Set db = s.CurrentDatabase
'get the M view to count documents
Dim v As NotesView
Set v = db.GetView ("M")
Step Action
5 Add the following code to get the number of view entries for the current movie
category:
'get the viewentry for the current category
Dim viewkey As String
Dim ventry As NotesViewEntry
Viewkey = doc.MovieCategory(0)
Set ventry = v.GetEntryByKey (viewkey)
'get the number of children
Dim count As Integer
Count = ventry.SiblingCount
6 Add the following code to update both the back-end and user interface
versions of the document:
'update back-end document
doc.NumCategory = count
'save document
Call doc.Save (True,True)
'update the front end with the back end and save
uidoc.Reload
uidoc.Save
'turn autoreload back on
uidoc.AutoReload = True
8 In the Notes client, open a movie document from the Movies view and click
Update Number in Same Category.
Result: The field value appears in the Number in this Category field.
Emphasize that there are few reasons to use the NotesItem class except for
setting special properties. This is why the first mention of AppendItemValue does
not show using NotesItem with it until this section.
Review retrieving and adding item values to lead to creating a new item with the
NotesItem New method.
Some item properties tell Domino to pay special attention to the value of the item.
For example, properties that identify particular items list the allowable readers and
authors of a document. Also, the IsSummary property identifies items that Domino
can display in views.
Create a new item on a particular document using the New object constructor of
the NotesItem class.
Syntax
Set notesItem = New NotesItem (doc, itemName$, value, Type%)
Example
Set nitem = New NotesItem (doc, "Subject", " ")
The New object constructor of NotesItem accepts another optional parameter that
allows you to identify immediately that the item is a Readers type, and will store
the names of users allowed to access the document.
Example
Set notesItem = New NotesItem (doc, "Readers", " ", READERS)
Once you have an item, you can set the Value property.
Once you have instantiated an object from the NotesItem class, you can use the
Values property to populate the new item with data.
Example
The following code concatenates the first and last name into one, creates a new
Authors item called FullName, and populates it with the concatenation of the
FirstName and LastName items from the same document.
Set notesItem = New NotesItem (doc, "FullName", " ",AUTHORS)
notesItem.Values = doc.FirstName(0) & " " & doc.LastName(0)
Use the procedure listed on the Student Guide to explain the process of creating a
new document. When creating a document programmatically, you must add items
that Domino automatically adds when a document is saved using a form.
You can use LotusScript to create a new document. The new document does not
contain any items; therefore, you must add all items programmatically.
Step Action
5 If the code is run from an opened view, update that current UI view object.
In addition to creating a document that is saved in the database, you can send it to
other people or applications.
Introduce the send method and how to use it.
Sending a document
Use the Send method of the NotesDocument class to route or mail a document to
another user or application. When calling the send method, specify the names of
the recipients in one of the following two ways:
Pass the list of recipients into the method.
Store the list of recipients in an item named SendTo (in the same document).
Example
The following code sends a document to Doctor Notes in two different ways.
Set doc1 = v.GetFirstDocument
' pass recipients into send method
Call doc1.Send (True, "Doctor Notes")
Set doc2 = v.GetNextDocument(doc1)
doc2.SendTo = "Doctor Notes"
' rely on SendTo item for recipients
Call doc2.Send (False)
In this guided practice, write code to create a new movie document. The script will
create all the items, supply the values of those items, and save the document.
Follow these steps to create the new document.
Step Action
1 In the Demos and Activities database open the Create Document form.
2 Add the following code to the Create a new movie button to create a new
document object:
'We are accessing a document in the same database the
'script lies.
'Therefore, get the session and the current database.
Dim s As NotesSession
Set s = New NotesSession
Dim db As NotesDatabase
Set db = s.CurrentDatabase
'Create a document in the db
Dim doc As NotesDocument
Set doc = db.CreateDocument
3 Continue adding the following code to create items for the application:
'Fill in application items
doc.MovieTitle = "add your own movie here"
doc.MovieCategory = "choose from one of the categories here"
doc.MovieDescription = "describe the movie here"
4 Continue adding the following code to set the items Domino needs:
'Set the form item
doc.Form = "M"
'assign authors:
' use username from session and notesitem
Dim nitem As NotesItem
Set nitem = New NotesItem(doc,"Authors", " ", AUTHORS)
Call doc.ReplaceItemValue ("Authors",s.username)
7 Preview the form and click Create a new movie. Check the view for the new
document. Select the new document and open the Document Properties box.
Examine the document contents.
8
Le sso n 8 Wri t i ng D a t a to D oc um e nt s
8
Les so n 8 Wri t i ng D a t a t o D oc u m e n t s
In this exercise, you will use the Inventory database. In the Course Summary
view, create an action that generates a report identifying the number of students
currently registered for a course.
Each student registered for a course is listed in the Course Summary view as a
child of the course name. Use this information to determine the total number of
students in the course.
Challenge
Modify your solution to this exercise so that the action generates the report for the
course of whichever document is currently selected in the view.
Hint: Use the CaretCategory property of the NotesUIView class to read the
category of the currently selected document.
8
Using ViewEntry and
Document Collections
8
Using ViewEntry and
Document Collections
LotusScript provides several classes for accessing data from multiple documents.
Lesson 6: Accessing Data in Documents introduced arrays and how to read data
from individual elements. This lesson begins with more information on building
arrays and iterating through their elements. The lesson then introduces three new
classes that, like arrays, contain several elements. But instead of a group of
integers or strings, these classes contain groups of objects like view entries and
documents. Building on the concept of arrays, you can group related objects
together and iterate through them to examine specific data.
Objectives
Building Arrays
Introduce the For loop and explain the example code from the Student GUide.
Building Arrays
Arrays are useful programming elements when you have to hold multiple values or
lists. Arrays can be static or dynamic. A static array has a specific size that is
known at compile time. A dynamic array changes size at run time.
Declare a static array if you know the number of elements the array will contain.
Example
'declare fixed-length array
Dim firstnames(2) As String
'populate array elements
firstnames(0) = "Molly"
firstnames(1) = "Frank"
firstnames(2) = "Sean"
Building Arrays...(continued)
Explain the example code from the Student Guide. Students will use this construct
later in this lesson.
Building Arrays...(continued)
The ForAll loop is useful for iterating through arrays. One advantage this construct
has is that you do not need to know the number of elements in the array.
Syntax
Use the following syntax for the ForAll loop.
ForAll refVar In arrayName
statements
End ForAll
The reference variable refVar refers to each element in the array as the loop
iterates through the statements. The name refVar is declared by its appearance
in the ForAll statement. It is an alias for each individual element of the array. Its
data type is the data type of the element in the array for that iteration.
Example
The following code uses the ForAll statement to iterate through an array.
'display firstnames array
ForAll fnames In firstnames
Messagebox fnames
Next
Dynamic arrays
Building an array
Use the code behind the ReDim Example button on the Building Arrays-demo
form to illustrate how to create a dynamic array.
Dynamic arrays are useful when the required size of the array is unknown. Initially,
you can declare the array without any size, and later in the program grow the size
to whatever is required.
Declare a dynamic array if you do not know the number of elements the array will
contain. Initially, a dynamic array has no dimensions or elements, and no storage
is allocated for it.
Example
The following code declares a dynamic array.
'declare a dynamic array
Dim fnames() As String
Step Action
3 Add the following variable declarations and instantiations for the arrays and
other variables needed in the code.
'declare dynamic arrays
Dim favmovies() As String
Dim survey() As String
'declare counters
Dim arraycount As Integer
Dim i As Integer
'declare strings to capture results from prompts
Dim movieresult As String
Dim surveyresult As Integer
Step Action
4 Add the following code to access the workspace and the current document (UI
and back-end).
'access the workspace and current document
Dim w As NotesUIWorkspace
Set w = New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Set uidoc = w.CurrentDocument
Dim doc As NotesDocument
Set doc = uidoc.Document
5 Add the following code to display a prompt for the user to enter a favorite
movie and store it in an array. The loop will run until the user enters nothing for
the movie.
Do
movieresult = w.prompt (PROMPT_OKCANCELEDIT, _
"Movies","Enter a favorite movie and click OK. " & _
"Click Cancel to exit.")
If movieresult <> "" Then
Redim Preserve favmovies(arraycount) As String
favmovies(arraycount) = movieresult
arraycount = arraycount + 1
End If
Loop Until movieresult = ""
Step Action
6 Add the following code to survey the user and store the result in another array.
Redim survey(arraycount-1) As String
For i = 0 To arraycount-1
Surveyresult = w.prompt (PROMPT_YESNO, _
"Question", "Did you see " & favmovies(i) & _
" more than once?")
If surveyresult = 1 Then
Survey(i) = "Yes"
Else
Survey(i) = "No"
End If
Next
9 In Notes, click Build a Dynamic Array. Enter a movie title, and click OK. Add
a few more movie titles and then click Cancel. The information you entered
should appear on the document.
Creating a NotesViewEntryCollection
Open Domino Designer Help and display the complete syntax for the retrieval
methods. They work similarly to the methods of NotesView.
Ask students to help you build the code to retrieve entries.
Creating a NotesViewEntryCollection
Create a collection of view entries from an existing NotesView object with the
following:
The AllEntries property provides access to all entries in the view.
Dim veCol As NotesViewEntryCollection
Set veCol = v.AllEntries
The Count property holds the number of entries in the collection. For example, if
there were three documents in the Asia Pacific category of a view, the following
code would display 3.
' v is instantiated as a view object
Dim veCol as NotesViewEntryCollection
Set veCol = v.GetAllEntriesByKey ("Asia Pacific")
Messagebox veCol.Count
Navigating a collection
Navigate through a collection identifying each entry and each entry's column
values.
On the ViewEntryCollection Demo form, click the Navigate a
ViewEntryCollection button.
This button creates a collection of all the entries in the Movies view, and
displays every column value for each entry in a Messagebox.
In this guided practice you will modify code to count the number of movies in the
Comedy category of the Movie view in the Demos and Activities database.
The code uses a NotesViewEntryCollection object to hold all the movies of the
specified category.
Because the view displays report documents along with the movie documents,
scan the column values so that the reports are not included in the count.
If there are no reports, you can use the Count property of the
NotesViewEntryCollection.
In this case, subtract the number of reports from the total count to get the
actual number of movies.
Follow these steps to complete this guided practice.
Step Action
2 Click Count Comedies. Examine the LotusScript code that is already there.
3 Add the following code after the statement 'Add code here…
' Get the Movies view
Set v = db.GetView("M")
' Get a NotesViewEntryCollection for comedy
Set veCol = v.GetAllEntriesByKey("Comedy")
' set count to number of entries in the collection
comedyCount = veCol.Count
Note: If there are no report documents in the view, this is the number of
movies in the comedy category.
Step Action
Using NotesViewNavigator
Use Domino Designer Help and the information from the Student Guide to explain
how to create a NotesViewNavigator object.
Describe the different methods to retrieve entries as listed in the Student Guide.
Using NotesViewNavigator
Using NotesViewNavigator...(continued)
Students will modify the button they worked on earlier in the Count movies in the
Comedy category guided practice. The new button should count movies in each
genre.
(Optional) Run the solution code in the instructor version of the Demos and
Activities database so students are clear about what the code is doing.
Review the guided practice with the students to be sure they understand what
each piece of code does.
Using NotesViewNavigator...(continued)
In this guided practice, extend the functionality of the Count Comedies button
from the last guided practice. The modified button should:
count the number of movies for each genre and display them in a form.
use NotesViewNavigator to build an array of movie genres from the Movies
view.
use a NotesViewEntryCollection to access the entries for each genre and
subtract any reports from the total count.
Follow these steps to modify a button to count the number of movies in each
genre.
Step Action
1 In the Demos and Activities database, open the All Genre Report form.
2 Click Count Movies in Each Genre. Examine the code that is already there.
3 Add the following code after the comment ‘ Add code here…
' get movies view
Set v = db.GetView("M")
' create a view navigator
Set vNav = v.CreateViewNav
' get first entry of navigator
Set ventry = vNav.GetFirst
' get all categories in the view navigator
Do Until ventry Is Nothing
Redim Preserve gArray(count)
gArray(count) = ventry.ColumnValues(0)
count = count + 1
Set ventry = vNav.GetNextCategory (ventry)
Loop
Using NotesViewNavigator...(continued)
Using NotesViewNavigator...(continued)
Step Action
Using NotesViewNavigator...(continued)
Using NotesViewNavigator...(continued)
Step Action
7 Preview the form in Notes and click Count Movies in Each Genre. Verify the
result by examining the Movies view.
The NotesDocumentCollectionclass
Describe the retrieval methods and refer to Domino Designer Help for complete
syntax and details.
Creating a NotesDocumentCollection
Use NotesDocumentCollection
Students will modify the code for an existing button so that it gathers the names of
stars in the listed movies and displays these names in the document.
Use NotesDocumentCollection
In this guided practice, you will add code to a button on the Movie form that lists all
the stars of that movie. The code:
uses a NotesDocumentCollection to gather the response documents of the
current movie.
loops through the collection, gathering the names of the stars listed in each of
the documents.
stores these names in an array.
displays the array of names in the document., after processing all the
documents in the collection.
Follow these steps to complete this guided practice.
Step Action
2 Add the following code to the button after the statement: 'Add code here...
'turn off autoreload, go into editmode
uidoc.editmode=True
uidoc.autoreload=False
'get back-end document of the current document
Dim doc As notesdocument
Set doc=uidoc.document
'get the viewentry representing what is in the
' movie category, stored in viewkey
Dim viewkey As String
Dim ventry As notesviewentry
viewkey=doc.MovieTitle(0)
Set ventry=v.getentrybykey(viewkey)
'get the document of the view entry,
' kdoc for key document
Dim kdoc As notesdocument
Set kdoc=ventry.document
Use NotesDocumentCollection...
Step Action
Use NotesDocumentCollection
Step Action
7 Open a movie document in the Notes client (from the Movies view).
9
Reusing Code
9
Reusing Code
This lesson focuses on sharing code among the scripts of your application. It
begins with a discussion of variable scope and how to define and instantiate
global variables that can be used in multiple programs. It then introduces how to
create functions and subroutines to make code more modular. The lesson ends
with using a script library.
Objectives
Explain the concept of a code module. We have not been concerned about this
yet because all of our code has been written in single events. Now we will look at
declaring one set of global variables that can be accessible to multiple events.
Explain the diagram. It shows that variables declared in the Globals section of an
object are available to the events of that object. However, variables defined within
those events are not available to any other event.
So far in this course, you have defined all variables within the script that uses
them. These variables are only accessible with the script that declares them. For
this reason, they are said to have procedure scope. LotusScript offers the ability to
define variables that have a module scope and are therefore accessible to all
scripts contained in that module.
A module is a set of code that shares the same address space in memory. Each
element has its own module of code associated with it. Examples of modules
include forms, fields, and buttons. Declaring a variable in the form module makes
it accessible to all buttons and fields on the form.
The following diagram shows the relationship of options and variable declarations
defined in the (Globals) section of an object and the other events of the object.
Open Domino Designer and show students where to place variable declarations
for an entire module.
To declare a variable with module scope, place the declaration statement outside
of a procedure. The Programmers pane in Domino Designer provides a place for
you to declare variables that have module scope.
For example, the Objects tab allows you to:
Declare variables that you want accessible to all scripts in the entire form in
Globals.
Declare variables that you want accessible to all scripts in a particular field or
button in Declarations.
In this activity, modify the code in the Movies view to declare commonly used
variables so they are accessible to all code modules in the view.
Follow these steps to declare global variables.
3 Cut each declaration out of the The v and uiv object variables can
action code and paste it into the now be instantiated in any module in
Movies (Globals) module. the view.
4 Save the view and test the action. The action runs as it did before. The
advantage this activity illustrates is
that you do not have to declare
variables for the front-end view or the
back-end view for any other actions in
this view. You can use the global
variables.
Defining variables while the module loads can improve performance of the scripts
that use the variables. Each UI class has a PostOpen event that runs after the
object is loaded. You can place variable assignments in this event so that they are
ready when the scripts on the object run.
Example
The following code assigns object references, declared in the (Globals) script, in
the PostOpen event of the NotesUIDocument.
Sub PostOpen (Source As NotesUIDocument)
Set w = New NotesUIWorkspace
Set db = w.CurrentDatabase
Set uidoc = Source
End Sub
In this activity, move the statements that instantiate the global variables declared
in the Movies view in the Inventory database.
Follow these steps to set the object variables in the PostOpen event.
3 Add the following statements to the Result: The v and uiv object
Movies (View) module in the variables will be instantiated when the
PostOpen event. view opens, which makes them
Set uiv = Source available to any module in the view.
Set v = uiv.View This speeds up the application and
avoids setting the same variables
repeatedly.
4 Save the view and test the action. Result: The action runs as it did
before. The advantage of this
activity is that you can now access
the object data for the front-end
and back-end views from
anywhere in the view, because the
global variables are set as soon as
the view opens.
Students will modify the code on the Course form in the Inventory database
In this exercise, modify the code on the Course form in the Inventory database
so that the front-end document and back-end document are instantiated when the
form loads and are available to all the buttons.
Tasks
Building Functions
Building Functions
Placing code in functions allows you to modularize your programs for easier
maintenance. A function is a named piece of code that performs a particular
action and returns a value. That value can be a scalar, variant, or object reference
data type.
Example
Function calcTotal (orderPrice As Single, orderAmt As Integer)
As Double
' calculate and return the total price
calcTotal = orderPrice# * orderAmt#
End Function
Building Functions...(continued)
Building Functions...(continued)
Building Subroutines
Building Subroutines
Defining a subroutine
A subroutine starts with the Sub keyword and ends with the End Sub keyword. A
subroutine can accept parameters from the calling script.
Syntax
Sub subroutineName (parameter1, parameter2)
'
' subroutine statements
End Sub
Example
Sub alertForBlankField (fieldValue As Variant)
' Display a message to the user if the field is blank
If (fieldValue Is Nothing) Then
Messagebox "Please enter a value in the field"
End if
End Sub
The Exit Sub statement terminates execution of the current subroutine. Execution
continues in the script that called the subroutine.
Example
This example subroutine instantiates object variables for the UI document and the
back-end document when run in the PostOpen event of a form. It assumes that
the uidoc and doc variables are defined globally. If the variable passed to the
subroutine does not contain a UI document object, the subroutine exits.
Sub instantiateDoc (currentDoc As NotesUIDocument)
If (currentDoc Is Nothing) Then Exit Sub
uidoc = source
doc = uidoc.Document
End Sub
Open Domino Designer and show students how to create a script library.
A script library is a module of code that you can reuse in the scripts of the
database that contains it. A script library may contain variable declarations,
functions, and subroutines that can be used in multiple forms, view, actions, and
agents. Using script libraries, you can avoid re-coding the same procedure in
many places.
Step Action
2 Expand Shared Code in the Design list, and select Script Libraries.
4 In the Programmers pane, select the appropriate script from the Objects tab.
5 Add code to the script to define variables, functions, and subroutines that you
will use in other scripts of the database.
6 Choose FileÆSave to compile the code and save the script library.
Introduce the Use statement as the mechanism for incorporating a script library in
your application.
Use statements
To incorporate a script library into another scriptable object, enter a Use statement
specifying the appropriate script library. Place the Use statement in the Options
script of the object.
Code contained in the (Options), (Declarations), Initialize, and Terminate
events of the library becomes available as though it were in the current objects.
User-defined functions and subroutines are also available as though they were in
the current object.
Use statements
At run time, the Use statement loads a module of script for use in the current
module being loaded. The external module is loaded before running the Initialize
subroutine of the current module.
Example
A script library named Error Checking contains the following subroutine:
errorCheck
The following statement placed in the (Options) script of a form makes the
errorCheck function available to the buttons and fields on the form:
Use "Error Checking"
The following statement invokes the subroutine:
Call errorCheck()
Students will modify the Movie form to display a message if errors are detected.
In this activity, use the function in the Error Checking script library to display a
common message when an error is detected. First you will define all global values
then you will define the form’s events.
Follow these steps to complete this activity.
Step Action
2 Before using the script library, declare and instantiate a global variable for
the UI document.
In the Programmer’s Pane, select (Globals) M Æ(Declarations). Add the
following code:
Dim uidoc As NotesUIDocument
3 Load the script library so it can be used on the form. In the Programmer’s
Pane, select (Options) and add the following code:
Use "ErrorChecking"
5 Add the following code to the QuerySave event to check that values were
entered into the fields on the form:
If (uidoc.FieldGetText("MovieTitle") = "") Then
Call errorcheck()
Continue = False
ElseIf (uidoc.FieldGetText("MovieCategory")="") Then
Call errorcheck()
Continue = False
ElseIf (uidoc.FieldGetText("Media") = "") Then
Call errorcheck()
Continue = False
End If
6 Save the form and preview it in Notes. Try to save a document without
entering any values.
10
Processing Run-Time Errors
10
Processing Run-Time Errors
The final lesson in this course discusses how to use the On Error statement and
set up error handling routines to process run-time errors. It introduces the error
constants and how to use them in your code.
Objectives
Run-time errors
Run-time errors are found when a script is executed. The LotusScript compiler
cannot predict these errors when you save the code. Run-time errors generally
prevent the script from running to completion. The following are examples of run-
time errors:
Attempting to access a server that is down
Failing to instantiate an object before calling one of its methods
Running out of memory
The On Error statement intercepts run-time errors and passes control to an error
handling routine.
Syntax
The On Error statement has the following syntax:
On Error GoTo label
Example
The following code for a button uses On Error to invoke an error handling routine
called errHandler when any run-time error occurs.
Sub click (Source As Button)
On Error GoTo errHandler
%Rem
other statements
%End Rem
errHandler:
' code to process error
Exit Sub
Describe the parts of the error handling routine (or error handler).
Explain that the Resume statement is one way to return from an error handling
routine.
Open Domino Designer Help to display more details about this statement.
An error handling routine is designed to resolve run-time errors. How the routine
handles the error can depend on the error and the application.
The following table describes the parts of an error handling routine.
Part Description
Statements to process the error LotusScript statement to process the error that
invoked the routine.
Statement to end the error handling Determines how the script exits or continues.
routine This statement can be one of the following:
Resume
Exit Function
Exit Sub
Statement Function
Resume 0 Continues executing at the statement that
caused the current error.
Resume Next Continues executing at the statement following
the one that caused the current error.
Resume label Continues executing at the specified label.
Describe the functions available to identify the error that Domino trapped.
Domino Designer Help contains the run-time error messages.
The following is an example of an error handling routine that simply informs the
user that an error has occurred and continues executing the script.
ErrHandler:
Messagebox "An error has occurred."
Resume Next
Inside an error handling routine, you can identify what error has occurred using
built-in LotusScript functions. These functions return standard messages and
numbers describing the error.
The following table describes the functions that identify the error.
Part Function
Err Returns a number identifying the current error
Erl Returns the line number in the script source
code that caused the current error.
Error$ Returns a text message describing the current
error.
Note: Once a Resume statement executes, the error information is cleared and
these functions will return nothing until the next error occurs.
Error constants
List benefits of using the error constants rather than the integer values they
represent.
Error constants
Domino specifies standard error numbers as constants. The following table lists
some error constants and the errors they represent.
Domino specifies standard error constants in the LSERR.LSS file. This file defines
names for the error codes LotusScript uses to identify all of the run-time errors
that can occur.
Programmers should use the constants to refer to the errors instead of the actual
number for the following reasons:
Your code is easier to read, since the names of the constants are more
descriptive than the numbers.
Your code will be unaffected if Lotus must change the error values.
To use the constants to identify errors, include the file in a script that loads before
the other scripts in the application.
To include the error constants, enter the following statement in the (Options) event
of a scriptable object:
%Include "lserr.lss"
You can write code that traps for a specific error to occur. If that error occurs, it is
routed to a special error handling routine.
You can trap specific errors using the predefined constants and direct them to
particular error handling routines.
Syntax
Use the following syntax to invoke a particular error handling routine for a specific
error.
On Error errorConstant GoTo label
Example
The following code will invoke the noFileFound error handling routine if the
database file name does not exist on the server. If the script cannot open the
database for another reason, it will invoke the openFailed error handling routine.
(Options)
%Include "lserr.lss"
(Click)
Sub click (Source As Button)
On Error ErrFileNotFound GoTo noFileFound
On Error ErrOpenFailed GoTo openFailed
'other statements
Call db.Open ("","discuss.nsf")
'other statements
' there were no errors so exit the sub
Exit Sub
noFileFound:
' error handling routine for not finding the file
Messagebox "Could not find database file."
Resume Next
openFailed:
' error handling routine for failing to open the database
Messagebox "Could not open database file."
Resume Next
' finished subroutine
Exit Sub
You can create your own constants to represent errors that may occur in the
application. You can set up conditions that trigger the errors and invoke error
handling routines.
You can define your own error constants and messages to use in your scripts.
Declare a constant to represent the error condition.
CONST OutOfRange = 99037
Use the Error statement to signal the occurrence of the error.
If <error condition> Then
Error OutOfRange, "Number out of range"
End if
You process your errors just as you process those that Domino recognizes by
default. The following code defines an OutOfRange error and invokes the
errorRange routine to process it.
'Define a constant
CONST OutOfRange = 99037
'Trap the error
On Error OutOfRange
'If the error condition occurs, trigger the error
If <error condition> Then
Error OutOfRange, "Number out of range"
End If
The following table shows the declaration statement for different variable
descriptions.
Step Action
2 Add the following code to the click event of the new button to create a copy of
the Inventory database on your local machine:
'dim object reference variables
' sdb is the source database,
' tdb is the target database
Dim sdb As NotesDatabase
Dim tdb As NotesDatabase
'point sdb to source db on server
'replace ?? with name of server, if necessary
Set sdb=New NotesDatabase("??","Inventory.nsf")
'create tdb from sdb
Set tdb = sdb.CreateCopy ("","NewInventory.nsf")
3 Add the following code to change the title of the new database to Inventory:
'change title
tdb.Title="NewInventory"
4 Add the following code to display a message box stating that the database
has been copied and the name has been changed:
'display new title
Messagebox "The new title is " & tdb.Title
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 3
Preview
A pp en di x A E xerc is e S ol ut i on s
In this exercise, use LotusScript and the Domino objects to retrieve the access
level to a database on the instructor’s server and display it in a message box.
Step Action
1 Create a button on the ACL Entry Exercise form in the Demos and Activities
database. Name the button Get Access to DB on Server.
Step Action
4 Add the following code to use a select case statement to set a display string
to a text value representing the ACL level:
'declare string
Dim dispstring As String
'get acl level
Select Case dbaclentry.level
Case ACLLEVEL_NOACCESS
Dispstring="No Access"
Case ACLLEVEL_DEPOSITOR
Dispstring="Depositor"
Case ACLLEVEL_READER
Dispstring="Reader"
Case ACLLEVEL_AUTHOR
Dispstring="Author"
Case ACLLEVEL_EDITOR
Dispstring="Editor"
Case ACLLEVEL_DESIGNER
Dispstring="Designer"
Case ACLLEVEL_MANAGER
Dispstring="Manager"
End Select
5 Add the following code to display the name of the ACL entry and the access
level with a message box:
Messagebox "The level of access for " & _
dbaclentry.name & " is " & dispstring
6 Test the code by previewing the form in Notes and clicking Get Access to
DB on Server. Open the ACL of the database and verify the access level
your script retrieved.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 5
Preview
A pp en di x A E xerc is e S ol ut i on s
In this exercise, add a button to prompt users for information using the Prompt
method of the NotesUIWorkspace class.
Step Action
1 Create a new button on the Course form in the Inventory database. Name
the button Request Course Description.
2 Add the following code to the Request Course Description button on the
course form:
'This button allows users to request
' a course description
'get workspace object
Dim w As NotesUIWorkspace
Set w=New NotesUIWorkspace
'create a variable to store the prompt
Dim promptresults As Integer
'display initial prompt to user and capture result
promptresults = w.prompt (PROMPT_YESNOCANCEL ,"Mail", _
"Click Yes to send your request via mail, " & _
"No to send your request via email, " & _
"Cancel to cancel this request")
4 Save the form and test the Request Course Description button.
In this exercise, add code to the Inventory database that displays a message to
the users, thanking them for signing up for a particular course. The message
should use the current user’s name and the course name from the current
document.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 7
Preview
A pp en di x A E xerc is e S ol ut i on s
Step Action
1 In the Inventory database (not the copy you created in an earlier exercise),
open the Student form.
4 Open one of the course documents from the Course Summary view and
click Add a student. Enter values and save the document.
In this exercise, create an action for the Course Summary view in the Inventory
database that generates a report identifying the number of students currently
registered for a course.
Step Action
1 In the Course Summary view, each student is listed as a child to the course
name. To determine the number of students currently registered for a course,
use the ChildCount property of the NotesViewEntry class.
3 Add the following code to the action to retrieve the number of children for the
Ceramics view entry:
'We are accessing a document in the same
' database the script lies.
' get the session, and current database.
Dim s As NotesSession
Set s = New NotesSession
Dim db As NotesDatabase
Set db = s.CurrentDatabase
'locate the view to get the document, CS
Dim v As NotesView
Set v = db.GetView("CS")
'get the viewentry representing a course
Dim ventry As notesviewentry
Set ventry=v.getentrybykey("Ceramics")
'get the number of children
Dim count As Integer
count=ventry.childcount
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 9
Preview
A pp en di x A E xerc is e S ol ut i on s
Step Action
4 Add the following code to the action to create a new document that can be
displayed through the Report form:
'create document
Dim doc As notesdocument
Set doc=db.createdocument
'add form field
doc.form="R"
5 Add the following code to add the course name, number of students, and
user name to the document, and save it:
'add other fields
doc.ReportCourse = "Ceramics"
doc.ReportNumStudents = count
'save document
doc.save True,True
6 Add the following code to update the view to display the new report
document:
'refresh back-end view
v.Refresh
'update the front-end view
Dim w As NotesUIWorkspace
Set w = New NotesUIWorkspace
Call w.ViewRefresh
7 Save the view and preview it in the Notes client. Click the Count Students
action to test it.
Challenge
To build an action in the Course Summary view that creates a report for the
course representing the document that is currently selected in the view, use the
following code:
'We are accessing a document in the same database
' the script lies.
'Therefore, get the session and the current database.
Dim s As NotesSession
Set s = New NotesSession
Dim db As NotesDatabase
Set db = s.CurrentDatabase
' get the workspace and ui view
Dim w As NotesUIWorkspace
Set w = New NotesUIWorkspace
Dim uiv As NotesUIView
Set uiv = w.CurrentView
'create document
Dim doc As NotesDocument
Set doc = db.CreateDocument
'add form field
doc.Form = "R"
'add other fields
doc.ReportCourse = currentCategory
doc.ReportNumStudents = count
'save document
call doc.save (True,True)
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 11
Preview
A pp en di x A E xerc is e S ol ut i on s
This exercise modifies the code on the Course form in the Inventory database so
that the front-end document and back-end document are instantiated when the
form loads, and are available to all the buttons on the form.
The Count Students and List Students buttons use the variable uidoc to
reference the current document displayed in Notes and the back-end document
related to the current document.
Follow these steps to declare the common object variables doc and uidoc so
that they are accessible to the entire form.
Step Action
1 Select the Count Students button on the Course form of the Inventory
database.
3 Choose EditÆCut.
5 Select the following statement in the Click event of the Count Students
button on the Course form:
Set doc=uidoc.document
6 Choose EditÆCut.
8 Select the List Students button and delete the following two statements from
the Click event:
Dim uidoc as NotesUIDocument
Dim doc As NotesDocument
Step Action
2 In the Notes client, open a course document from the Course Summary
view.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s A 13
Preview
A pp en di x A E xerc is e S ol ut i on s
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s B 3
Preview
A pp en di x B E xam Co mpe t enc ie s
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s B 5
Preview
A pp en di x B E xam Co mpe t enc ie s
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s B 7
Preview
A pp en di x B E xam Co mpe t enc ie s
This section includes the relevant information about the standard curriculum
development learning processes and icons. Use this section as a tool to prepare
to deliver the course successfully.
Note: The terms instructional unit and unit are used to refer to general units of
instruction, including modules, lessons, topics, activities, and so on.
Learning processes are the basic instructional strategies that the instructor uses
to encourage students to achieve learning objectives. Presentation, Discussion,
Demonstration, Guided Practice, and other delivery strategies provide the means
for facilitating instruction and skills acquisition. A unique icon indicates the
recommended learning process and displays next to the learning process
instruction.
For the learning processes that follow, you will see:
A summary description
The appropriate icon
A table indicating what the instructor and students will see in their guides
Teaching tips
Note: Not all the learning processes are used in every course.
What is e-learning?
Assessment
Teaching tips
9 Clearly state the purpose of the assessment (for example, to provide self-assessment,
assess prior knowledge, or calculate course grade).
9 When applicable, provide information on the organization's policies regarding grading
and privacy of information.
9 When delivering an e-learning question, allow for transmission time before tallying
answers.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 3
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Case Study
Teaching tips
9 Follow the recommended timing for the case study, but modify accordingly based on
the students’ expertise.
9 Lead a discussion on a recommended solution.
9 Discuss the solution(s) and, as a group, list the advantages and disadvantages of the
suggested alternatives.
Demonstration
Demonstration database
For some offerings, a Demonstration database is included on the Classroom
Tools media. Sample Demonstrations are pre-built for the instructor to use.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 5
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Teaching tips
Discussion
Teaching tips
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 7
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Exercise
Teaching tips
9 Refer to any special preparation students must complete, or issues they may
encounter during the Exercise.
9 Remain available during the Exercise and be prepared to answer students' questions.
9 Review the Exercise solution in Appendix A: Exercise Solutions at the end of the
exercise.
9 Make group assignments clear and achievable.
9 For e-learning delivery that uses the Breakout Session tools, schedule the session as
a final class activity, one that does not require students to return to the main live
session. This simplifies the navigation that students need to complete.
9 For e-learning delivery where students have little or no experience with Breakout
Session tools, assign a teaching assistant to initiate the session and facilitate the
group’s work.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 9
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Guided Practice
Teaching tips
Presentation
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 11
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Teaching tip
Procedure
Teaching tips
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 13
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Review
A Review is used to reiterate main concepts and can be used to gain feedback,
assess learning, review critical material, or transition from one instructional unit to
another.
A Review may be used to:
Review the results of a Guided Practice, Case Study, or Exercise.
Seek feedback on the pace or level of instruction.
Provide self-assessment.
Present assessments that can be stored and graded in e-learning delivery.
Reinforce content.
The following table lists the supporting information that may be included in the
Instructor and Student Guides for this learning process.
Teaching tips
This section includes the relevant information about the standard curriculum
development conventions and icons. Use this section as a tool to prepare to
deliver the course successfully.
Conventions are rules that govern how to display specific types of information.
The following are standard curriculum development conventions and icons that
may be used within this courseware.
Note: Notes appear in the Instructor Guide and Student Guide and can be used to
note differences in content.
Notes for the Instructor: Special notes the course developer wants to
communicate to the instructor regarding delivery, classroom strategy, classroom
tools, exceptions, and other special considerations.
Tip: Tips provide additional guidance, or a hint, for students about a topic or task.
U s i ng Lo tu s S c r ip t i n I B M L o tu s D o m in o A p pl i c a t i on s C 15
Preview
A pp en di x C Le arn in g Pro cess es an d Instr ucto r Gu id e Co nve ntion s
Lotus software
IBM Software Group
One Rogers Street
Cambridge, MA 02142