XRX/Configuration File Editor

Motivation

You have an XML configuration file that only one person at a time will be editing. You want to make it easy to edit the configuration file so that non-technical users without knowledge of XML or occasional users will not make any mistakes editing the file.

Note that this method may not be appropriate if multiple people might edit the same file or record simultaneously. See the record locking section for more detail on this process.

Method

We will load the entire file into an single XForms instance, edit it, and save the entire file. This can be done with a single submission in the XForms application and a single store() operation in the eXist (or similar) database. This can be done even if the configuration file is very complex, and has many sections and many repeating elements. Regardless of the complexity of the file, you only need a single function call on the server to store the file.

Program Outline

Let's assume that the file is stored in a single eXist collection such as my-config.xml. To load this file into an XForms application, you simply put the document into an instance within the XForms model:

<html xmlns:xf="http://www.w3.org/2002/xforms">
   <head>
      <xf:model>
         <xf:instance src="my-config.xml" id="config"/>
      </xf:model>
   </head>
   <body>
   ...
   </body>
</html>

You can then save the file by adding a submission element to the model that will save the file back to the database once the data has changed in the client.

<xf:submission id="save" ref="config" method="post"/>
...
<xf:submit id="save">
   <xf:label>Save</xf:label>
</xf:submit>

Note that you will need to use "post" not "put" in this example. The submit element creates a button in your form with the label "Save".

Building the Forms Application for the Configuration File

There are many ways to "autogenerate" the XForms application that will edit the configuration file in a browser, even if your configuration file is complex and has many repeating elements.

One way is to use a transformation program that transforms an XML Schema to an XForms file. One example of this is the NIEM transform. Although there are other examples of this type of transform, most of these require you to have an XML Schema for your configuration file. If you do not have an XML Schema there are tools that can generate an XML Schema from one or more instance documents.

If you do not have an XML Schema, you can "draw" your XForms client using commercial XForms tools such as IBM Workplace Forms Designer. This drag-and-drop environment makes it easy for non-programmers to build and maintain complex forms.

If you are building a form on a budget, then another option is to use the Orbeon XForms Builder which is an XForms application that will build the form for you.

Client Side Save

If you have a secure Intranet you can use the HTTP PUT operator to save your configuration file directly to the web file system. Sometimes you will need to be able to authenticate a user before you permit the save. This can be done with a traditional login and session management system or you can create a single script that has the correct permissions.

Sample Save XQuery

xquery version "1.0";
declare namespace request="http://exist-db.org/xquery/request";
declare namespace xmldb="http://exist-db.org/xquery/xmldb";

(: put the collection we want to save our data to here :)
let $my-collection := '/db/config-files'
let $my-config-file-name := 'my-config.xml'

(: get the data we want to update from the HTTP POST :)
let $my-posted-data := request:get-data()

(: make sure we have write access to this collection :)
let $login := collection($my-collection, 'my-userid', 'my-password')

let $store-return-status := xmldb:store($my-collection, $my-config-file-name, $my-posted-data)

(: this is what we return.  You can also return an XHTML file. :)
return
<return>
   <message>File {$my-config-file-name} saved in collection {$my-collection}</message>
   <result-code>{$store-return-status}</result-code>
</return>

Back: XSLTForms and eXist • Next: Dictionary Editor