Preface

ERW is a system for managing complex (and possibly large) databases using a web browser. Its original purpose was content management, that is, allowing easy maintenance of web site data organised in a database in a heterogeneous environment, where little is known about client machines except that they will have a web browser.

ERW is based on a formal description of the database in a variant of the common entity-relationship model (more precisely, of what it is usually called the extended entity-relationship model). An XML-based language, ERL (Entity-Relationship Language), is used to define formally a entity-relationship schema that provides a conceptual description of the database.

From the ERL-based description, a Java™ preprocessing tool, ERtool, reifies the schema, that is, it transforms the description based on entities and relationships in a set of tables that suitably implement that description. Moreover, it generates a graphical representation of the schema and documentation about the reification process; this documentation allows you to understand exactly how the process was carried out. And, last but not least, it generates a set of configuration files written in PHP. These files, when fed into the provided run-time PHP environment, generate a set of forms that allows easy editing of the database. A flexible customisation process allows you to tune the forms to your needs.

Where is the difference with other web-based database administration tools? The point is that ERW knows the abstract structure of the database, and thus can offer a much more sophisticated interface to the user. In particular, the user never sees an SQL table: rather, it is presented with relation-based operations such as "associate this element to this element". The run-time environment (using the configuration files produced starting from the ERL file) will modify the database tables correspondingly.

Just to make a comparison, a tool like PHPmyAdmin is to ERW as a disassembler is to a compiler/run-time environment. You can of course use PHPmyAdmin to do raw administration of the database tables generated by ERW, but the knowledge that ERW has of the abstract structure of the entity-relationship schema gives it the possibility of interpreting the same tables in a deeper way. Of course, ERW can only edit databases reified by ERtool, so it is less general.

These are not, however, the only advantages of using ERW. We list some of them:

There are, of course, also some drawbacks. ERW makes a number of assumptions on the structure of the database and on the inner workings of your entity-relationship schema that prevents you from doing certain things:

A Simple Example

Maybe at this point you are curious about ERW, but you still do not understand what it exactly does. The easiest way to solve this problem is showing a simple example.

Suppose you have a library, and you would like to keep track of which users have (or had) a certain book. To this purpose you set up a simple entity-relationship schema, which has three entity types: person, subscriber and book. Book are lent to persons, but certain persons subscribed to the library, and possibly donated some money.

The schema contains a relationship type loan going from person to book, and this type has some attributes: first of all, the starting date startdate of the loan (this attribute is clearly mandatory, as there is no loan without a start); then, the ending date enddate of the loan (this attribute is optional, as the book could be currently out); finally, the attribute type that defines the type of the loan (long or short term).

The informal description of the entity-relationship schema that we have just given is formalised by the following ERL document:


<?xml version="1.0"?>

<!DOCTYPE erl PUBLIC "-//DSI//DTD ERL V1.2//EN" "file://erl.dtd">

<erl id="library" title="A Library">

&ERWauth;

<enum id="termlen" type="char" size="1">
	<enumval value="L" label="Long term"/>
	<enumval value="S" label="Short term"/>
</enum>

<ent id="person" label="Person">
	<attr id="fname" label="First Name" size="30" mand="true"/>
	<attr id="lname" label="Last Name" size="30" mand="true"/>
</ent>

<ent id="subscriber" label="Subscriber">
	<isa entref="person"/>
	<attr id="card" label="Card number" type="int" mand="true"/>
	<attr id="address" label="Address" mand="true"/>
	<attr id="donation" label="Donation" type="numeric" size="11" scale="2"/>
</ent>

<ent id="book" label="Book">
	<attr id="title" label="Title" mand="true"/>
	<attr id="author" label="Author" size="40" mand="true"/>
	<attr id="publisher" label="Publisher" mand="true"/>
	<attr id="isbn" label="ISBN Code"/>
	<attr id="year" label="Year" type="integer"/>
	<attr id="description" label="Description" type="text"/>
</ent>

<rel id="loan" label="Loan">
	<attr id="startdate" label="Start date" type="date" mand="true" 
                default="'2001-01-01'"/>
	<attr id="enddate" label="End date" type="date"/>
	<attr id="duration" label="Type" type="enum" enumref="termlen" mand="true"/>
	<leg entref="person" label="Borrowed..."/>
	<leg entref="book" label="Lent to..."/>
</rel>

</erl>

