[Formelsprache] Verbergen-Wenn (Hide-When) - Formeln

[TMC]

Autor(en):             Matthias TMC
Stand:                   07.10.2004
Version:                 1.1
Notes-Versionen:    5.x, 6.x, 7.x


0. Inhalt

1. Grundsätzliches
    1.1 Einführung
    1.2 Absätze (Paragraphen)
    1.3 Das Eigenschaftsfenster
    1.4 Der Rückgabewert von Verbergen-Wenn-Formeln
2. Aufbau von Verbergen-Wenn-Formeln
    2.1 Und / Oder - Beziehungen
        2.1.1 Und-Beziehung
        2.1.2 Oder-Beziehung
    2.2 Klammern
    2.3 Zeigen-Wenn anstatt Verbergen-Wenn
    2.4 Unnötige Teile vermeiden
        2.4.1 @If
        2.4.2 Listentrennzeichen verwenden
    2.5 Richtextfelder
        2.5.1 Sich immer eine Hintertür offen halten
        2.5.2 Verbergen-Wenn's von Anwendern
        2.5.3 Verbergen-Wenn-Formeln per Tool entfernen

3. Bekannte Bugs in Zusammenhang mit Verbergen-Wenn-Formeln
    3.1 Tabellen
4. Tipps zur Fehlersuche
    4.1 Fehlervermeidung und Fehlersuche in umfangreichen Verbergen-Wenn-Formeln
    4.2 Zeigen-Wenn
    4.3 Sich die Formel selber vorsagen
5. Weitere Beispiele für Verbergen-Wenn-Formeln
6. Aktualisierung von Verbergen-Wenn-Formeln
    6.1 Aktualisierung bei Feldänderung - Refresh fields on keyword change:
    6.2 Programmatische Aktualisierung


1. Grundsätzliches

1.1 Einführung

