HOWTO: Managing your contacts

In this tutorial we'll see how to set up a simple contact list in an XML database, as well as a simple application that will allow the list to be managed. The application we produce is based on the Ruby on Rails tutorial since we want to show how much more easily and quickly web applications can be built and maintained, when we are using large, standard components.

Creating an initial list of contacts

Create a new file.

Paste the following into it:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<people>
<person>
<name>Superman</name>
<street1>123 Somewhere</street1>
<street2/>
<city>Smallville</city>
<state>KS</state>
<zip>123456</zip>
</person>
</people>
</pre>
Click on the "Save to URL..." button.

Connect to the database at:

http://localhost:8080/exist/webdav/db/

By default the administrator user name is "admin" and the password is blank.

Create a new folder, called "people".

Add the file-name "people.xml" to the URL.

Save it.

Verify that the data is there, via a web-browser:

<a href="http://localhost:8080/exist/webdav/db/people/people.xml">http://localhost:8080/exist/webdav/db/people/people.xml</a>

For instructions on using other WebDAV clients, see:

<a href="http://localhost:8080/exist/webdav.xml#N101D2">http://localhost:8080/exist/webdav.xml#N101D2</a>

Creating a simple application to view the data

Now we need to create an application that lists our contacts. We'll call this application a 'view' (in the MVC sense), but since it also retrieves the contact data via an XForms model, it is more than a view.

Create a new file.

Paste in the following:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns:xf="http://www.w3.org/2002/xforms" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Friends View</title>
<xf:model>
<xf:instance src="people.xml"/>
</xf:model>
</head>
<body>
<h1>Friends View</h1>
<p>This page will display one friend</p>
<xf:group ref="person">
<xf:output ref="name"/>
</xf:group>
</body>
</html>
</pre>

Save this to the URL:

http://localhost:8080/exist/webdav/db/people/view.xhtml

<a href="http://localhost:8080/exist/webdav/db/people/view.xhtml">Open with your test browser</a>. (See here for installation instructions.)

Note that we aren't dynamically creating a user interface on the server and then distributing it, as you would with languages like PHP, ASP, JSP, Ruby on Rails, and so on; instead we've created a small application that itself gets its own data. Since the language used to write this application is XML-based, standard mark-up, it can still be processed on the server in the same way that other languages are.

Adding CSS rules

To give our application a basic style we need to create a CSS stylesheet. The quickest way to do this is to create an empty CSS file, and paste in the style rules from the Introduction to XForms.

Once we have the CSS file in our XML database, we can refer to it as follows:

[TODO: Either put the CSS inline, or refer to it with a link.]

Showing repeating data

In a web application that uses a standard SQL database in conjunction with some kind of server-side scripting language--Ruby on Rails, PHP, ASP, etc.--adding repeating data to an item will require an extra table in the database, and some kind of 'for' loop in the code.

A typical example of what is involved is available in the Ruby on Rails tutorial:

  1. a new table is created to hold phone numbers;
  2. a Ruby on Rails model is generated to wrap this table;
  3. the script for this model is modified to indicate that a person 'has many' phone entries, and that the phone table 'belongs to' the person table;
  4. a 'for' loop is added to the view to show all phone numbers.

We'll now show how to achieve the same effect without having to update database tables, or write language-specific looping constructs.

Adding the phone information

The first step is to add the phone number information to our person data. This is easily done by editing the person.xml 'file' in our XML database:

    <zip>123456</zip>
    <phones>
      <phone>1234567890</phone>
      <phone>1122334455</phone>
    </phones>
  </person>

Showing the phone numbers in the application view

Now that we have some repeating data to show, we can update the application itself. This involves nothing more than using the XForms repeat construct:

        <xf:output ref="zip">
          <xf:label>Zip:</xf:label>
        </xf:output>
        <xf:repeat nodeset="phones/phone">
          <xf:output ref=".">
            <xf:label>Phone:</xf:label>
          </xf:output>
          <br />
        </xf:repeat>
    </xf:group>

Manipulating the data

The next stage of developing our application is provide facilities to add, remove, edit and list our contacts. Ruby on Rails provides some powerful tools to automatically generate these kinds of facilities for you--described as scaffolding. We'll generate these methods ourselves in our application.

Allowing database updates

Before we can update the database we need to alter the security settings on eXist. Whenever you access the XML database without having logged in, operations are performed as user guest, so we need to allow this user to have full rights to the collection people. The quickest way to do this is by setting the 'home collection' for guest.

First, open the administration tool:

http://localhost:8080/exist/admin/admin.xql

Login (remember that the default administrator is admin with no password).

Go to 'Manage Users'.

Select guest and then click 'Edit'.

Click on 'Leave password unchanged' and set Home Collection to 'people'.

Click 'Change'.

Adding a new contact

To add a new contact we'll take the following approach:

  1. a switch is set up containing two cases;
  2. the first case contains a trigger which allows the second case to be activated. It's this trigger that the user will click to add a new person;
  3. the second case contains input controls that correspond to each item in a person;
  4. the user can enter data into the controls;
  5. when the user saves the data, a PUT is performed to the person collection;
  6. the initial case is toggled back into view;
  7. the list of contacts is refreshed from the database.

This last step will be useful in the future if more than one user can update the database at the same time, since by performing a refresh we'll be retrieving changes made by other people.

Adding edit controls to the application

The first thing we'll do is allow the data to be edited. To do this we will take the following approach:

  1. use an indentifier from the entry.....

need to add input controls to reflect each of the parts of the instance data that can be edited: