Initialising a local file

Whether using file: or cookie:, a common requirement is the need to create the initial file on first use of a form. This is a little tricky, because if you initialise your instance using @src you have no way to detect that the file doesn't exist. The following technique is used by our RSS Reader side-bar (part of the formsPlayer install, and discussed at [to be added]):

1. Create an instance that will hold the contents of the file. Give it an inline instance of some default values--in our case it contains a basic list of RSS feeds--rather than referring to the file using @src. In the rest of this example, the instance is referred to as i-list.
2. Set up a submission to load the required document. In our case it's going to be a configuration file, loaded via the cookie: protocol, but it could be loaded via the file: protocol:
   

   <xf:submission
    id="sub-open-list"
    method="get"
    ref="instance('i-list')"
    action="cookie://feed-list.xml"
    replace="instance"
   >
     <!--
       If we fail to load the list, then this is probably
       the first time we've been run, so save the default
       list.
     -->
     <xf:action ev:event="xforms-submit-error">
       <xf:message level="modal">
         RSS Reader has failed to open your local data file.
         This may be because this is the first time you have
         used the RSS Reader. A default data file will be
         created which includes a small number of feeds.
       </xf:message>
       <xf:send submission="sub-save-list" />
     </xf:action>
   </xf:submission>
   

   Note the behaviour in the error handler (when the file doesn't exist)--we simply save our initial instance data, which has been placed inline in the instance i-list).

3. Create an xforms-ready handler that triggers this get, i.e., which loads your local document:
   

   <xf:send submission="sub-open-list" ev:event="xforms-ready" />
   

   (Note that you have now effectively emulated the behaviour of @src, but with all the benefits of submission, such as having notification events as well as the ability to use instance data.)

   In normal operation, using sub-open-list will load the previously saved file, overwritting the inline instance data. But on first use there will be no file, and so the error handler will be run, and cause the inline instance data to be saved.

4. Set up a submission to save the list to the file (you don't need to set a 'dirty flag' but it is quite useful):
   

   <xf:submission
    id="sub-save-list"
    method="put"
    ref="instance('i-list')"
    action="cookie://feed-list.xml"
    replace="none"
    encoding="ISO-8859-1"
    omit-xml-declaration="false"
    indent="true"
   >
     <xf:setvalue bind="dirty-flag" ev:event="xforms-submit-done">
       false
     </xf:setvalue>
   </xf:submission>
   

   Note that you would need these two submissions anyway, to load and save the file; the only additional bit we're adding here is the use of xforms-ready to invoke the submission that does the loading, and the use of xforms-submit-error on that load to invoke a save of our initial data.