XPages Example: Building a Custom Control - How to build a Custom Multi-FileUpload Control that you can drop on any XPag

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:



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....