John's Blog

Yellow Day tip: how to use Notes computeWithForm with an XPage

groupwareinc — Mon, 11 Aug 2008 00:00:00 -0400

I'm celebrating Yellow Day today here at GroupwareInc. In honor of the celebration I have an XPages tip to share with you.

How to use Notes computeWithForm with an XPage
Here's how you can use your Lotus Notes default field formulas when opening up an XPage, or when saving an XPage, or both.

- Select your XPage Properties tab and click on the All Properties tab.
- Navigate to data and expand data->dominoDocument[0].
- Select when to execute the computeWithForm form logic. Your choices are: onload, onsave, or both

On the backend, this actually executes the document.computeWithForm() method.

Here is a screen shot:

Have a happy Yellow Day!

John

XPages: Techniques for using Client-Side Javascript with Server-Side Javascript

groupwareinc — Wed, 16 Jul 2008 07:55:51 -0400

XPages provides techniques that you can utilize between client-side and server-side Javascript. I have a couple of examples below that show how you can stop server-side events from firing from a client script and also how you can retrieve values for use in client-side script using inline server-side script in your client js.

Events
Each event for a component can have both client-side and server-side Javascript. When the event is fired the client-side script is executed first. You can prevent/allow the server-side script from being executed by returning true or false from your client-side script.

For example, on a "Save" button you want to prompt the user and ask them if they are sure they want to save the document. You can provide a client-side confirm popup on the onclick event. If the user presses "OK" you would return "true" and the server-side script would then proceed to be executed. If the user clicks "Cancel" you would return "false" and the server-side script would be prevented from being executed.

Here's a screen shot of the onclick event showing that there is a server-side simple action to save the document:

Here's a screen shot of the same onclick event, this time I clicked on the "Client" tab:

Here's the result when the button is clicked in the browser:

Processing server-side script in client-side script
You can process server-side script using inline commands in your client-side code. This is a similar technique as using computed text in Domino within a page that contains Javascript. As with Domino, the server-side code is evaluated when the page is loaded.

For example, you want to retrieve values from a Notes document and use that value in client-side script. On the client-side onclick event for the button, you can place the following simple EL expression:

Here's the result if you click the button in your browser:

or you can use server-side Javascript to perform the same task as the EL expression:

or let's say you have a session variable from another page:

or...here I am getting the database name using an @Function::

As you can see, you can pretty much execute any server-side Javascript to return the values you want. This includes server-side js functions from script libraries if they are set as resources for the page.

Additional resources:
Last year there was an article written by Jason English and my good friend Sal Mazzotta for Lotus Component Designer titled Client-side JavaScript techniques and demos. Though all of it does not apply to XPages, you can find techniques similar to the above as well as additional techniques that might be useful.

John

XPages Example: Calling Java Methods directly from server side JavaScript - performing an SQL query Part 1

groupwareinc — Mon, 7 Jul 2008 00:00:00 -0400

I have been reading many of the discussions this week concerning JavaScript as the language for XPages. I can understand many of the concerns and questions as to why JavaScript? So, I decided to demonstrate one of the advantages of using JavaScript as the server side language for XPages. In the below example I demonstrate how easy it is, and how powerful it is, to call Java methods directly from JavaScript. You can download the example Domino database by clicking here: XPagesJSToJava.nsf

JavaScript can call Java methods directly and pass variables to and from those methods. There are some "type" differences between Java and JavaScript that you need to be aware of. I believe the charts on this site outline the variable conversions well: Javascript to Java Conversions. In the below example I pass string values directly from JavaScript to and from Java, which is straightforward and without any conversion issues.

