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:

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:

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:

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:

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:

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:

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:

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.