ShowTable of Contents
Sometimes when using the Viewer it is desirable to be able to load and save instance data of a form to XML files on your local file system.
For example, a form could be created that is able to load client data for a given client. The form could provide the user with a file picker dialog, asking the user to choose which client XML file to load, and then that client data could be loaded into the current form. This could operate in an off-line mode, and is all possible using out of the box Lotus Forms functionality.
This could also be useful for a user to be able to save their address information, to a local XML file, and then any further form that requires this address information, the user could select their address.xml file and their address information would automatically be loaded into the current form instead of having to retype the information. The user could make changes to the address info, and then save their changes in the same manner.
How does it all work?
Providing a Save File Dialog
First off we need to allow the user to be able to specify the name and path of the xml file to save. We use the viewer.fileSave() function. Which provides a Save File picker to the user and simply returns the file path chosen. Now we need to do something with this path.
Saving XML Data
Now we're going to talk about the mechanism that we use to actually save the XML file. We can use an xforms:submission of type 'put', where we specify what instance data to 'put' into the file, and if the URL of the submission is a file based URL, then the viewer will create the file containing the XML found in the instance.
OK, we know how to capture a file path provided by the user, and we know how to save the XML file, now how do we glue these two things together especially concerning the fact that the viewer.fileSave() function is an XFDL function, and the xforms:submission is XForms, add to that we want to dynamically specify where to submit the XML file to.
Dynamically determining URL for xforms:submission
xforms:submissions have an attribute called actionref that allows one to specify some xpath that points to where the URL can be found, so it can be determined at runtime - instead of using the action attribute (which hard-codes the URL). So this sample forms uses the following XPath to create a file based URL:
so we want to get the path chosen into savepath
Moving Data from XFDL to XForms
The XFDL set() function has the ability to set data into the xforms model by adding the 'xforms' specification at the end of the set, so this is how we copy the chosen path into the xforms model:
set('instance("Generated")/page1/savepath', custom:fileName, '', 'xforms' )
To put it all together, we've added a value-change-event on a hidden field that points to savepath, such that when it changes, we do a send:action invoking the xforms submission.
So in summary: the user clicks the button, which launches a dialog, capturing a path, the path is saved into a custom option called custom:fileName
, when the custom:fileName
changes there's a compute that pushes its data into the savepath element in an xforms instance. There's a field (likely hidden) on the form, that points to the savepath, where this field has a value-change-event on it - such that when the value changes, it calls an xforms:send action invoking an xforms submission, which uses the savepath as to where to submit (or save) the XML to.
Loading XML Data
Loading the data is almost exactly like saving the data, except we use the viewer.fileOpen() function. Which provides a Open File picker and returns the file path chosen. The xforms:submission this time is a submission of type 'get', so it loads the data from the XML file instead.
Running The Sample
In order to run the sample form properly, you must save the form to your local drive (do not run it directly from the wiki). Any xml files you wish to save or load must be either right next to the form or in subdirectories from where the form exists on disk. For example if you have your form saved in C:\myforms then the XML files could exist in C:\myforms or C:\myforms\myXMLFiles.
I recommend you open the form, and enter some data into the table, and then click the 'Save XML Instance' button. Then enter some more data, clicking save again providing a different file name. Then you can load either file using the 'Load XML Instance' button.