Domino.Commands
Users interact with Domino applications through commands issued as
URLs. Each command specifies a top-level object and activates the methods
needed to carry out a request and generate HTML output. The Domino
Web Server implements many commands. The commands related to the
display and modification of documents are worth a closer look. These are
the commands that enable interactive applications, so the similarities and
differences in their implementation are of particular interest.
?OpenDocumentand ?EditDocument
Three commands display the contents of a document:
?OpenDocumentopens an existing document in read mode, ?EditDocument
opens an existing document in edit mode, and ?OpenForm opens a new
document in edit mode. The implementations of ?OpenDocument and
?EditDocument are very similar. Both execute the following sequence of
steps:
1. Open the existing document.
2. Read all items from document into memory.
3. Load the Notes form referenced by this document.
4. Scan the Notes form and execute default value formulas for any items
that are not yet in memory, and execute all computed field formulas
and add/update items to the in-memory document accordingly.
5. Run the appropriate agent if an item named $$QueryOpenAgent exists.
6. Render the Notes form into an HTML page or HTML form using the
item values from the in-memory document.
7. Free the in-memory document and all items it contains.
The only significant difference between ?OpenDocument and
?EditDocument commands is in step 6, where ?OpenDocument instructs the
GenerateHTML methods to respect read-mode hide attributes contained
within the Notes form, and to create HTML for a read-only page.
?EditDocument instructs these methods to respect edit-mode hide attributes
on the Notes form and to create an HTML form.
?OpenForm
The ?OpenFormcommand executes a similar sequence of steps:
1. Create a new document in memory.
2. Load the Notes form referenced in the URL.
3. Scan the Notes form and execute all default value formulas and
computed field formulas, adding items to the in-memory document.
4. Run the appropriate agent if an item named $$QueryOpenAgent exists.
5. Render the Notes form into an HTML form, respecting edit-mode hide
attributes and using item values from the in-memory document.
6. Free the in-memory document and all items it contains.
The last step of the procedure for all three commands frees the in-memory
document and its associated items. The ?EditDocument and ?OpenForm
commands do not cache the documents for later use because that would
violate the stateless nature of the a Web server. If and when the browser
sends edited information back, the Domino Web Server will re-establish all
the data structures necessary to handle the updates.
?CreateDocumentand ?SaveDocument
?CreateDocumentand ?SaveDocument are the two commands that receive
HTTP POST data generated by browsers when a user clicks the Submit
button on an HTML form and saves the data in Notes documents. Submit
buttons on HTML forms generated by the ?OpenForm command send the
?CreateDocument command, and Submit buttons on HTML forms
generated by the ?EditDocument command send the ?SaveDocument command. The two commands follow similar sequences of steps. The steps
for ?CreateDocument begin with:
1. Create a new document in-memory.
2. Open the Notes form referenced in the URL.
3. Scan the Notes form and execute all default field formulas and
computed value formulas, adding items to the in-memory document.
?SaveDocument
The steps for ?SaveDocument begin with:
1. Read the existing document referenced in the HTTP POST data.
2. Open the Notes form referenced in the URL.
3. Scan the Notes form and execute all default field formulas and
computed value formulas, adding items to the in-memory document.
Then both commands continue on essentially the same path:
4. Create items for all data sent in the POST data.
5. Scan the Notes form and execute all translation, validation and
computed value formulas, updating items in the in-memory document
and returning validation errors as HTML.
6. Scan the Notes form and eliminate any computed-for-display items
from the in-memory document.
7. Run the appropriate agent if an item named $$QuerySaveAgent exists.
8. Save the in-memory document to the appropriate database file.
9. If the $$Return item exists, run the appropriate formula from the Notes
form, and if there is no output from a QuerySave agent, send the result
of this formula back to the browser.
10. Delete the in-memory document and all associated items.
One thing worth noting is the fact that formulas that a user might have
thought executed only once at the time that an HTML form was sent by
either the ?EditDocument or ?OpenForm command will actually execute
again when ?CreateDocument or ?SaveDocument is processed. This can
result in some confusion if these formulas have time-dependent values, or
are based on lookups of constantly changing information.
Posts