Since Domino 8.5 is Eclipse based, you can switch to the Java perspective and add Java code to your project. The nsf database is the project. (If you haven't done this yet, it is interesting to switch perspectives and look around at the structure and the code.) By switching to the Java perspective, you open up your code to the importing or referencing of Java libraries, or the creation of your own classes.

What makes calling Java methods directly so powerful in XPages is that nearly every property in an XPage can be computed, and wherever these's a computation you can use JavaScript for the value or formula. For example, this will allow you to call Java for: populating data sources, labels, view column labels, view data columns, computed text, visibility formulas, any place you see a diamond (which is everywhere)...as well as all server side events. So, wherever you can call JavaScript you can also basically call Java methods!

Example Overview
In this example I am calling a Java method that will return data from a DB2 database. I pass in the query and I receive a concatenated string as the result. If you want to follow the example, and you do not have DB2, you can download DB2 9C for free from here: DB2 Expess-c 9.5. After the install you will see an option to create the Sample database, select this and you will have pre-populated tables to work with.

**Just a note that this is just for demo purposes and performance was not a key consideration. Hopefully access to relational databases will be native in a future release.

This is a screen shot of the Employee XPage. The Combo Box Control's values are populated with a JavaScript call to "getDeptNumbers()". This function calls the Java method "javaMethods.SQLQuery.executeQuery()" which is the Packagename.Class.Method() of the method we want to call. The last line of the JavaScript function I use an "@Explode" in order to convert the string to an Array for the Combo Box values. There's very minimum amount of code in this example so it will be easy to implement.

** update 7/9/08 - I changed the location of the SQLQuery.java file in Part 2 of this article and it is different than in the Eclipse screen shot

Here is a screen shot of the Employee View where I perform a dynamic SQL lookup on the last column. Nathan Freeman posted an example of performing a @DbLookup on a view column. It's a great example, and a great change in how we as Domino developers can utilize views in XPages. View columns can contain any JavaScript formula in XPages, so they can be dynamic.

As the view is rendering it is dynamically performing SQL lookups for the Department Name by passing the ColumnValue "Depart. No." to the JavaScript function "getDepartment(deptNo)". This function makes a call to executeQuery passing in the "where" clause so we only retrieve the single Department Name for each Dept. No. in a row. Now....I Know what you are thinking....performance obviously would be a consideration in really using this technique....but it's really cool example nonetheless!

How to build it

Click here to continue with Part 2: How to build it.....

XPages Example: Calling Java Methods directly from server side JavaScript - performing an SQL query Part 2

groupwareinc — Mon, 7 Jul 2008 00:00:00 -0400

This is Part 2 of this example. Click here to read Part 1. How to Build It I'll go over the steps in detail here. The steps are actually very few. I found that the SQL.jar file is already included in the project, so you do not need to ...

XPages Example: Building a Custom Control - How to build a Custom Multi-FileUpload Control that you can drop on any XPage, and it stores all attachments in an external repository db.

groupwareinc — Sun, 29 Jun 2008 08:17:49 -0400

Below is an example of how to build a multi file upload Custom Control that uses a central attachment repository db for all the attachments. The application has very little code and utilizes the Repeat control and Panel control to generate an unlimited amount of uploads per XPage. (Actually, I am sure there is a limit but I have not hit it yet.) The step by step instructions are below. You can also download the example database(s) by clicking here: XPageCustomControl.zip

Overview:

XPage Custom Controls allow you to build your own controls for reuse. They show up in the control palette and can be dragged and dropped on any page just like any of the other controls. The concept is similar to a subform in Domino.

I was demoing XPages to a group of colleagues the other day. I was showing an example of the repeat control, which allows you to repeat a group of other controls based on a formula or value. The neat thing about the Repeat control is it can dynamically creates controls at runtime. One of the the guys asked about using the control to generate unlimited file upload controls for storage in central repository database. I thought... wow, that is a great use case for an example (thanks Mark). It was very quick to build too.

Let's start out with a look at the completed custom control:

After dropping it on an XPage, here is a screen shot of the control in use. You can see that 3 files have been uploaded already and the user clicked the "Add New Upload" button a 4th time and is presented with a blank upload control plus a description field:

The "Add New Upload" button creates a new document in the FileUploadDB database with a reference to the current document's doc ID. The page is then reloaded and the repeat control creates a new blank upload control bound to the new document. A simple JavaScript save() uploads the attachment.

You can drop this control anywhere on your page(s). The only additional item that is needed on your page is a field calculating the document's docUNID (2nd to last screen shot below).

Here are the steps to build the control:

In your database, under Database Navigator select "Custom Controls" then click "New Custom Control". Provide a name for the control.

Drag and drop a Button control on the page and for the label enter "Add New Upload". Select the Event tab and provide the following formula for the onclick() event. This will create a new attachment document in the repository and reload the page:

*note: for this example the attachment repository is named "FileUploadDB.nsf" in the Domino root directory

Next drag a Repeat control to the canvas. Select JavaScript for the Iteration and enter the following for the formula. This formula looks up the associated attachments and generates an array of docIDs based on the document collection:

Enter the following for the Repeat control options. The "docid" variable will contain the docUNID for each document:

*note: I do limit the amount of uploads to 30. I think that's enough...

Next drop a Panel control into the Repeat control. Set the Datasource as follows:

Set the Document Id to be computed. The Document ID will be the "docid" variable from the Repeat control:

There is one property we do have to set that is not obvious if you are starting out with XPages and Panels. That is to: "ignoreRequestParams". The reason for this is we are setting the Document ID and default Action for the Panel ourselves and do not want the Panel to pick up these parameters from the request. Here is a screen shot of how to set that parameter:

Drop a "Table control" to the Panel, 1 row by 2 columns. Now we need to add our controls to the Table. Add an "Edit Box", "File Upload" and "File Download". Here's a screen shot of the bindings for the controls:

Description Edit Box Control:

FileUpload Control and FileDownload Control both have the same bindings:

For the FileUpload control we want to hide the control after one file has been uploaded. We only want one attachment per repository document. Here is a screen shot of the Visibility formula and where you would set that:

Set the opposite logic for the FileDownload control, that is return false if there are 0 attachments.

Place a Button control in the second column labeled "Upload". Set the same visibilty formula as the FileUpload control. It has a very simple formula which saves all data sources. You could substitute a simple action here if you prefer:

On the form where you will use the new MultiUpload control, I use the universalID for the link between the document and the attachment. I placed a hidden Edit Box control on the page with the following Default value formula:

Lastly, here is the Attachment form in the FileuploadDB.nsf repository. I have a view sorted by ParentUNID named "vAttachmentLkUp":

That's it! It really is very minimal the amount of work involved. It took less than an hour for me to do. I am sure the interface could use a little bit more work, but I think it makes for a great example.

The one issue I had seemed to be a bug where I could not place the FileUpload control as the first control in the Panel. I ended up putting the Description first and that seemed to fix the issue...very odd issue. I posted the problem to the 8.5 Beta forum.

Download it and try it out. Hopefully seeing these techniques solving a real business need will start you thinking about other uses for this technology. Let me know if you have any questions....

John

XPages Example: utilizing the built-in AJAX features

groupwareinc — Sun, 22 Jun 2008 09:45:51 -0400

You can take advantage of AJAX while developing web 2.0 applications with XPages. There are 2 features that provide built-in AJAX support.

These are:

Ajax Type Ahead
Partial Page Refresh

Below I will walk you through step-by-step on how to implement these features in an application. You can also download a sample database by clicking here: xPageAjaxExample.nsf

Ajax Type Ahead

The Ajax type ahead feature can be added to any edit box control. It allows you to provide a list of values to the user by either entering a static list or computing the list via a formula. There is also a choice for retrieving a list from a URL, though I have not tried this option myself.

In this screen shot I have clicked on an "Edit Box" control and then selected the "Type Ahead" tab:
- I clicked on "Enable Type Ahead"
- Selected "Full" mode
- For suggestions I selected computed and added a @DbColumn formula (next screen shot)
- I unchecked "Case-Sensitive"
* The help has a full description of the options

For the type ahead suggestions, I want to return a list of Sales Representatives from a view. I selected computed by clicking the diamond and entered the following formula:

Here's the results if I enter the letter "s" in the SalesRep field in the browser. The user is provided with a drop down of choices to select from:

Ajax Partial Page Refresh

The partial page refresh is available on any event. You select "Partial Update" on the event tab and then select the element you only want to have updated when the event is fired.

In this example, I only want a table on the page to be updated when the user clicks the Lookup button. Here is what the settings look like. The table ID I want to refresh is "OtherCustomers":

This is the screen shot prior to clicking the button.

This is after the button is clicked. Screen shots do not really do this feature justice, you'll need to try in in your browser to see the effect.

This example is a very simple one where I have no business logic behind the button event. The button's sole purpose is to force a round trip of the page to the server and provide the partial page refresh.

There is a computed text field on the form that performs an @DbLookup based on the SalesRep field. Here is the code for that computed field. Note: I implode the array and use "
" as a separator so I get a line break. On the computed field there is an option to set the "Content Type" as HTML. This equates to pass thru HTML in Domino. Here's the formula for the lookup:

As you can see, it is very easy to take advantage of these 2 features. Domino 8.5 also ships with the Dojo toolkit available on the server. You will be able to utilize the library in you client side script for additional AJAX features.

Additional xPage examples on this site can be found here: Domino 8.5 - XPages examples

John

XPages Example part 2: Generating dynamic editable fields for a document collection

groupwareinc — Mon, 16 Jun 2008 06:50:00 -0400

I built on the previous XPage example, the Customer Orders application, to demonstrate how to generate dynamic fields from a document collection. There is a sample database for you to download as well as a powerpoint presentation that explains the steps involved.

Over the years I have developed different techniques to handle dynamic fields in Domino applications. I'm sure many of you have also tackled this issue in various ways. In XPages there are built in controls that you can utilize to address this issue.

In the previous example I demonstrated how XPages allows you to bind your controls on the page to multiple datasources. In this example I take it up a notch by showing how you can repeat a panel control that is bound to a document multiple times, thereby binding edit controls to a collection of Notes documents. XPages maintains the binding so that all the documents are updated from a single button with a single simple action "Save Datasources".

Here's the use case: When a Customer Order is created there could be multiple items the customer is ordering. We should give the user the ability to add new items dynamically by clicking a button. The button will create a new response document and then reload the page. The repeat control will generate the following editable fields for all the response documents: Item Number, Price, and Quantity.

Here is a screen shot:

Here are the downloads:
- CustomerOrders.nsf
- step-by-step powerpoint

Download the application and try it out. Contact me if you have any questions via posting or email. My contact information is in the powerpoint.

John

XPages Example: updating data from multiple forms from a single xPage

groupwareinc — Mon, 9 Jun 2008 00:00:00 -0400

I put together an example of using XPages to update data from multiple forms on a single XPage. There is a sample database for you to download as well as a presentation that walks you through the steps involved.

XPages separates the presentation layer from the data layer. This is obviously very different to the one to one relationship in Domino. XPages also allows the developer to bind to multiple datasources from a single page. This feature can really provide a different approach to developing Domino applications.

I came up with the following simple use case: We have an application where the user takes product orders that are shipped to customers. Sometimes the user needs to update the customer information while taking the order. We can provide the Customer fields right on the Order form and bind them via a Panel control to the Customer form. A single button with a simple action saves all the bound datasources for the page and therefore updates both forms for us. Here is a screen shot:

Here are the downloads:
- CustomerOrders.nsf
- step-by-step powerpoint

Download the application and try it out. Contact me if you have any questions via posting or email. My email address is in the powerpoint (created with Symphony however!).

John

Lotus Domino Designer 8.5 Beta 1 release

groupwareinc — Sun, 1 Jun 2008 10:54:01 -0400

As a Lotus Domino 8.5 design partner, I have been working with the 8.5 pre-beta releases for several months. The public beta version 1 was released last Friday. There are many enhancements, the largest being within the Designer and the move to eclipse and the inclusion of xPages. With a background in Lotus Notes and Websphere Portal I am particularly interested in xPages since the technology is derived from the Lotus Component Designer.

Here is a good description of the new xPages technology taken from the IBM Lotus Domino Wiki:

XPages and custom controls

An XPage is a new design element based on JavaServer Faces (JSF) technology that lets developers create Web 2.0 enabled pages for use in Web browser applications running on Domino 8.5. XPages remove the barrier of Web programming in Domino by providing advanced page design capabilities and complete control of the generated markup. They also allow access to any kind of data and provide an easy method for localizing applications. XPages includes the following features:

AJAX enabled (for example, partial page refresh, type ahead capability, and so on)
Advanced Web control library (tabbed panel, and so on)
Full support for styling by using CSS

Fully extensible by using custom controls (composite controls or Java-based controls) or JSF extensions

Support for multiple clients (Web, rich client, and so on)

JavaScript scripting language support for client-side and server-side action

Pre-built simple actions provided for most common cases

Direct access to Java libraries on the server

A custom control is a collection of controls that are stored as a single object. Similar to subforms in Domino Designer, custom controls are design elements that you can create once and add to multiple XPages. When you update a custom control, every XPage that uses that custom control gets updated with the changes, saving developer time and effort.

I am working on a number of examples and samples that I will be posting demonstrating xPages. This will present some compelling reasons why Domino developers will want to use this technology. I'll be posting these over the next couple of weeks on this site....

Domino 8 beta 2 - composite applications and eclipse components

groupwareinc — Mon, 7 May 2007 09:09:13 -0400

I've been working with the beta 2 release of Domino 8. In particular I've been working on composite applications, eclipse components, and eclipse plugins. The product has been very stable.

I've found some good resources for the work I've been doing. Here's a collection of links that I found helpful:

New redbook draft that has a chapter on Lotus Notes: Building Composite Applications
Two simple tutorials to build NSF based apps with NSF and Eclipse components
Excellent article by Brian Leonard : Extending the IBM Lotus Notes V8 sidebar and tool
A follow up article by Brian: Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar
A thread on Notes.net discussion that has some good info. In particular how to deploy plugins to the Notes 8 client (you have to change plugin_customization.ini for user initiated installs)
A pdf : How to develop Eclipse Components in an Eclipse IDE for CompositeApplications in Lotus Notes
I found this pdf very valuable for building an eclipse composite application component and for learning how to deploy components by creating an update site. Creating a new feature and then update site starts on page 28: Composite Application Tutorial II: Eclipse Component

John