Der Auslöser dieses AtNotes Best Practices - Artikel war folgender Weblog-Artikel von Ben Langhinrichs (http://www.geniisoft.com): Writing better hide-when formulas


Verbergen-Wenn - Formeln (auch "Hide-when Formulas" genannt), dienen dazu, um
   - Paragraphen (dt. "Absatz") in Dokumenten
   - Schaltflächensymbole (auch "Action Buttons" genannt) in Dokumenten und Ansichten
   - Abschnitte
   - Layout-Bereiche
   - Gliederungseinträge
   - eingebettete Gliederungseinträge
zu verbergen, wenn eine oder mehrere Bedingungen zutreffen.


1.2 Absätze (Paragraphen)

Wie bereits in Kap. 1.1 erwähnt, gelten Verbergen-Wenn-Formeln in Dokumenten für ganze Absätze (Absatz = "Paragraph").
Dabei gilt es zu beachten, dass eine Tabellenzelle mit einem Absatz beginnt, daher gilt dies auch für Tabellenzellen. Allerdings kann eine Zelle mehrere Absätze haben (getrennt via Zeilenumbruch).
Weitere (englischsprachige) Informationen zu Absätze siehe: Ben Langhinrichs: Rich Text 101 - Paragraphs


1.3 Das Eigenschaftsfenster

Verbergen-Wenn-Formeln werden im Eigenschaften-Fenster des des entsprechenden Objektes auf der Karteikarte "Paragraph Hide When" gesetzt:
   

In diesem Beispiel wird der Absatz verborgen, wenn das Dokument zum Bearbeiten geöffnet ist (direkt oder per Voransicht ('Previewed') oder das Dokument neu ist, also noch nie gespeichert wurde (@IsNewDoc ergibt @True, wenn Dokument neu).
Das heißt, dass hier eine "Oder-Beziehung" zwischen den Verbergen-Wenn-Optionen (unter 'Hide paragraph when document is") und der Verbergen-Wenn - Formel besteht.
Will man stattdessen den Absatz verbergen, wenn das Dokument sowohl im Editmodus ist und gleichzeitig neu ist (also "Und-Beziehung"), so deaktiviert man alle Eigenschaften und schreibt als Formel in das Formelfenster: @IsNewDoc & @IsDocBeingEdited.


1.4 Der Rückgabewert von Verbergen-Wenn-Formeln

Der Rückgabewert von Verbergen-Wenn-Formeln muss immer Wahr oder Falsch sein, also @True (bzw. @Yes) oder @False (bzw. @No).
Dies bedeutet, dass Verbergen-Wenn-Formeln immer Bedingungen enthalten müssen, die True oder False zurückgeben.

Ein vorangestelltes Ausrufezeichen (!) stellt, wie überall in der Formelsprache, den Rückgabewert ins gegensätzliche, dadurch wird aus dem Rückgabewert @True ein @False (und umgekehrt).

Beispiel:
@IsNewDoc gibt @True zurück, wenn das Dokument neu ist. Will man allerdings ein @False haben wenn das Dokument neu ist (also z.B. einen Absatz nicht mehr anzeigen, wenn das Dokument nicht mehr neu ist), so kann man folgende Formel einsetzen: !@IsNewDoc (dadurch wird @False zurückgegeben).

Siehe auch: Kap. 2.3 (Zeigen-Wenn anstatt Verbergen-Wenn).


2. Aufbau von Verbergen-Wenn-Formeln


2.1 Und / Oder - Beziehungen

Werden mehr als 1 Bedingung in Verbergen-Wenn-Formeln verwendet, so verbindet man diese mit einer Und / Oder - Beziehung:

2.1.1 Und-Beziehung

Sollen von 2 Bedingungen beide Bedingungen gleichzeitig erfüllt sein, damit die Verbergen-Wenn-Formel @True zurückgibt, so verwendet man eine Und-Beziehung.

Dazu verwendet man "&" ("Ampersand", auch bekannt als "kaufmännisches Und").

Beispiel: Wenn sowohl der Status = "In Bearbeitung" sein muss und gleichzeitig der Titel = "" sein muss, um das entsprechende Objekt zu verbergen, so verwendet man:
Status = "In Bearbeitung" & Titel = ""

2.1.2 Oder-Beziehung

Reicht es, wenn von 2 Bedingungen nur 1 Bedingung erfüllt ist, so verwendet man eine Oder-Beziehung.

Dazu verwendet man "|" (Pipe-Symbol).

Beispiel: Wenn das entsprechende Objekt nur verborgen werden soll, wenn entweder der Status = "In Bearbeitung" ist oder der Titel = "" dann verwendet man:
Status = "In Bearbeitung" | Titel = ""

2.2 Klammern

Für die logische Trennung mehrerer Bedingungen verwendet man Klammern, um die "Und" bzw. "Oder" - Teile zu trennen.
Soll zum Beispiel ein Absatz verborgen werden, wenn entweder der Status = "Offen" ist und gleichzeitig das Feld Kategorie = "R4" ist, oder aber - davon unabhängig - das Dokument neu ist, so verwendet man folgende Formel:
(Status = "Offen" & Kategorie = "R4") | @IsNewDoc

WICHTIG: Man sollte aktiv von den Klammern Gebrauch machen, nicht nur um Transparenz in die Verbergen-Wenn-Formeln zu bringen (und dadurch Missverständnisse vermeiden), sondern auch um Fehler auszuschließen.

Beispiel:
Status = "Abgelehnt" | Typ = 3 & @IsDocBeingEdited.

Hier könnte man folgendes darunter verstehen, wobei dadurch jeweils unterschiedliche Rückgaben erzielt werden:
a) (Status = "Abgelehnt" | Typ = 3) & @IsDocBeingEdited
b) Status = "Abgelehnt" | (Typ = 3 & @IsDocBeingEdited)


2.3 Zeigen-Wenn anstatt Verbergen-Wenn

Viele Missverständnisse treten dadurch auf, dass man wohl unterbewusst in "Zeigen-Wenn" anstatt "Verbergen-Wenn" denkt beim Erstellen von Verbergen-Wenn-Formeln.

Hier kann man sich aber einfach behelfen, indem man die komplette Formel einklammert und ein Ausrufezeichen (siehe Kap. 1.4) davor stellt:
!(Status = "In Bearbeitung" | @IsDocBeingEdited)

Das kann man noch leicht abwandeln, in dem man die Bedingung in eine Variable setzt, und die Variable dann mit einem vorangestellten Ausrufezeichen aufruft:
_Show := (@IsNewDoc | @IsDocBeingEdited)
!_Show

Eine erweiterte Möglichkeit, um die Logik und Lesbarkeit von Verbergen-Wenn - Formeln zu verbessern, ist die Verwendung von speziellen Variablen:
_anzeigen := @False;
_verbergen := @True;
@If(
   Bedingung1; _anzeigen;
   Bedingung2; _anzeigen;
   Bedingung3; _anzeigen;
   _verbergen
)
Dadurch sieht man auf einen Blick, welche Bedingungen zum Anzeigen und welche zum Verbergen des Absatzes führen. Allerdings kann diese Vorgehensweise u.U. die Performance negativ beeinflussen.


2.4 Unnötige Teile vermeiden

2.4.1 @If

Wie oben erwähnt, erwartet Lotus Notes als Rückgabewert immer ein @True oder @False (bzw. @Yes / @No).

Ein @If kann man daher oftmals vermeiden.
Beispielsweise kann man die Formel @If(Status = "Offen"; @True; @False) ersetzen durch Status = "Offen".


2.4.2 Listen

Listentrennzeichen
Die Formelsprache bietet uns eine einfache Möglichkeit, um einen Wert auf verschiedene Inhalte abzufragen.
Dadurch kann man z.B. die Formel Status = "Offen" | Status = "Beantragt" | Status = "Abgelehnt" wie folgt vereinfachen: Status = "Offen" : "Beantragt" : "Abgelehnt"
Wir nutzen hierbei den Doppelpunkt (:) als Listentrennzeichen.

Schnittmenge zweier Listen
Um auf die Schnittmenge zweier Listen zu prüfen, kann man für Listen den Permutations-Operator "*=" verwenden - anstatt der Formelfunktion @Keywords.
Beispiel: !(@UserNamesList *= ErlaubteAutoren)
Dadurch wird geprüft, ob mindestens ein Eintrag der Rückgabe von @UserNamesList (Benutzernamen, Gruppen und Rollen des aktuellen Benutzers) im Feld "ErlaubteAutoren" enthalten ist. Falls mind. 1 Eintrag gefunden wird, gibt die Formel ein @False (aufgrund des vorangestellten "!", ansonsten @True) zurück und das Objekt, welches diese Verbergen-Wenn-Formel enthält, wird angezeigt.



2.5 Richtextfelder

2.5.1 Sich immer eine Hintertür offen halten

Grundsätzlich werden Verbergen-Wenn - Formeln in Masken an Richtextfeld-Inhalte direkt weitergegeben. Dabei kann man auch Designelemente, welche Verbergen-Wenn Formeln enthalten, immer im Designer-Client sehen. Bei Richtextfeld-Inhalten ist dies allerdings nicht der Fall !

Falls beispielsweise die Formel Kategorie = "R4" lautet, so sollte man diese in Kategorie = "R4" & (!@IsDocBeingEdited) umschreiben. Dadurch kann man den verborgenen Absatz sehen, wenn das Dokument bearbeitet wird.
Eine weitere Möglichkeit ist, eine spezielle Rolle in der ACL einzurichten; wenn diese Rolle gesetzt ist, kann man dann alle verborgenen Absätze sehen.

2.5.2 Verbergen-Wenn's von Anwendern

Weiter ist im Zusammenhang mit Richtextfeldern zu beachten, dass der Anwender eigene Verbergen-Wenn's erstellen und somit das Design der Maske aushebeln kann.
Workarounds gibt es dafür mehrere: Abschnitte oder berechnete Teilmasken sind Möglichkeiten, die man hier einsetzen kann.

2.5.3 Verbergen-Wenn-Formeln per Tool entfernen

IBM bietet ein Tool für Windows an, um Verbergen-Wenn-Formeln in Richtextfeldern wieder zu entfernen.
Details siehe: UNhideRT.exe - Utility to Clear Hide/when Formulas From Specific Rich Text Fields



3. Bekannte Bugs in Zusammenhang mit Verbergen-Wenn-Formeln

3.1 Tabellen

Gerade in früheren Notes/Domino - Versionen traten vermehrt Bugs in Tabellen mit Verbergen-Wenn-Formeln auf, dies oft bei umfangreichen Tabellen und im Zusammenhang mit Teilen/Verbinden von Zellen oder Einfügen von Zeilen oder Spalten.
Besonders vermehrt treten diese Erscheinungen auch auf, wenn die im Designer bearbeitete Maske gleichzeitig im Client ein Dokument in der gleichen Maske darstellte.

Tipps:
1.) Hide-when-Formeln in Tabellen nur bearbeiten, wenn im Client nicht die Entwicklungs-DB geöffnet ist.
2.) Vor Änderungen eine Kopie der Datenbank oder der Maske erstellen (dabei sollte die Kopie der Maske aber nicht in die selbe Datenbank eingefügt werden, um u.a. ein unnötiges Füllen der UNK zu vermeiden).


