Every document and every design element in a Notes NSF or NTF file, is stored as a "note" -- a record containing header information (such as the Last Modified date-time) and "items" which have a name and value. For a document note, items usually correspond to fields on a form.
Notes views, by default, only display notes of the "data" or "document" class. This article describes how to programmatically modify a view to display design elements of specific types -- so you can, for instance, have a view that lists all your forms as if they were documents. You can either modify an existing view, or use this as the last step in creating the view programmatically. The example code is in LotusScript, but this can easily be done in Java also, the same way.
The basis of this technique is to change two attributes of the view: the selection formula (which is exposed in the Designer user interface as well as in the NotesView class) and the note class filter (which is not, but which you can access through code).
Locating the View
If you have a view name or alias that you want to use, and the name or alias is unique, use NotesDatabase.GetView to get the NotesView object for that view.
If there is no unique name or alias (as may occur if you're working with "server private on first use views", for instance, where there's a shared copy and a private copy of the design), you may need to iterate through the NotesDatabase.Views property to find the right one. This has performance implications -- see the article "Manipulating Design Elements..." in the Resources section for details.
Adjusting the Selection Formula
In general, you'll want to use the view to either display all design elements, or all of a specific type (e.g. all folders). Design element types are uniquely distinguished by the combination of their note class and the values in the $Flags and/or $FlagsExt items. You can't check the note class in a selection formula, but you can test the flags. You can also test other items, if you want to further restrict the selection, e.g. only list folders that are not hidden. See the article "Manipulating Design Elements..." in the Resources for information about other items you may want to test in your selection formula.
Decoding the values in $Flags to select just the design elements you want, may be complex. The file
stdnames.h from the Notes C API toolkit, contains definitions for the criteria the Notes client and Designer use to filter design elements of specific types; so you can use that as a guide. For a copy of this file, see the Resources section. Search for DFLAGPAT_ to find these constants in the file.
The criteria can change from version to version, as new design element types are added; the table below shows the basic tests as of version 8.5, for each type of design element. The table lists both note class and selection formula; the next section of this article shows how to select a note class.
Design Element Name | Note Class (hex) | Selection Formula (as of version 8.5) |
|
|
|
!@Matches($Flags; "*{UWy#i:|@Kgz}*")
|
|
|
|
!@Matches($Flags; "*{FG^}*")
|
|
|
|
|
|
|
|
!@Matches($Flags; "*{QXstmz{}*")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Script Library (excluding Web Service Consumers)
|
|
@Matches($Flags; "*{sh}*") & !@Contains($FlagsExt; "W")
|
|
|
|
|
|
|
|
@Contains($Flags; "g") & @Contains($Flags; "`")
|
|
|
|
|
|
|
|
|
|
|
|
@Contains($FlagsExt; "W") & @Matches($Flags; "*{sh}*")
|
|
|
|
|
|
|
|
@Contains($Flags; "g") & @Contains($Flags; "K")
|
|
|
|
@Contains($Flags; "g") & @Contains($Flags; ";")
|
|
|
|
@Contains($Flags; "g") & !@Matches($Flags; "*{~K[];`}*")
|
Hidden File Resource (created by XPage build)
|
|
@Contains($Flags; "g") & @Contains($Flags; "~") & !@Matches($Flags; "*{~K[];`}*")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note: If you're coding the above selection formulas as constants in your LotusScript code, you will have to put quotes around them. There are three kinds of quotes in LotusScript: doublequote ("), vertical bar (|) and {curly braces}. In general, you'll find it easiest to use as a quote character whatever of these is
not used in the formula itself, usually vertical bar. However, some of the formulas contain all of these characters, or you may just want to be consistent. In that case, use vertical bar and "escape" the vertical bar characters within the string by doubling them, e.g.:
view.SelectionFormula = |@Contains($Flags; "||")| ' select Composite Application design elements
If you want to further limit the selection, you can add clauses to the selection formula. So if you wanted a view of only non-hidden folders, you might write:
view.SelectionFormula = |@Contains($Flags; "F") & !@Begins($TITLE[1]; "(")| ' select non-hidden folders.
Adjusting the Note Class Filter
Setting the selection formula to the desired value, isn't enough to make the view display design elements; it would just display whatever regular documents matched the selection formula (probably, none). You must also update the "$FormulaClass" item of the view design note, which by default has the value "1" ("data" note class)
Wait, what?
Remember, the view design element is itself a note, and the items of that note contain all the information about the view design. If you open a design list in Domino Designer and look at the properties of design elements, you can see the values of their items. We're talking about accessing the design note's items directly -- through the NotesDocument object. The NotesView class doesn't contain a way to access that particular setting.
$FormulaClass contains a string which is the hexadecimal expression of the "logical or" of all the numbers of the note classes you want to include. Normally, you'll either choose just one, or all non-data notes ("7FFE").
One problem with using multiple note classes here, is that the selection formula must be correspondingly more complex to select the exact design elements you want; in some cases it may be impossible. For instance, if you wanted to list all Page design elements (Form class) plus the Help About and Using documents, and nothing else, the $FormulaClass value would be "106". But since there's no @Function to return the note class, you can't easily distinguish in your selection between a form (whose $Flags value might be "") and one of the help documents (whose $Flags generally are ""). You would have to look at other items in the design note to make the distinction (probably $TITLE, in this case).
By way of example, the whole process is shown in Listing 1, for the specific case of making a view of folders. Because the NotesView object updates the design note, and the NotesDocument object updates the same design note later, the routine deletes the NotesView object to avoid having incompatible copies of the same information. This may not be strictly necessary, but it seems safest.
Note: It's also possible to adjust the $FormulaClass using a toolbar button in Designer from a design list view, e.g.
FIELD $FormulaClass := "8"
Displaying Information about the Design Note in the view columns
So now you have a view containing design elements; what information do you show in the columns of the view to make a useful display for users?
The most useful information is probably the design element name and aliases, which are stored in the $TITLE field. You might also do some tests of the $Flags and $FlagsExt items to see whether they contain characters that indicate that the design element (let's say) is protected from design refresh, or is a private view, or whatever. The $Flags values documented in stdnames.h are helpful here, and so is the list of common $fields in the "Manipulating Design Elements" article (see References). That article also discusses how to find out what item names and values are used to store information for specific design element types.
You can use any of these item names in a view column formula as if they were regular document field names. For instance, to display the main title of the design element:
@Trim(@Subset(@Explode($TITLE; "|"); 1))
As with the view selection formula, the functions @Contains and @Matches are very helpful in finding out information about the design element from its $Flags values.
Note: Like all views, the formulas in a view of design elements may only refer to "summary" items. Use the Properties panel from a design element list view in Domino Designer, to determine which items have the SUMMARY flag set.
Note: In some versions of Notes, editing a view may reset the $FormulaClass item to its default value, "1". In that case, you would need to reapply the $FormulaClass fix.
Resources
The file
stdnames.h, part of the Notes C API toolkit, contains symbolic names for all the $Flags characters and many other special values used in design elements. You can download this toolkit from the
Lotus Downloads page of IBM developerWorks. The file
nsfnote.h in the same kit, defines constants for the different note classes, not all of which are mentioned here.
"Manipulating Design Elements" wiki article.
Sample Code
Listing 1: MakeViewListFolders subroutine
Sub MakeViewListFolders(view As NotesView)
' Change a view to list Folder design elements rather than documents.
' WARNING: the view object passed in will be deleted. If the caller needs
' it again they should re-fetch it by name.
Dim docDesElem As NotesDocument
Dim db As NotesDatabase
view.SelectionFormula = |@Contains($Flags; "F")|
Set db = view.Parent
Set docDesElem = db.GetDocumentByUNID(view.UniversalID)
Delete view
docDesElem.ReplaceItemValue "$FormulaClass", "8"
docDesElem.Sign
docDesElem.Save True, False, True
End Sub
|
|
10/29/2008 10:57 AMby Andre Guirard/Cambridge/IBM
|
|
|
10/30/2008 09:39 PM by Maureen Leland/Westford/IBM
|
Reviews: