Genii Weblog

Show 'N Tell Thursday: Writing better hide-when formulas

Thu 23 Mar 2006, 11:29 AM



by Ben Langhinrichs
Show and Tell ThursdayThis is a repeat of one of my more popular tips (see here), but since people never see it until I point them to it, it probably deserves repeating:

It has always surprised me how many questions are raised in the various Notes/Domino forums about hide-when formulas.  No, I don't mean the (many) about hide-when formula bugs.  I mean the basic process of creating a hide-when formula that does what the user wants.  I think that part of the problem is that many non-developers have the need to create a hide-when formula on occasion, and that another part is that people think in terms of "Show When", not "Hide When".  In any case, I thought I would write a short primer about hide-when formulas to link to when people are confused.







Basic Rules for Hide-When formulas
  1. Hide-when formulas effect entire paragraphs (a table cell starts with a paragraph, so this is true in table cells as well, although a table cell may have multiple paragraphs.  See more on paragraphs).
  2. A hide-when formula should always either be a condition (e.g., Status = "Pending") or return a @Yes or @No (or @True or @False, which are equivalent).
  3. Multiple conditions should be combined with an ampersand, &, if all the conditions must be true in order to hide the paragraph, or with a vertical bar, |, if any one of the conditions must be true to hide the paragraph.  For example, if we should hide the paragraph when either Status is "Pending" or Override is "Denied", the formula should be Status = "Pending" | Override = "Denied".
  4. If you have mixed conditions, use parentheses to separate the "and" and "or" parts.  For example, if the paragraph should be hidden when either Status is "Pending" or Override is "Denied, but not when the document is being edited, the formula should be (Status = "Pending" | Override = "Denied") & !@IsDocBeingEdited.

Tips for Simpler Hide-When formulas
  1. Do not use an @If unless you really, really need to.  The formula @If(Status = "Pending"; @True; @False) should be simplified to Status = "Pending".
  2. Formula language allows you to check against a list of names at one time, so the formula Status = "Pending" | Status = "Denied" | Status = "Reviewed" should be simplified to Status = "Pending":"Denied":"Reviewed", with the colon between the items being a list separator.
  3. If it is very hard to describe the "hide when" condition, but easy to describe the "show when" condition, just put the "show when" condition in parentheses and use an exclamation mark, which means "not" in front.  Thus, if the paragraph should be shown (not hidden) when the Type is 1 or the document is being edited, you can use !(Type=1|@IsDocBeingEdited) instead of trying to figure out the inverse.
  4. Beware of mixed conditions.  If you have a formula which says Status = "Denied" | Type = 3 & @IsDocBeingEdited, how do you know whether the proper meaning is (Status = "Denied" | Type = 3) & @IsDocBeingEdited or Status = "Denied" | (Type = 3 & @IsDocBeingEdited), which have very different meanings.  If you assume the first interpretation, your paragraph may be hidden whenever you are in edit mode, but if you assume the second, it will only be hidden in edit mode when the Type is 3.
  5. Try "talking the formula".  If you have a formula which says Status = "Denied" | Type = 3, and you try to say it out loud as "Hide this paragraph if Status is "Denied" or Type is 3", you may catch that what you wanted was "Hide this paragraph if Status is "Denied" and Type is 3", which should be Status = "Denied" & Type = 3.

Special Tips for Hide-When formulas in rich text fields

While most people use hide-when formulas on forms, pages and subforms, they are also used in regular rich text fields.  Additionally, a rich text field on a form with a hide-when formula inherits that hide-when formula.  These tips are particularly useful for hide-when formulas in rich text fields and for hide-when formulas on forms which include rich text fields.

  1. Include a "back door".  A hide-when formula on a form includes an implicit assumption that you can always see the hidden paragraph when designing the form.  There is no such assumption with rich text fields.  If your formula would have been Donations = 0.0, make it Donations = 0.0 & (!@IsDocBeingEdited).  Then, you can still see the paragraph when editing.  Another option is to check a special role, so that when that role is set, you can see all hidden paragraphs.  If you don't do this, you may find hidden paragraphs that you can't ever find again.
  2. Be clear you are using hide-when formulas with users (or admin or somebody).  People don't expect hide-when formulas, and won't be very happy if they feel "fooled".

Tidbits from the Gold Forums

These are tips from others posting in the Gold Forums.  They offer different ideas and suggestions that might be useful.  I provide links back to the original post to allow reading the whole thread.

Bill Ernest 10.Feb.04 - Another way to use "show when" logic: 
I usually find it a lot easier to write them like this...

Show := @IsMember("{IT]";@UserRoles) | @IsMember("[VisSystemBoard]";@UserRoles);
!Show
Andre Guirard 05.Apr.04 - @ThisName doesn't work in hide-whens: 
The problem in this case is that the hide formula is not considered a formula of the field. There is no field context in which this formula executes. The hide formula applies to the text paragraph. In your case, perhaps there's nothing in the paragraph except one field. But there might be several fields and some text or other objects besides. In that case, to which field does @This... refer?

Warren Gamley 19.Feb.04 - Easy way to refresh hide formula from a button: 
I have a button that I need to click in order to display a hidden paragraph. I have it working so that when I click the button, I have to then click somewhere on the form before the paragraph is displayed. Is there a way to do it so that it appears immediately when the button is pressed?

... [Warren answers his own question] ...

I think I figured out a way.  Placing...

@Command([RefreshHideFormulas]);

... on the button seems to do the trick.

This post is likely to be a work in progress.  Any other tips or hints or strong suggestions about writing better hide-when formulas hide-when ?

Copyright © 2006 Genii Software Ltd.

What has been said:


447.1. Jackie Horowitz
(03/23/2006 01:27 PM)

My biggest hide-when rule of thumb for myself is *TRY* to avoid having a different hide-when for every cell of a table. If it is necessary, make sure to save often and actually close out the form design before starting again. At least with 6.5 and prior, designer seems to go haywire with too many hide-whens in a single table - often putting the hide-when for one cell into a different cell. But closing the form after every few formulas and re-opening seems to alleviate the problem.


447.2. Mikkel Heisterberg
(23-03-2006 14:13)

The concept of hide-when has been switched to show-when in the Workplace client. I guess IBM has been listening... :-)

/lekkim


447.3. Ben Langhinrichs
(03/23/2006 02:19 PM)

Mikkel - Really? I didn't know that. Thanks!