4. Tipps zur Fehlersuche

4.1 Fehlervermeidung und Fehlersuche in umfangreichen Verbergen-Wenn-Formeln

Wenn man längere Verbergen-Wenn - Formeln schreibt oder Fehler in den Verbergen-Wenn - Formeln beheben möchte, kann man die Formel in ein Feld, "berechnet zur Anzeige", setzen und in der Verbergen-Wenn-Formel auf dieses Feld verweisen.

Vorteile:
1.) man hat die Standard-Programmieroberfläche für die Formelsprache zur Verfügung
2.) man sieht das Ergebnis im entsprechenden Feld, dadurch kann man Fehler schneller erkennen.

Wenn die Funktionsfähigkeit der Verbergen-Wenn-Formel nachgewiesen wurde, kann dann dieses berechnete Feld selbst durch Ankreuzen der Checkboxen für "Verbergen in Notes" und / oder "Verbergen im Web" ausgeblendet werden.
Weiterer Vorteil: Nicht selten basiert das Verbergen-Wenn zahlreicher Felder auf der gleichen Formel. Befindet sich diese Formel in einem berechneten Feld, muss anschließend jeweils nur auf den Wert dieses Feldes verwiesen werden.


4.2 Zeigen-Wenn

Auch bei der Fehlersuche kann es sich bewähren, die Formel als "Zeigen-Wenn" anstatt Verbergen-Wenn darzustellen, siehe Kap. 2.3.


