This tip shows how to use the view property called "Allow selection of documents" for web views. The documentation on this property setting is not very descriptive and does not contain all the information you need to use this feature. This property can add the capability to your Domino 6 web application to select several documents in a view and then perform a process on them. For example, you could use the formula language to delete the selected documents. When used in conjunction with a WebQuerySave agent, the documents can be processed to do anything that a LotusScript agent can. Some examples of using this feature might be to process orders, change field values or mail the selected documents.

Click here to see a demonstration of this tip!

To get more information on using WebQuerySave agents and how to use LotusScript in your web applications check out TLCC's Using LotusScript in Domino 6 Web Applications. This advanced level course is designed for developers who know LotusScript and want to use it to build more powerful and dynamic Domino web applications.
Click here to get more information on this course.

Don't know LotusScript yet? Enhance your skills and your career with TLCC's Notes Domino 6 LotusScript Package which includes three LotusScript courses for Notes Domino 6.
Click here for more information on this special LotusScript Package offer!

Tip Explanation

Domino 6 introduced a new view property "Allow selection of documents" for use in Domino web applications. There are several ways to take advantage of this feature:

Add a view action or a button which is used to move documents to the trash or permanently delete them.
Process the selected documents via a WebQuerySave agent by retrieving the selected document's UNID and then retrieving those documents to perform some action upon them.

The first step in using this property is to turn it on. Then, depending on your application requirements, you can either add the ability to delete several documents simultaneously or process the selected documents.

Procedure: Turning on the Allow Selection of Documents in a View

Set the "Web Access: Allow selection of documents" property on the Advanced tab of the View properties.

Procedure: Deleting multiple documents

To delete the selected documents, add the following formula to either a view action or to a button, hotspot or link on the embedded views container page/form:

@Command([MoveToTrash])

This will cause the documents to be moved to the trash. A second view action with the EmptyTrash @command can be used to delete the documents from the database.

If the documents are to be deleted immediately then use the following formula:

@Command([MoveToTrash]);

@Command([EmptyTrash]);

The demonstration uses the MoveToTrash @command to mark the documents for deletion.

Procedure: Selecting all or deselecting all documents

The @commands EditSelectAll and EditDeselectAll can be used to select or deselect all the documents in the view. Note that using this @command will not select all the documents in the view but just those documents displayed on the current web page.

Another way to select all the documents (or deselect them) is to use JavaScript. When the Allow selection of documents is checked Domino will add several JavaScript routines to the web page. Once of those JavaScript routines is _SelectAllDocs(). Calling this JavaScript function with true as the parameter will mark all the documents in the view. Using false as the parameter will deselect all the documents.

The demonstration's button to "Select All" is set to use JavaScript and contains the following code:

_SelectAllDocs(true);

The demonstration's button to "Deselect All" is set to use JavaScript and contains the following code:

_SelectAllDocs(false);

Procedure: Processing Selected Documents

When the "Web Access: Allow selection of documents" property is enabled for a view, Domino will populate a field called $$SelectDoc with the UNID document identifiers of all the documents that the user selected. A WebQuerySave Agent can be used to read in the document identifiers and perform some action on those documents or gather information from the documents.

Follow these steps to process the selected documents.

1. Turn on the view property "Web Access: Allow selection of documents".

2. Embed the view into a container form.

3. In the container form, enable the property to "Generate HTML for all fields".

4. On the container form, create a field called $$SelectDoc. Make this field editable and allow multiple values. Hide this field from web browsers.

5. In the Input Translation formula for the $$SelectDoc field, add the following formula to strip out any null values from the list of document identifiers (UNID):

@Trim($$SelectDoc)

6. If you do not want the container form to be saved in the database then add a hidden text field called "SaveOptions" and make this computed when composed. The formula should be "0" to designate the documents should not be saved to the database.

7. Add a button to submit the form. This button should have the following formula (or use JavaScript to submit the form):

@Command([FileSave]);

@Command([FileCloseWindow])

8. Specify a WebQuerySave agent to run when the form is submitted by setting the form object for the WebQuerySave.

9. Create a new agent. Give it the same name as specified on the form for the WebQuerySave agent. Set the agent's Runtime properties to "Agent list selection" with a target of none. (Domino will add the parentheses around the name if the agent is set to run via "Agent list selection.)

10. The following sample code will display the names of all the customers selected and total up the orders. The key here is that the $$SelectDoc field contains the UNID's of all the selected documents. This code gets those values (which are in an array) and then uses the GetDocumentByUNID method to get each document that was selected to perform the processing.

Sub Initialize

Dim session As New NotesSession

Dim docSubmit As NotesDocument

Dim varDocUNID As Variant

Dim docSelected As NotesDocument

Dim total As Double

Dim db As NotesDatabase

total = 0

'Get the document that was submitted with the embedded form

Set docSubmit = session.DocumentContext

Set db = docSubmit.ParentDatabase

'Setup the web page's font

Print ||

'Get the field that contains the UNID's of the selected documents (array)

varDocUNID = docSubmit.GetItemValue("$$SelectDoc")

'Make sure that at least one document was selected

If varDocUNID(0) = "" And Ubound(varDocUNID) = 0 Then

Print "No documents were selected. "

Else

Print "The customer orders you selected were: "

'Loop through all the documents that were selected

Forall unid In varDocUNID

Set docSelected = db.GetDocumentByUNID(unid)

If Not docSelected Is Nothing Then

Print docSelected.Customer(0) & " "

total = total + docSelected.OrderTotal(0)

End If

End Forall

'Print the total of the selected orders

Print " "

Print "Total of the orders selected was " & Format(total,"Currency")

End If

'Add a button to return to the view

Print " "

Print |<Center><input type="button" value="Return to view" onClick="history.back();"></Center>|

Print ||

End Sub

Below is a screen shot of the container form in Domino Designer.