APPLICATION DESIGN


Formula fields
Formula fields are used to populate a subscription list, which works in conjunction with the Headlines.nsf database. The Headlines database is used as the home page of an IBM® Lotus® Notes® client. The Headlines database includes a feature called subscriptions. Each database designer has the option enabling a database for subscriptions. When a user subscribes to a database (by choosing Create - Subscription), it triggers a server task that will notify the user whenever a document of interest is saved in that particular database. The criteria that the server looks for is contained in a formula field on the subscription form. Although users fill out the subscription form in the database they want to subscribe to, the subscription documents are stored in users' headlines databases (the default is headlines.nsf) on their local client.

If you want to create a custom subscription form for your database you can start with the default subscription form, named $Subscription, in the HEADLINES.NSF or HEADLINES.NTF database that is included with IBM® Lotus® Domino(TM) Designer. First copy and paste the form into your database, then customize it. When you customize a subscription form you must include the formula field. The formula field on the $Subscription form is named $HLFormula and is on the second tab of the tabbed table on the right side of the form. The $HLFormula field is a computed field. If you choose to keep the formula field computed, you write a formula that resolves to a selection formula for a subscription list. A formula field must resolve to a selection formula in order for the server to be able to retrieve the subscription criteria for the user.

Another option for the formula field is to choose Literalize fields on the Field Info tab of the Field Property box. When you select the Literalize fields option, you are programming the formula field to accept the formula you put in without compiling it. If you literalize a formula, the field references must be: text, text list, number, number list, date, date range, or date list. If the field referenced is of any other field type, it will be left out as a field reference.

The following is an example of a formula for a formula field for which Literalize is selected as an option:

Select (Names = ExampleNames) & (Numbers = ExampleNumbers) & (Categories = ExampleCategories)& (Dates = ExampleDates)

If the current document has these fields and values:
FieldValue
ExampleNames"CN=Sara Ryan/O=Acme" : "CN=Jack Town/O=Acme"
ExampleNumbers1: 2: 3
ExampleCategories"Arizona" : "Florida" : "New York"
ExampleDates[3/26/82]:[10/08/86]:[5/30/98]

Then the formula field will literalize to:

Select (Names = "Sara Ryan/Acme" : "Jack Town/Acme" ) & (Numbers = 1 : 2 : 3) & (Categories = "Arizona" : "Florida" : "New York") & (Dates=[3/26/82]:[10/08/86]:[5/30/98]

If you choose the computed option, the formula you enter must resolve to another formula. This provides the ability to optimize complicated formulas before they are saved. After the formula is evaluated, the resulting formula is saved.

If the resulting formula is invalid, the field is saved with a value of type error. In some cases, the user would never be able to exit out of the document. To differentiate between success and failure, you should test in the QuerySave event to determine if the Formula field is indeed a formula. If it is not, then the computation did not result in a valid formula.

For example, a computed formula field has the following formula:

tLitNames := "\"" + @Implode( ExampleNames; "\" : \"") + "\"";

tLitNumbers := @Implode( @Text(ExampleNumbers); " : ");

tLitCategories := "\"" + @Implode( ExampleCategories; "\" : \"") + "\"";

"Select (Names = " + tLitNames + ") & (Numbers = " + tLitNumbers + ") & (Categories = " + tLitCategories + ")"

If the current document has these fields and values:
FieldValue
ExampleNames"CN=Sara Ryan/O=Acme" : "CN=Jack Town/O=Acme"
ExampleNumbers1: 2: 3
ExampleCategories"Arizona" : "Florida" : "New York"
Then the formula will compile to:

Select (Names = "Sara Ryan/Acme" : "Jack Town/Acme" ) & (Numbers = 1 : 2 : 3) &(Categories = "Arizona" : "Florida" : "New York")

See Also