4.3 Sich die Formel selber vorsagen

Dies mag etwas ungewohnt klingen, aber manchem Programmierer hilft es gerade bei der Fehlersuche, sich die Formel selber vorzusagen.

Beispiel:
Angenommen man hat die Formel Status = "Abgelehnt" | Typ = 3. Nun kann man sich diese Formel selber vorsagen: "Verberge den Absatz, wenn Status ist "Abgelehnt" oder wenn der Typ = 3 ist".
Dadurch findet man unter Umständen heraus, dass man eigentlich wollte "Verberge den Absatz, wenn Status ist "Abgelehnt" und Typ ist 3" (was die Formel Status = "Abgelehnt" & Typ = 3 wäre).


5. Weitere Beispiele für Verbergen-Wenn-Formeln

Verbergen wenn das Dokument neu ist:
@IsNewDoc


Verbergen wenn das Dokument im Bearbeitungsmodus ist:
@IsDocBeingEdited


Verbergen für alle User mit Ausnahme der ACL - Rolle "Bearbeiter"
!(@IsMember ("[Bearbeiter]";@UserRoles))
Dadurch wird für alle User verborgen, wenn diese nicht die Rolle [Bearbeiter] haben.
Dabei gilt es zu beachten, dass Rollen lokal nur funktionieren, wenn in der ACL "Enforce a consistent Access Control List across all replicas" ausgewählt wurde.


Zeigen wenn Autor lt. Autorenfeld oder mindestens Editor lt. ACL:
_Access := @TextToNumber(@Subset(@UserAccess(@DbName); 1));
_Zeigen1 := _Access > 3;
_Zeigen2 := @UserNamesList *= Autorenfeld1 : Autorenfeld2;
!( _Zeigen1 | _Zeigen2)
Dadurch wird das Objekt nur angezeigt, wenn entweder der aktuelle User mindestens Editor lt. ACL ist, oder aber der aktuelle User in einem der angegebenen Felder (Autorenfeld1 oder Autorenfeld2) enthalten ist.


6. Aktualisierung von Verbergen-Wenn-Formeln

6.1 Aktualisierung bei Feldänderung - Refresh fields on keyword change:

Folgende Feldtypen bieten die Option "Refresh fields on keyword change" an:
  - Radio button
  - Dialog list
  - Checkbox
  - Listbox
  - Combobox

Eine Änderung dieser Felder bewirkt bei aktivierter Option "Refresh fields on keyword change" eine Aktualisierung der Objekte, in denen Verbergen-Wenn - Optionen und Formeln gesetzt sind. Ein unnötiges Setzen dieser Feld-Option sollte man allerdings aus Performancegründen vermeiden.


6.2 Programmatische Aktualisierung

Man kann auch programmatisch eine Aktualisierung der Verbergen-Wenn-Formeln und Optionen hervorrufen.

Dazu hat man sowohl in Formelsprache als auch in Lotus Script spezielle Befehle, um auschließlich die verborgenen Formeln eines Dokumentes zu aktualisieren, und nicht etwa eine Dokumentaktualisierung (entsprechend dem F9) durchzuführen, die u.a. auch die Eingabevalidierungen auslösen würde (was wir aber hier u.U. vermeiden möchten).

Formelsprache: @Command([RefreshHideFormulas])

Lotus Script: Die "RefreshHideFormulas" Methode der NotesUIDocument - Klasse:
Call notesUIDocument.RefreshHideFormulas