There are several interesting features in this example. First of all, we include the system entity &ERWauth;, which will automatically include the entity and relationship types that are necessary to handle authorisation. Then we declare a static enumerative type, that is, a function from values to labels. The database will store the values, but the user will be always presented with the labels. Finally, we declare the entity types we are interested in: note that subscriber is declared as being a person.

Then, we declare our only relationship type. The two leg XML elements tell ERW which entity types must be related. Note also that we specify that the default value for the start date of a loan is the first day of the current millennium (but, should we be certain that our database fully supports the SQL standard, we could use, say, CURRENT_DATE).

It is now time for a little bit of magic: assuming there is an empty database named test, and that the file above is named library.xml, the command ertool --sql <library.xml will print on standard output the instructions to create your database. Usually piping this code in a DBMS client with the right privileges is enough to set up completely the database.

Now we have the database, but we still cannot modify it. Assuming that we installed correctly the ERW PHP scripts in a directory served by Apache, we create there a directory named defs, generate the definition files with ertool --defs <library.xml and move the PHP files thus produced to the defs directory. These files contain information used by the PHP run-time environment to produce the forms that handle the database.

Finally, you must set up a configuration file named ERW-conf.php that explains to ERW which kind of DBMS you are using, the name of the database and so on. There is a sample ERW-conf.orig.php file that you can copy and modify.

You now need a way to access the scripts handling form. The ERW scripts include a sample index.orig.php file that can be used as a start page (copying it to index.php). If you do so, accessing with a browser the directory containing the ERW scripts you should see a list of links named as the entities we defined in the ERL file (the list is automatically generated for testing purpose only; the database administrator should set up a nicer way to access the editing forms). Clicking on them will lead you to the editing forms; for instance, to edit books you will get a list looking like this:

Figure 1. An ERW list where you can choose books.

You can browse around, and filter elements (to be true, the filter shown has been customised). Once you find to the book you want to edit, you get to a form looking like this:

Figure 2. An ERW form for a book.

The first input elements allow you to edit the attributes of a book (note that you can upload a description text file). However, the rest of the form is concerned with editing a relation: there is a list of entities (persons that borrowed the book, in this case) and you can create and delete relationships, or change their attributes.

Analogous forms exists for persons, but here we have an interesting feature:

Figure 3. An ERW list where you can choose persons.

Note that you have the choice, when creating a new person, to make a subscriber or not. In general, you can select any of the subtypes of the current entity type. In any case, if you edit a person you will get the right form—a subscriber, for instance, will get something like this:

Figure 4. An ERW form for a subscriber.

You can also have a list of subscribers only: in this case, you can choose to have also cynical filters, such as the amount of donation:

Figure 5. An ERW list where you can choose subscribers.

Finally, in certain cases you may want to edit relationships directly. That is, you may want to browse (with filtering) and modify loans by themselves:

Figure 6. An ERW list where you can choose loans.

The forms thus generated may not really suit your needs. In this case, you can try to customise them. A simple form of customisation, for instance, is localisation: labels and user interface elements can be translated in any language, and the correct language for the user will be negotiated with the browser. However, you can also define your own forms using ERF, an XHTML-like language; here we have a simple, self-explanatory example for a subscriber:


<?xml version="1.0"?>
<!DOCTYPE erf PUBLIC "-//DSI//DTD ERF V1.0//EN" "file://erf.dtd">
<erf ref="subscriber">
  <style type="text/css">
    fieldset { background: #B0B0B0; border: solid black } 
    legend { background: #808080; border: black solid thin }
  </style>     
  <fieldset>
    <legend style="background: #E0E0E0">User Data</legend>
    <input ref="person.fname" size="20"/>
    <input ref="person.lname" size="20"/>
    <input ref="address" size="80"/>
  </fieldset>

  <fieldset>
    <legend>Subscription Data</legend>
    <input ref="card" size="8"/>
    <input ref="donation"/>
  </fieldset>

  <p>You can see loan details by clicking on them. 
  However, you are <em>not</em>
  allowed to modify loan data.</p>

  <list ref="person.loan_book" readonly="true"/>
</erf>

The resulting form would look as follows:

Figure 7. A customised form, with a read-only relationship display.

Essentially, we freely described a page where ERF input elements are replaced by ERW's input controls: besides changing the look of the page using style sheet, we can also set the size of the text inputs, force elements to be read only, and so on.

This example should have given a taste of ERW capabilities. Browsing this manual you can also find how to generate documentation and graphical layouts. To appreciate the power of conceptual modelling, you should think of schemata with hundreds of entities, complex type hierarchies and ownerships, which ERW will handle with the same ease.