【Lotus】操纵Profile文档的二种方法

 

1.   What are Profile Documents?

 

Profile documents provide a quick, easy and efficient way of storing and retrieving data shared by all users of a database and for data stored for each individual user. Profile documents can be considered just like any other database documents with the following exceptions:

• They will not display in any of the database views
• They will not be reflected in the database document count
• They must be created and edited using either LotusScript or @Functions

 

2.    Creating and Editing Profile Documents Using LotusScript

 

You can create and access profile documents using the NotesDatabase GetProfileDocument method. This method has one required argument and one optional argument. The required argument is the name you wish to call this particular profile document. The second optional argument will assign a particular user to this profile document. Using the second argument is necessary only if you wish to create a separate profile document for every user of the database. Below are sample scripts which create, modify, and retrieve data from profile documents.

 

Creating a Profile Document

 

The following script will create a new profile document in the database in which the agent is run. The profile document will be named "Profile Doc 1." If this profile document already exists in the database, the script will get a handle to the existing document.

 

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

 

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument(“Profile Doc 1”)

 

Call doc.save(False, False)

 

Writing to an Existing Profile Document

 

The following script will get a handle to the "Profile Doc 1" profile document, retrieve the value of the field "counter", add one to this value, write the new value back to the document, and save it.

 

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim count As Integer

 

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument(“Profile Doc 1”)

Count = cint(doc.count(0))

Count = Count + 1

Doc.count = Count

Call doc.save(False, False)

 

Deleting a profile document

 

The following script will delete the "Profile Doc 1" profile document.

 

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

 

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument(“Profile Doc 1”)

Call doc.Remove(0)

 

Retrieving Data from a Profile Document

 

The following script will get a handle to the "Profile Doc 1" profile document, retrieve the value of the field "counter" and display it in a messagebox.

 

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim count As Integer

 

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument(“Profile Doc 1”)

Count = cint(doc.count(0))

 

MessageBox Count

 

Editing an Existing Profile Document in the User Interface

 

Each form in a database can have one profile document associated with it. The following script will either create or edit the profile document associated with the "Profile" form. Before running this, you must create a form named "Profile."

 

Dim workspace As New NotesUIWorkspace

Call workspace.EditProfile(“Profile”)

 

If you do use the second username argument in this method, it will display the profile document for the particular user.

 

Dim workspace As New NotesUIWorkspace

Dim session As New NotesSession

Call workspace.EditProfile(“Profile”, session.username)

 

Determining if a NotesDocument Object is a Profile Document

 

The following script will display True or False depending upon whether the NotesDocument object 'doc' is a profile document.

 

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

 

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument(“Profile Doc 1”)

 

MessageBox doc.IsProfile

 

3.    Creating and Editing Profile Documents Using @Functions

 

You can create and edit profile documents using @Command ([EditProfile]) or @SetProfileField. You can retrieve values from an existing profile document using @GetProfileField. The syntax for the @Command is:

 

@Command ([EditProfile]; formname; username)

 

• The formname parameter is required and must be the name of a form that exists in the database.
• The optional username parameter is used to create a user-specific profile document. The username argument is necessary only if you wish to create a separate profile document for every user of the database.

 

You can think of a profile document created without a username as a profile document for the entire database that can be used by everybody. Conversely, profiles created with the username parameter associate the profile document with an individual user to set and retrieve user-specific information.

Below are sample @Commands and @Functions which create, modify, and retrieve data from profile documents.

 

Example A

 

Create the Form

 

First, design a form, save it, and call it "Beeper Carrier Info". Uncheck the options for "Include in menu" and "Search Builder". (Documents composed via the menu create a document like any other document in the database that is not hidden from views, thereby defeating the purpose of profile documents).

 

Create/Edit Profile with @Command

 

@Command ([EditProfile]; "Beeper Carrier Info")

 

If the Profile, "Beeper Carrier Info" is not found, this @Command will create a new one. If it is found, it will place the existing one into Edit mode. You can then fill in the value just like you would when composing any other document.

 

Create Profile/Set Field Values with @Function

 

@SetProfileField ("Beeper Carrier Info"; "Carrier"; "Joe Lotus")

 

If the Profile, "Beeper Carrier Info" is not found, this @function will create a new one and set the field "Carrier" to the value "Joe Lotus". If it is found, it will simply set the field "Carrier" to the value "Joe Lotus".

 

After the "Beeper Carrier Info" profile document is created, you can then use the @GetProfileField function to retrieve values from the profile document as follows:

 

Retrieve Value

 

a:=@GetProfileField("Beeper Carrier Info";"Carrier");

@Prompt([OK];"Current Beeper Carrier";a)

 

The above formula will retrieve the value from the "Carrier" field and display it in a @Prompt dialog box.

 

Example B

 

A good use for profile documents might be to store user-specific information such as name, extension, and location. Assuming you have created a form called "User Information" with these 3 text fields, here are some ways to set and retrieve the values:

 

Create/Edit Profile with @Command

 

@Command([EditProfile]; "User Information"; @Username)

 

If the Profile, "User Information" is not found for the current user, this @Command will create a new one. If it is found, it will place the existing one into Edit mode. This profile will be associated with the current user since @Username was used as the second parameter. You can then fill in the value just like you would when composing any other document.

 

Create Profile/Set Field Values with @Function

 

@SetProfileField("User Information"; "Extension"; "5555"; @UserName)

 

If the Profile, "User Information" is not found for the current user, this @function will create a new one and set the field "Extension" to the value "5555". If it is found, it will simply set the field "Extension" to the value "5555". This profile will be associated with the current user since @Username was used as the fourth parameter.

 

Retrieve Value

 

a:=@GetProfileField("User Information";"Extension"; @UserName);

@Prompt([OK];"Extension";a)

 

The above formula will retrieve the value from the "Extension" field from the profile document associated with the current user, and display it in a @Prompt dialog box.

 

Note: There is no @Command or @Function to delete profile documents. It is usually unnecessary to delete an existing profile document since you can simply edit the existing one and change the values. If it is determined there is a need to delete it, you can use LotusScript to delete it.

 

4.    Access Rights and Profile Documents

 

In order to create a profile document with @SetProfileField or @Command([EditProfile]), you must have at least Author access with Create document rights in the Access Control List (ACL) of the database.

In order to edit profile documents, including your own profile, using @Command([EditProfile]), you must have at least Editor access or Author access in the ACL plus inclusion in an Author field. You do not need Create document rights to edit documents.

In order to edit a profile document using @SetProfileField, you need only Author access. It is not necessary for you to have edit rights. You do not need Create document rights to edit documents.

Trivia pertaining to fields in a layout region: If you have Reader access in the ACL it appears you can edit fields in a layout region but, on trying to save, a "You are not authorized...." error occurs. If you have author but not edit rights, you will not be able to move the cursor at all in a field in a layout region. In a document with fields not in a layout region, of course, you will not even be able to place the document in Edit mode.

 

5.    Supporting Information

 

From the On-line help:

You can access profile documents quickly and use them to store information that you don't want in user documents and to share information across scripts within a database.

Only one profile of a given form can exist per database per person. If you create a profile without a user name, Notes assumes it's the only profile document of that form in the database. You need at least author access to create a profile that applies to an entire database.

Documents saved with EditProfile are hidden.

 

Original URL