Domino Development - Back to Basics - Part 2: Forms and Documents

Continuing from Part 1 you now know that everything in Notes is stored in a Note. To further understand how Notes "ticks" some light needs to be shed on the relation between forms and documents.
In the simplest way to look at it, a form acts like the schema to be used to populate a document with values. The fields one fills into a form get stored as items into a document. This explanation is good enough for starters, but warrants a closer look to fully appreciate Notes' flexibility. In a RDBMS a record is "unbreakable" linked to the containing table by the database schema definition. Each record has each column defined in the schema. Notes ticks differently. The link between a form and a document is established by a Notes item with the reserved name "Form". When you open a form, fill it in and save it, automatically a item with the name of the form gets created. When that document gets opened, it will pull that form for display.
That link is not static: it can be overwritten in many ways:

• In the Notes client using View - Switch Form ...
• Though a field with the name form containing a formula
• Code in an event
• Code in an agent
• A form formula in a view
• A Smart button

A form ultimately only decides what gets displayed or computed when you open a document. Adding or removing a field from a form doesn't add or remove an item from a document! A popular trap: You add a new field to a form (e.g. color) and give that field a default value (e.g. green). You open that document to check and it nicely shows "green". However the document actually doesn't contain the item. Since the item wasn't there when you open it, the default value executes, but until you switch to edit mode and hit save nothing gets saved back into the document.
The same applies when you remove a field from a document: it simply isn't shown anymore, but the data is still in the document. If you want to get rid of the data too, you need to create an agent for that (which is pretty simple: FIELD obsoleteField := @DeleteField (You get the irony here: despite deleting an item the formula is @Delete field. Renaming a field is the same as deleting and recreating it with a new name. It is an action in the form, with no impact on the document.
Another stumbling block: the form defines how an item is displayed and entered into a form via the field definition, suggesting data type and if it is one or more values. However items are always multi-value data and the data type of an item doesn't need to match the type of the field (if auto-conversion fails you will get an error). There is a detailed explanation about forms, documents and items you want to read.

Forms might include subforms, which from a document perspective doesn't matter. An item created (through a form) doesn't carry any information how it was created. If you need a detailed track record what item has been created/updated when and by whom, you want to have a look at the Inversion of Logging pattern.
Forms also contain a series of events that fire when things happen in the form. In the context of XPages that is no longer relevant, the event model is superseded by the XPages event model. However one area might be relevant: The @Formula used for fields:

* Keywords: check boxes, radio buttons, drop down list etc. Depending on type are inherently single or multi-value or both
Fields in forms can be computed, carrying one @Formula or Input fields, carrying 0-3 @Formula. A field defined as computed for display doesn't get stored back into the document. A field computed when composed gets computed once when the document doesn't contain the field yet. Usually that applies to new document, but the formula also would run when a field is added to a form and a document is opened with that form (and if the document isn't saved, the result of that formula doesn't get stored back). A computed field gets refreshed every time a document is recomputed, that implies the document is in edit mode (unless there is no item with that name, then it runs in view mode too)!
The translation formula replaces the user input with its result. A popular prank is to pick a formula that computes something independent from the input. For orderly developers there is @ThisValue to use the user input. The Validation formula needs to return @success or @Failure("message"). The failure message gets propagated to the XPages error system and shows in the form error control, but not in a field error control.
In XPages a developer can define for each document data source that the document should be computed on open and/or save. The difference to classic form use: in XPages on open all formulas run: default, translation and validation while in classic on open only default runs. Also the form computation runs after the XPages validations, so if an XPages validation fails, the form computation never runs which then might yield additional errors from the validation formula.
Next up: Not all Documents are created equally