Tuesday, December 06, 2005

Lotus Notes - Computed Subforms and Web Query Open (WQO)

Two powerful aspects of the Notes environment are:
  1. Computed Subforms
    An entire region of a form can be turned on or off according to a value that is computed at runtime. The maintainability of an approach based on computed subforms stands head and shoulders above the use of paragraph by paragraph "hide-when" formulae.
  2. Web Query Open (WQO)
    A Domino-hosted form, viewed on the web, can be set to run a server-side agent when the form is loaded. In this way any information passed in the URL (using multiple occurrences of "&" followed by text) can become parameters to a server executed routine.

Unfortunately these two aspects do not work together - you cannot use a WQO agent to select a computed subform because the Domino server decides which subforms to use before a WQO agent is executed.

The very simple answer to this is to use formulae in the form being loaded to directly decode the contents of the Query_String field in order to decide on the subform. A "computed for display" Query_String field is required for any passing of URL parameters to the server.

It took me a while to realise this (blindingly obvious?) fact but once I had taken it on board I began to think of the maintenance issues and the effect of this approach on other Domino solutions I was using. The following approach needs to be read with that in mind.

URL Syntax Policy

There is no set policy for what comes after the action part (eg ?OpenForm) of the URL. This part of the URL will be consumed by server-side code that you provide. In my Domino applications I choose to make this part of the URL consist of a series of name/value pairs. For example:


is used to assign the value "hello" to a variable named "param1" and "goodbye" to a variable named "param2".

Any solution to the subform problem needs, for me, to be compatible with this policy for Query_String. In practice this type of URL can lead to the setting of values on a form through my SetFields agent which the WQO agent for many forms.

The Subforms field

My web computed subform solution begins with a Shared Field named "Subforms". This field can be included in any form and has the following settings:
  • Computed for display (ie not written to the document on the server)
  • Formula:
    @Middle(@Right (Query_String;"Subforms");1;"&")

    This simple formula locates, in Query_String everything to the right of "Subforms" and then skips (1;) the "&" for the value and reads to the next "&"
The effect of this is to set the value of the field named Subforms to the value passed in the URL.

Computing the subform

The formula for the computed subform needs to read from the Subforms field, take account of the possibility of multiple subforms (separated with a ",") and return the appropriate value. I use:
  • subformnum:=1;

    The subformnum variable is not strictly necessary but aids maintenance.
    The Subforms field (a string) is made into a list at the "," boundaries via @Explode.
    The inner call to @Subset extracts the first subformnum entries from that list.
    The outer call to @Subset extracts the last entry in that list (position parameter = -1)
That's all!