Your Development & Design Resource

Understanding the Domino CRUD API: non-Domino Form CRUD Basics - Part 1

In previous entries, we've discussed how to use the Domino CRUD API in the following ways:

Now I'll show how you can create your own non-Domino Form Design Element-based XHTML Form Elements that use the Domino CRUD API for NotesDatabase Data Management. In this, the Part 1 in a smaller part of the overall Understanding the Domino CRUD API series, I'll show you how you can create a simple Domino Page Design Element that can be used to Create and Update NotesDocument data.

NOTE: I'm opening up the Domino CRUD API Example NotesDatabase to Anonymous access having Editor w/ Delete. I'll keep it that way as long as we all play nicely. Someone playing script-kiddie and putting some cross-browser attack or posting inappropriate content will ruin this for everyone (as well as give me the burded of shutting things down). Should go without say, but...

First thing first, we'll talk about the ingredients for this build:

  1. Page Design Element: content.html

    This is going to be - on purpose - a very basic build. I could get really creative with this XHTML (Content-Type: text/html) webpage, but that might distract from the overall example.

  2. Input/Textarea Element name Attribute match

    This one is simple yet very powerful. If you're NotesItem is named title, your XHTML Form Element's Input Element name for title needs to be title!

  3. NotesDocumentUNID passthru Logic

    Just like with the Smart Landing Page - which is a basic example of an advanced Domino Design Element-driven Domino CRUD Read - we'll be using a NotesDocumentUNID to drive the Update XHTML page Form population.

  4. ?CreateDocument Domino URL Command

    We'll use this to facilitate the Create Domino CRUD verb.

  5. ?SaveDocument Domino URL Command

    We'll use this to facilitate the Update Domino CRUD verb.

First, we'll create our simple content.html Page Design Element:

Domino CRUD API: content.html Page Design Element

Simple, and will get the job done. Two major things to point out here: the Form Element's processing agent and the value attribute for each Input Element.

The Form Element's processing agent - as shown - uses a Computed Text instance to populate it's action:

~UNID := @UrlQueryString("UNID");
@If(~UNID = ""; "content?CreateDocument"; "0/" + ~UNID + "?SaveDocument")

This simply checks the URL Query String for a parameter named UNID. If found, I know I'm going to Update a NotesDocument. Otherwise I'm going to Create a new NotesDocument.

The Computed Text set as the values of our Input and Textarea Elements does someting similar (for the Title Input Element):

~UNID := @UrlQueryString("UNID");
@If(~UNID = ""; ""; @GetDocField(~UNID; "title"))

When we click submit - via the simple Input Element typed "submit" - we're going to rely on our XHTML Form Element's processing agent to handle the rest.

For new NotesDocuments, we see that it's pointing to the Content Domino Form Design Element and will issue the ?CreateDocument Domino URL Command. This will result on a NotesDocument being creating in the target NotesDatabase and leverage the $$Return to redirect our Web Browser Client session post-submission to our Smart Landing Page.

For existing NotesDocuments, we'll use the following syntax:


Same thing here - the ?SaveDocument does the real work here via the Domino CRUD engine and performs an Update with the submitted XHTML Form Element contents.

NOTE: Notice the /0/ placeholder for the View Design Element in the XHTML Form Element's processing agent. If you replaced this with /pages/, it would honor the pages View Design Element's Form Formula, thus first rendering/submitting the NotesDocument via the display Form Design Element and - since there is no $$Return - would simply return the Form Processed message to the Web Browser Client.

The last part of this is to direct people to an edit link for each NotesDocument in your Pages View Design Element:

~t := @If(title = ""; "Untitled Content"; title);
~pl := "<a href=\"pages/" + permalink + "\">Use Permalink</a>";
~unidl := "<a href=\"pages/" + @Text(@DocumentUniqueID) + "\">Use UNID</a>";
~htmledit := "<a href=\"content.html?open&UNID=" + @Text(@DocumentUniqueID) + "\">Edit</a>";

"<tr><td class=\"col0\">" + ~t + "</td><td class=\"col1\">" + ~pl + "</td><td class=\"col2\">" + ~unidl + "</td><td class=\"col3\">" + ~htmledit + "</td></tr>"

The ~htmledit gives us the UNID URL Query String Parameter required for our Update, and the rest is handled by the Domino CRUD engine!

Wanna play? I've enabled Anonymous access to the Understanding the Domino CRUD API Example NotesDatabase. You should have Editor access with the Delete role enabled.

In our next entry - Understanding the Domino CRUD API: non-Domino Form CRUD Basics - Part 2 - we'll discuss how you can handle Read and Delete CRUD verbs - completing the Basics subsection of the non-Domino approach. After that, we'll get into some pretty advanced stuff!

Hopefully you'll start to see - especially after this - exactly where we can go from here. My XHTML Form was created in Aptana and outside of it's using Computed Text to populate the XHTML Form Element really wouldn't need to reside in a NotesDatabase at all. See... getting a firm handle on this stuff is the ground work for extending your Domino Web Application Development to new heights: integrating with other technology investments and SaaS/cloud services!

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.