Controller API Utility v1.0 - Take MVC Architecture to your IBM Lotus Notes Application

07/12/2010 12:15 AM by Chris Toohey

• Controller API Utility
• Initial Setup
• Installing the com.dominoguru.control Script Libary
• Creating Control Documents
• Purchase & Download

Controller API Utility

The Controller API Utility allows you to completely maintain application and business logic separate from user interface design, allowing you to evolve the application as needed with minimal code and design maintenance.

The Controller API Utility -- or Controller -- consists of Control Documents that you define, which can conditionally set values of fields (NotesItems) on a document (NotesDocument), or launch an agent from the active Lotus Notes application.

This document will first walk you thru the setup of Controller, and then it's use in your own Lotus Notes apps.

Initial Setup

Before you install the Controller Script Library (com.dominoguru.control), there is a simple change required to the LotusScript. The com.dominoguru.control Script Library will be copied/installed to a target Lotus Notes application, but will need to communicate back to the Controller. By default, com.dominoguru.control is designed to work on a local Lotus Notes Client in the root NotesData directory.

Simply put, you need to update the Server and FilePath of Controller in the com.dominoguru.control to match your installation location in your environment.

To do this, simply open the com.dominoguru.control Script Library in Domino Designer.

Note: You may be prompted that modifying this Script Library may cause problems. Controller inherits from itself, so select OK in this instance.

Once you have opened the com.dominoguru.control Script Libary in the Domino Designer Client, find the cdb_server and cdb_filepath variables in the process Function, and update them to mirror your installation directory.

For example, if you installed Control in the following location:

Domino Server: dev_server/acme
File Path: development\control.nsf

You will need to update the LotusScript variables to the following:

Note: \ (backslash) is the escape character for Strings in LotusScript, so for subdirectories, you will need to "escape-the-escape" and add a second backslash.

After completing this change (and saving your changes!), you are ready to use the Controller API Utility.

Installing the com.dominoguru.control Script Libary

In order for your Lotus Notes applications to take advantage of the Controller API Utility, they will need the updated (see above) com.dominoguru.control Script Library.

Select Actions\Install Script Library from the Lotus Notes Client Action Menu, and you will be prompted to choose a Target Lotus Notes application:

Once you select the Server and Filepath to your target Lotus Notes application, you will receive a confirmation upon successful installation.

Using the com.dominoguru.control Script Libary

Each document save-level operation will use the process Function, this includes:

• Form Design Elements
• Agent Design Elements
• View Action Design Elements
• Shared Actions

For example, the standard document save-level operation is interrupted for a Form Design Element via the addition of a SaveOptions Computed For Display Field set to "0".

After setting including the com.dominoguru.control via the Script Global in the Form Design Element:

You can set the QuerySave Event to the following:

The process Function actually saves the submitted document while processing the Formula-type Control Documents. This method allows you to "seed" an Agent without creating a NotesDocument in the Lotus Notes application -- allowing you to create stateless logic processing events.

Creating Control Documents

The Control Document allows you to maintain application and business logic in your target Lotus Notes application simply by allowing you to control the value of target fields (notesitems) based on your own logic or trigger Agents in the target Lotus Notes application as part of the document save-level operation.

Here are several things to consider when creating your control documents:

• Controller is designed to work on Active Status entries only. You can disable an entry by setting the status to Inactive.
• A Selection Formula can be defined to evaluate if the Control Document applies to the submitted NotesDocument.
• Use the Description to give your Control Documents an easy-to-remember name.
• You can either set the value of a NotesItem via Formula or call an Agent based on the Type.
• Example Formula syntax:
  @Now or "foo".
• NotesItem is the name of the target field, such as form or subject.
• Use either the primary or alias name for the Agent Name:
  (AgentName) or agentname.

Demo Video

The following is a screencast demo of the Controller API Utility in-action with a simple Test Application Lotus Notes Client applications.

In this video, I show you how to easily maintain business and application logic via Admin-defined Control Documents without needing to modify the target Lotus Notes app.

Purchase & Download

The Controller API Utility for IBM Lotus Notes is only $5.

You can purchase this application, along with the demo app from the screencast/demo, via the button below:

Once your Paypal purchase has gone thru, you will be redirected to the download by Paypal. The download is a simple 423KB ZIP archive of both the Controller and demo apps. The Controller app has About this Database and Using this Database documents which have installation and usage details.

If you have any issues with the purchase, please contact me directly at ctoohey@dominoguru.com! Paypal should be redirecting you to the Zip archive download URL immediately after you authenticate with your Paypal link and click on the Pay now button. If you are not redirected to the ZIP archive download URL after purchase, please let me know and I'll get it to you immediately!

And thank you in advance for your purchase!