Genii Weblog

Writing better hide-when formulas

Wed 7 Apr 2004, 06:23 PM



by Ben Langhinrichs
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 © 2004 Genii Software Ltd.

What has been said:


143.1. Richard Schwartz (04/07/2004 09:46 PM)

I've subscribed to your tip #3 for years. Ever since I helped Lotus QA the hide-when feature when it came out in R4. Whenever I have a compound condition, I use a see-when formula instead of a hide-when. Just surround the see-when formula with !( ... ), and you have your hide-when equivalent.

Another tip, by the way, goes hand-in-hand with your tip #4: parenthesize, parenthesize, parenthesize!

My own most important tip is that if you have a complex form with many hide-whens, make a fresh copy of the form before you make any changes to any hide-when, especially in table cells, and make a copy of the form before you ever do a split, merge, insert, or append of table rows or columns. They say that the long-standing bugs that we've all battled for years are fixed now, but I still don't trust it. Don't know that I ever will.

And finally: for debugging purposes, put your hide when (or see when!) formula in a computed field and simply reference that field value in the little hide-when formula property box. Make the field visible for debugging purposes.

-rich


143.2. Duffbert (04/08/2004 04:32 AM)

Very nice resource post, Ben.


143.3. Joe Litton (04/09/2004 06:58 PM)

On forms with many role-dependent hide/whens, put a hidden compute for display field at the top, with a catchy name like 'userRoles', and a value formula of @UserRoles. Then reference the field from the hide/whens.

This next one may not be the most CPU efficient, but for readability on complex hide/whens, I'll do something like:

show := @False;

hide := @True;

@If( ; show;

; show;

hide )

When there are multiple scenarios, this makes it much easier for the poor schmuck reading my code to understand the intended result.


143.4. Joe Litton (04/09/2004 07:00 PM)

Well that didn't work so well in my above example...I used some angle brackets and that stuff was stripped out. In the little sample, the idea is simply to list some condition, then the variable 'show' or 'hide' to make it easy to read.


143.5. Todd (06/09/2004 03:12 PM)

I'd like to hide the out of office action from /Students/Company, /Guests/Company, /Janitors/Company. How would I do this?


143.6. Sushant Upadhyay (03/30/2006 11:05 PM)

i think it's a good discussion but how can be solve my problem.we use a 80 rich text field in form.but when we open the document so some value in show the rich text and some value is not.means i have a single hide when for one field but hide when is working in line by line in the field.


143.7. Some Guy (05/07/2006 02:46)

For multiple hide/when's I reccommend the following construct or similar. It makes the code easier to read, and it's very easy to add additional 'hide/when' statements..

Design Library Documentation - Writing good hide when formulas.

FIELD MainProjectPhase:=MainProjectPhase;

FIELD Status:=Status;

eval:=@If(MainProjectPhase="Project Inception" & ProjectPlanningRequirements2="";"Yes";

@If(MainProjectPhase="Project Planning" & ProjectPlanningRequirements2="";"Yes";

@If(MainProjectPhase!="Project Planning";"Yes";

@If(MainProjectPhase="Project Planning" & cmpStatus="Pending Approval";"Yes";

@If(cmpStatus="Project Planning Signoff Complete";"Yes";

@If(Status="On Hold";"Yes";

@If(MainProjectPhase="Project Planning" & CmpStatus="RACI";"Yes";

@If(@IsResponseDoc;"Yes";

"No"))))))));

@If(eval="Yes")


143.8. Jose (04/26/2007 08:51 AM)

Has anyone tried executing @Eval on a hide-when formula?

Say that I programmatically set the hide-when formula in a field in the form

Field Button_hideWhen:="@False"

and in the hide-when I enter:

@Eval(Button_hideWhen)

I can't make this work. I am wondering if someone has anycomments?

Thanks Ben!


143.9. jose_zaldivar (04/26/2007 09:11 AM)

