IBM®
Skip to main content
    Country/region select      Terms of use
 
 
   
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks  >  Lotus  >  Forums & community  >  Best Practice Makes Perfect

Best Practice Makes Perfect

A collaboration with Domino developers about how to do it and how to get it right in Domino

Since I've had to answer this question three times recently, I thought I would blog about it both because it seems to be something people are needing to do, and because that way I have something to send a link to, in future.

There are basically three ways to programatically make changes to design elements in LotusScript:

  • Use the methods and properties that are provided, e.g. NotesForm.FormUsers.
  • If the change you want to make is not supported that way, you can use DXL to export the design element, manipulate the DXL, then re-import it. As yet, this does not work with 100% reliability for all design elements, however, and still not all options are represented.
  • For some properties, you can access the design note with a NotesDocument object and change or delete items that store those properties.
It's the third technique I'm focusing on here.

The first step is to obtain the NotesDocument object representing the design element. If it's a folder or a view, this is how:

Dim db As NotesDatabase
Dim vu As NotesView
Set vu = db.GetView("viewname")
Dim docDesElem As NotesDocument

Set docDesElem = db.GetDocumentByUNID(vu.UniversalID)

If the design element isn't a Notes view, use a NotesNoteCollection to get the note ID. For instance, to locate the design note for an outline you might write:

Function GetOutlineNote(db As NotesDatabase, Byval outlineName$) As NotesDocument
        Dim nnc As NotesNoteCollection
      Set nnc = db.CreateNoteCollection(False)
      nnc.SelectOutlines = True
      nnc.SelectionFormula = {@lowercase($TITLE) = "} & Lcase(Replace(outlineName, Split({\,"}, {,}), Split({\\,\"}, {,}))) & {"}

       nnc.BuildCollection
      If nnc.Count <> 1 Then
              Error 31203, "Outline name " & outlineName & " matched " & nnc.Count & " outlines."
      Else

              Set GetOutlineNote db.GetDocumentByID(nnc.GetFirstNoteId)

      End If

End Function

Obviously, similar functions could be written for other types of design elements.

Once you have the NotesDocument representing the design element, you can mess with its items. For instance, the setting for whether a design element is protected from design refresh is the character "P" in the item $Flags. So if you wanted to unprotect design elements from refresh, you could do something like this:

flags = docDesElem.GetItemValue("$Flags")(0)
If Instr(flags, "P") Then
    docDesElem.ReplaceItemValue("$Flags", Replace(flags, "P", ""))
    docDesElem.Save True, False, True
End If

"How do we know to do that?" you might be wondering. One way is to download the C API toolkit from this website -- it includes a file stdnames.h, important parts of which are also copied here. This describes the purposes of all the $Flags values and some $FlagsExt values.

design element properties showing item valuesAnother way is to make the change you want manually, and compare the item values before and after to see what changed. From a view of design elements in Domino Designer press Alt+Enter or use menu File / Properties. Click the second tab to see a list of items in the design note.

Some items are of simple types -- number or text -- and you can replace their values as we did with $Flags above. Others, such as $AssistQuery in an agent, contain binary data which you'll be unable to decode from LotusScript -- but you can still delete the item, or replace it with a copy of an item from another design element of the same type (using CopyItemToDocument).

The other thing you must pay attention to, is whether the item you're modifying is signed. If it is, your modification will invalidate the signature of the design element, and you should re-sign it using the NotesDocument.Sign method before you save it. Otherwise Notes/Domino will refuse to use it. If you're not sure whether you're modifying a signed item, you can use the IsSigned property to check, or you can just sign the document anyway just in case (provided you're running your code with an ID that your users' ECL lists and so on will recognize).

In many cases, the design changes you make aren't noticed by the client until you exit and re-enter the application. The exception is outlines in version 8.0 and later -- there's a method to tell the client to reload these.

Have fun!

Andre Guirard | 7 May 2008 04:35:00 PM ET | | Comments (8)

Search this blog 

Disclaimer 

    About IBM Privacy Contact