John's Blog | 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.

Sunday 29th, June 2008

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.06/29/2008 05:17 AM

Domino 8.5 - XPages

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: XPagesCustomControl.zip

* Please Note: There's an updated version of this control Published on OpenNTF.org

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:

Image:John's Blog - 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.

Image:John's Blog - 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.

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:

Image:John's Blog - 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.

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:

Image:John's Blog - 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.

*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:
Image:John's Blog - 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.

Enter the following for the Repeat control options. The "docid" variable will contain the docUNID for each document:
Image:John's Blog - 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.

*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:

Image:John's Blog - 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.

Set the Document Id to be computed. The Document ID will be the "docid" variable from the Repeat control:
Image:John's Blog - 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.

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:
Image:John's Blog - 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.

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:
Image:John's Blog - 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.

FileUpload Control and FileDownload Control both have the same bindings:
Image:John's Blog - 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.

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:
Image:John's Blog - 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.

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:

Image:John's Blog - 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.

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:
Image:John's Blog - 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.

Lastly, here is the Attachment form in the FileuploadDB.nsf repository. I have a view sorted by ParentUNID named "vAttachmentLkUp":
Image:John's Blog - 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.

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

Technorati: Domino 8.5 XPages

This page has been accessed 6876 times.

Comments :

1. Sascha Jostock06/29/2008 01:01:41 AM

Works, Great!!

2. Sebastian01/09/2009 12:29:06 PM

Hey great tutorial,

i tried with Notes 8.5 final and got 2 Problems - notes doesnt get the Custom Controls "out of the box" of your database. I had to copy the contents into new Controls and add them to Projects Xpage.
Second but more anoying - with hidden DocUNID all uploads are shown, the field isnt computed. So i had to unhide the field and everything was fine. Is there a hidden checkbox like "compute html for all fields" in forms i just can't find?

3. John Mackey01/10/2009 08:56:03 AM

@Sebastian, I updated the sample to fix the problem with the docUNID field so it works with 8.5 Gold. I believe the custom controls issue is a beta 2 issue and you won't have that issue if you download the new example.

Thanks for bringing it to my attention!

John

4. Vayasin02/18/2009 06:06:07 AM

Hi John,
I like your tutorials. they have helped me alot.
Do you know how to use the fileupload without using a notes document to store it. For my project i need to feed a txt file directly into a Java function.

5. Apollo Entice03/13/2009 11:13:50 AM

John,

Let make take the chance to thank you for all your effort building sample apps that I religiously used as my learning tool. Congrats also to AD207, it was a great presentation and xpage app sample.

My question is with File Download control with this sample. Why all my uploaded MS Office (*.doc, *.xls, etc.)won't open when I click the attachments in IE but work's fine with Firefox. PDF's all open fine, *.doc and *.xls will show as garbage.

Any solution to fix this issue.

Thanks,
Apollo

6. Dale04/16/2009 08:28:45 AM

@5 Apollo we are experiencing the same issue, did you find a solution?

7. Richard Cotrim04/23/2009 01:42:59 PM

@5 @6, I'm facing the same problem. Does any one know the fix ? I've notice that the problem is ony with the file download control on IE.

8. John Mackey04/24/2009 09:57:34 AM
Homepage: http://www.jmackey.net

@5,6,7

There's a discussion thread in the 8.5 forum on this issue. Irina Kojevnikova posted a work around.

{ Link }

Hope this helps....

9. John Mackey04/30/2009 08:12:57 AM
Homepage: http://www.jmackey.net

@All, I posted a workaround for the filedownload issue. I also updated the sample download with the fix.

You can read about the fix here: { Link }

10. hector amato07/28/2009 10:20:32 AM

There is an issue which imposes a restriction to the custom control reusability. It is the name of the data source (document), used in document.save(), document.getDocument(), ecc.

If I include the control in a page having a data source named sales, I have to change the name, otherwise errors will raise.

Is there some way to avoid "wiring" the d.s. name ?

11. John Mackey07/29/2009 10:15:18 AM

@Hector

I have since addressed your concern in other posts. I think you'll like the results.....

Look at these 2 posts:

Expanded Custom Control: { Link }

Explanation of using "currentDocument": { Link }

-John

12. jake10/16/2009 09:20:26 AM
Homepage: http://www.critical-masses.com/jakeofalltrades

How do you create a hidden editbox control? I can't see how to make the standard editbox control hidden (type="hidden")

13. Ian10/22/2009 03:58:24 AM

Hi John,

Great example and this works perfectly for me on 8.5.1, almost!

The problem I am having is that when you first load the document you are not able to view the attachment section until you have saved and re-opened the document. It then works fine.

Any ideas how I can get around this?

Ta very much!
Ian