Never mind. It works quite fine I just have to say @True instead !!! :)

I am using this technique to programmatically show or hide several action buttons in a workflow process. Instead of having multiple buttons for for several actions in a workflow, I used 3 buttons are set as the worlflow advances:

with docCur

.Button01_LabelTX={Submit To Coordinator} ' Button Label

.Button01_HideWhenFormulaTX={@False' we are already in step 1 - alway show it

.Button01_ImageTX= imgLGLBActionDocumentSubmit} ' Image to show

.Button01_PrgNameTX={Submit To Coordinator}' Programatic name - for coding purposes

Then in the label formula I enter the corresponding field (i.e. Button01_LabelTX)

In the HidenWhen formula I enter:

@Eval(Button01_HideWhenFormulaTX)

finally in the action formula for that button. I enter something like this:

Call executeAction("Button01_PrgNameTX")

the subroutine "ExecuteAction" is then smart enough to deduct what the programmatic name of that field is. In this case "Submit To Coordinator" and then I can execute what ever code I need using a simple select case

Anyhow, fun stuff!

Jose


143.10. Neil (06/11/2007 11:50 PM)

Hi All,

Newbie here to Domino Designer - I have been asked to put together some Lotus Notes databases for our company, including a leave form.

In the leave form, I have placed a radio box with Leave Type options (eg. Medical leave, Carers leave etc.)

My issue is that I am trying to hide a radio box "Medical Certificate provided? Y/N" until a selection is made in the Leave Type radio box, of either MEDICAL leave or CARERS Leave.

I have set the "Hide paragraph when formula is true" on the Medical Certificate radio box, with the formula:

!@IsNewDoc | f1_LeaveType != "Medical Leave"

This works fine for NEW docs, and also displays the Medical Certificate radio box when MEDICAL Leave is selected. Question is however - how do I add this Medical Certificate radio box to show when CARERS Leave is chosen?

I have tried:

!@IsNewDoc | f1_LeaveType != "Medical Leave" | f1_LeaveType != "Carers Leave"


143.11. Ben Langhinrichs (06/12/2007 04:21 AM)

This is a perfect example of why one would use #2 and #3 above, and why #5 is important. When you use

!@IsNewDoc | f1_LeaveType != "Medical Leave" | f1_LeaveType != "Carers Leave"

you are saying "Hide this if it is not a new document or if f1_LeaveType does not equal 'Medical Leave' or if f1_LeaveType does not equal 'Carers Leave' " so what happens if f1_LeaveType is 'Carers Leave'? It still matches the part of the formula that says "if f1_LeaveType does not equal 'Medical Leave'" and you have used or, so the field will be hidden. Instead, rewrite the formula to group and to use a "show when formula":

!(@IsNewDoc | f1_LeaveType = "Medical Leave":"Carers Leave")


143.12. Neil (06/12/2007 07:05 PM)

Sorry - I didn't have my logic hat on yesterday - makes perfect sense. I have changed formula and works fine.

Appreciate your help, its been a bit dawnting coming from a MS Access background. Luckily I found this Blog - It's Blogs like this that really make the world a better place for self learning / teaching.

Thanks again,

Neil


143.13. pooja thakur (12/04/2008 10:11 PM)

In lotus notes how we implement

In the leave form,i have a combo box with Leave Type(Casual Leave,Short Leave,Special Leave,Earn Leave,Official Duty), I have placed a radio button with Full Day & Half Day & field name(ReqFor) and in Hald Day We have two Radio Button First Half and Second Half& field name(OdType2) ,I want to disable Full Day and Half Day Radio button in case of Short Leave onll,it will show only First Half & Second half..how?


143.14. Alisha (07/29/2010 12:19 PM)

Hi all,

we have one text field contain multiple names i.e alien,joy,vanisha.we used hide when formula in Field.but in my case hide when formula is working only for first value(first name). How can i solve this problem.