Understanding the Domino CRUD API: NotesDocument Deletion Basics

04/19/2009 01:57 PM by Chris Toohey

Deleting NotesDocuments in a NotesDatabase via the ?DeleteDocument Domino URL Command is simple enough, but there are many things to consider - some of which I'll go over in this entry.

1. Click-Confirm-Delete

You're going to want to create a simple to use, simple to recognize NotesDocument deletion mechanism for your Web Browser Client UI. In the Understanding the Domino CRUD API Example NotesDatabase, I've setup a simple click-confirm-delete engine for submitting a Delete request to the Domino CRUD API (example pictured below).

This UI-driven Click-Confirm-Delete facility will - when the delete icon is clicked - use a JavaScript confirm prompt to drive the cancellation or confirmation of the ?DeleteDocument GET-method call.

As Stephan Wissel commented, a direct ?DeleteDocument URL link from your UI could prove problematic and is really not recommended. As a slight work-around, I'm building the call to the Domino URL command via JavaScript.

First, an additional column to my pages rendered View Design Element:

<td class=\"col4\"><img title=\"Delete this NotesDocument\" onclick=\"notesdocument_delete('" + @Text(@DocumentUniqueID) + "');\" src=\"pk_icon_delete.gif\" alt=\"Delete this NotesDocument\" /></td>

Combining this with a very simple JavaScript function:

function notesdocument_delete(UNID) {
var q = confirm("Do you want to delete this NotesDocument?");
if (q) {
  window.location = "pages/" + UNID + "?DeleteDocument";
}
}

And we have the first part of our NotesDocument deletion facility.

2. Post-deletion behaviour -- what now?!

You'll note, in the above notesdocument_delete JavaScript function, I declare a valid View Design Element for the window.location to issue the ?DeleteDocument Domino URL Command.

The defining of a valid, existing, and Web Browser Client-accessible View Design Element is required for the ?DeleteDocument. Failure to define a View Design Element will result in the following error:

A successful submission will look like this:

Since we wanted to make this NotesDatabase a Domino Web Application, we know that this type of behaviour just won't do! We'll want to create a custom deletion confirmation message and - in this case - redirect them back to the NotesDatabase default launch element.

To do that, I've created a copy of the confirmation.html Page Design Element, stripped all of the NotesDocumentUNID lookups, and renamed it $$ReturnDocumentDeleted.

The $$ReturnDocumentDeleted, not unlike the $$Return, is a special-named element that provides functionality in the Domino RAD engine. Simply put, the $$ReturnDocumentDeleted-named Design Element is returned post-successful NotesDocument deletion.

For the Understanding the Domino CRUD API Example Application, I'm using a Page Design Element. Technically, you could name any Design Element $$ReturnDocumentDeleted and that Design Element would be returned post-successful NotesDocument deletion.

NOTE: I could have just as easily re-written the confirmation.html Page Design Element to accomodate this functionality (and added an alias of $$ReturnDocumentDeleted) instead... but that might throw off future users of the examples.

That's pretty much it for the basics of the ?DeleteDocument Domino URL Command. The next part of the ongoing Domino CRUD API series will discuss Read and the various ways that we can pull NotesDocument data from a Domino Web Browser-accessible NotesDatabase.

Stay tuned!