Menu ▾ ▴

People database Log in to Edit

People database

This database is a demo application for WODA, which demonstrates some features and provides a template for end-user applications. It is a web based address-book. This page contains what we call a "database definition file", it's a short text file, describing the database content.

You will find comments and explanations after the database definition file, below. You may find it cryptic, but don't be scared, it is very simple and you don't need to know any programming language to understand it. More, Woda can [generate] this file for you.

Code

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
#!/usr/bin/perl

# this file defines a Woda application
# 1) change the first line to point correctly
# 2) change the two lines below to point correctly
# 3) make sure it points to correct (.pl or .pm) version!

# woda-max.pl is the slower but more robust engine

#require "/var/www/woda/en/woda.pl" unless defined &main;
require "/var/www/woda/en/woda-max.pl" unless defined &main;

#
# Database definition:
#

# it is possible to live without the next setting

$WBB{'dataDir'} = '/var/www/www/wdat/people';

# more settings

$WBB{'dbTitle'} = 'Staff of the XYZ corporation';
$WBB{'about'} = 'This database is a demo application for WODA,
which demonstrates some features and provides a template for end-user applications.';
$WBB{'recordTitle'} = 'Personal data';
$WBB{'manager'} = 'Joe Manager';
$WBB{'managerEmail'} = 'joe.manager@fagg.uni-lj.si';

$WBB{'key'} = '"$rec{username}"';

$WBB{'sort;DEFAULT'} = '"$rec{lastName};$rec{firstName}"';
$WBB{'format;DEFAULT'} = <<'PERL';
# this is a perl expression returning a string
# returns a link if homePage is defined
$rec{homePage} ?
"<A HREF=$rec{homePage}>$rec{firstName} <B>$rec{lastName}</B></A> (<A HREF=mailto:$rec{email}>$rec{email}</A>)"
:
"$rec{firstName} <B>$rec{lastName}</B> (<A HREF=mailto:$rec{email}>$rec{email}</A>)"
PERL

#
# Field definitions:
#

$i=1000;        # counter

$x='firstName';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/[A-Za-z\-\. ]{1,40}/';
$WBF{$x,'cond'} = '1-40 US letters, dots and dashes!';
$WBF{$x,'help'} = 'Enter the first name followed by any middle initials e.g. <I>John F.</I>';
$WBF{$x,'picture'} = '"<BIG>$_</BIG>"';

$x='lastName';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/[A-Za-z\-]{1,40}/';
$WBF{$x,'cond'} = '1-40 US letters, dots and dashes!';
$WBF{$x,'help'} = 'Enter last name. If You have two, separate them with a dash e.g. <I>Martin-Smith</I>';
$WBF{$x,'picture'} = '"<BIG>$_</BIG>"';

$x='username';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'p'} = 'Username';
$WBF{$x} = 'm/[a-z]{2,8}/';
$WBF{$x,'cond'} = '2-8 small US letters';
$WBF{$x,'typePar'} = 'SIZE=8';
$WBF{$x,'help'} = 'Enter your username.';

$x='picture';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/gif$|jpg$|^$/';
$WBF{$x,'type'} = 'IMAGE';
$WBF{$x,'help'} = 'Adding an image is optional. But if you have one, upload it!';

$x='resume';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/pdf$|doc$|^$/';
$WBF{$x,'type'} = 'USERFILE';
$WBF{$x,'help'} = 'Adding a resume in .pdf or .doc format is also optional. Hey, this is a demo!';

$x='about';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'HTMLAREA';
$WBF{$x,'typePar'} = 'RICH ROWS=15';    # rich text html editing possible
$WBF{$x,'p'} = 'Tell us more about yourself!';

$x='title';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'OPTION';
$WBF{$x,'typePar'} = 'RADIO';
$WBF{$x,'options'} = 'Mr.|Mrs.|Ms.|Miss|M.S.|Dr.|Asst.Prof.|Assoc.Prof.|Prof.|Acad.Prof.';

$x='email';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'d'} = 'info@fagg.uni-lj.si';
$WBF{$x,'type'} = 'EMAIL';
$WBF{$x,'sticky'} = '1';
$WBF{$x,'help'} = 'Enter your email address.';

$x='topic';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'p'} = 'Classify the area of your expertise';
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'OPTION';
$WBF{$x,'typePar'} = 'TREE MULTIPLE CHECKBOX';
$WBF{$x,'options'} = '
mathematics
mathematics:algebra
mathematics:analysis
mathematics:geometry
physics
physics:mechanics
physics:nuclear
physics:nuclear:particle
physics:of materials
geodesy
civil engineering
civil engineering:structural
civil engineering:concrete
civil engineering:metal
civil engineering:metal:steel
civil engineering:metal:aluminum
information technology
information technology:programming
information technology:programming:C
information technology:programming:Perl
information technology:programming:Ada
';

$x='homePage';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'URL';
$WBF{$x,'help'} = 'If you have a home page, enter it here.';

$x='break';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'type'} = 'BREAK';
$WBF{$x} = 'Other data';

$x='relatives';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'COMPUTE';
$WBF{$x,'picture'} = '"<A HREF=$SCRIPT/search?search=$rec{lastName}>Find your relatives</A>"';

#
# now let woda handle this!
#

do main();

Comments

Comments are a work in progress, not yet completed...
Those comments are like a tutorial for beginners. But you shouldn't start by reading them. Just copy what is done in the script. Then you will want to understand.

Perl and Woda path

Woda database are defined in a databases definition file. Basically it is a simple text file with a list of fields.
Actually, Woda databases definition file are simple Perl scripts. Perl scripts starts with what is called a shebang (#!), followed by the path to the Perl interpreter. The first line must start like this :

#!/usr/bin/perl

In Unix/Linux world, Perl is usually installed at /usr/bin/perl. Your web provider should have documented this. On your workstation, open a terminal and type which perl, then press Enter to find Perl. It will return the path.

In Perl scripts, all lines started with a sharp "#" symbol are comments and are ignored. They are not interpreted nor displayed on screen. The demo file contains some comments to help you understand what is done.

# this file defines a Woda application
# 1) change the first line to point correctly
# 2) change the two lines below to point correctly
# 3) make sure it points to correct (.pl or .pm) version!

As with Perl path, we need to indicate the path to the Woda engine.
The place where you put Woda is not important, but if possible, it shouldn't be accessible through the web, thus it should be outside the web root. Here, I've installed Woda locally on my personal Linux box. I chose to put my web root at /var/www/www and the Woda files in /var/www/woda. I chose the english based Woda engine, hence the path is /var/www/woda/en/woda-max.pl (forget the unless defined &main for now).

require "/var/www/woda/en/woda-max.pl" unless defined &main;

And finally, 2 important points:

  • as it is a Perl script, all lines are treated as Perl instructions and must end with a semicolon ";"
  • we use the require Perl built-in function to indicate the Woda path

Woda instructions

Now, we start with the Woda instructions. But don't forget that this is a Perl script, each lines must end with a ";"!
We will set database definition parameters (sometimes called "database attributes" or "database settings") and fields definition parameters (or "field attributes", "field settings"). Each sort of parameters start with an easy to remember identifier:

  • $WBB for the database - think WBBase
  • $WBF for the fields - think WBField

The syntax is 

$WBB{'nameOfParameter'} = 'something';

don't forget the braces {}, the quotes ' ' and the semicolon ;.

Database definition

We put some comments to help reading the file.

#
# Database definition:
#

The data directory

Another path! this is the last one... it defines the data storage directory. As with the woda engine, it is better to store the data in a place outside the web root. But for a first sample, you will not store important informations in it, will you? so choose the easier path for you, and Woda will create the directory.

$WBB{'dataDir'} = '/var/www/www/wdat/people';

The name of the data directory is not important. It could be X1234. The choice of "people" here, seems logical because it reflects the name of the database definition file, and the database purpose.
This parameter is not required but sometimes Woda create it in a bad place. If you don't set it, Woda will create the directory named after the definition file.

Database description

We add a title for the database, a short description, and a nice title for adding new record. This will help the users. Note that each setting is clearly identified with a Woda keyword. Available keywords are listed in the built-in documentation, available through the AdministrationMenu and on this web site on the ConfigurableParameters page.

$WBB{'dbTitle'} = 'Staff of the XYZ corporation';
$WBB{'about'} = 'This database is a demo application for WODA,
demonstrates some features and provides a template for end-user applications.';
$WBB{'recordTitle'} = 'Personal data';

We give users the possibility to contact someone if the database failed. The Woda engine can also use the managerEmail to send periodical informations.

$WBB{'manager'} = 'Joe Manager';
$WBB{'managerEmail'} = 'joe.manager@fagg.uni-lj.si';

The unique key

Information in a database is grouped in records. Each record has an unique identifier, called an id or a key. If not defined, Woda will create it randomly on the fly, as a 4 symbol identifier, mixing letters and digits, like nacl or h2g2.
Here we use a field as the identifier. the field is defined some lines below, but it doesn't matter. Defining the unique key with the username field guarantee that the content of the username field will be unique. It is useful for the purpose of this little database, where each record will contain personal datas including the unique username, which may be used to connect somewhere.

$WBB{'key'} = '"$rec{username}"';

The $rec{nameOfField} syntax identifies a field of a record. It is enclosed in double quotes, that means that it will be replaced by the corresponding value for each record, we say that it is evaluated, it is not literally copied.

Presenting search results

Woda has built-in default sorting and formatting for the search results. You can also define your own.
We use Perl expressions, like above for the unique key. A Perl expression is evaluated (the result is calculated) and replaced by the result. Again, it is double quoted. Note that the entire expression is also quoted - yes, like above. Quotes are a mandatory syntax for Woda parameters.

As the names indicates, this is a default sorting:

$WBB{'sort;DEFAULT'} = '"$rec{lastName};$rec{firstName}"';

We define a sort using at first the lastName field and second the firstName field.

And below is a default formatting, a bit more complicating. That's because we want to display a conditional link to a www home page. We check to see if the field homePage has a value (field is empty or not):

$WBB{'format;DEFAULT'} = <<'PERL';
# this is a perl expression returning a string
# returns a link if homePage is defined
$rec{homePage} ?
"<A HREF=$rec{homePage}>$rec{firstName} <B>$rec{lastName}</B></A> (<A HREF=mailto:$rec{email}>$rec{email}</A>)"
:
"$rec{firstName} <B>$rec{lastName}</B> (<A HREF=mailto:$rec{email}>$rec{email}</A>)"
PERL

The particular <<'PERL'; syntax indicates that the Perl expression will expand on more than one line, until a line starting by PERL. Note the comments and the html code inside the Perl expression.
The Perl syntax is simpler that it looks like. It can be understood like:

code explanation
$rec{homePage} ? is there a value in that field ?
"perl expression" if yes, print this
: or
"perl expression" no? else print that

Field definitions

Remember ? we wil use $WBF for the fields parameters (think WBField).

Again, the file is more readable if we put some comments in it.

#
# Field definitions:
#

First, we define a counter to assist in generating a standard sequence for the display of the fields. It makes things easier when we let the computer do the job! Of course you can omit that line and define a number for each field. The counter is used to define the order in which the fields will be displayed, higher numbers are displayed first.

$i=1000;        # counter

The counter is a comment. Comments can be placed at the beginning of the line or at the end, after the ";"

A typical field

And now, our first field!
A field is not only defined by its name. A field can have some parameters restricting what can be entered, explaining the meaning of the field to the user, defining how to print the field, etc. We will see some of them.

$x='firstName';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/[A-Za-z\-\. ]{1,40}/';
$WBF{$x,'cond'} = '1-40 US letters, dots and dashes!';
$WBF{$x,'help'} = 'Enter the first name followed by any middle initials e.g. <I>John F.</I>';
$WBF{$x,'picture'} = '"<BIG>$_</BIG>"';

Quite complicated? well, yes and no. If you look at the script, each field have similar settings, and if you read the quoted values, a lot of settings are a help for the user.
Let's detail this below.

Naming a field

Below is the name of the field. We use a variable named $x to store the name, because we don't want to type it more than once. You can omit that line, but you will need to type the name for each field setting. That is, replacing each $x with firstName. As for the counter, let the computer do the job!

$x='firstName';

The advantage of using camel-case naming is that Woda will insert a space before each uppercase letter in the field's name. That's why we use a syntax like firstSecond. You can do what you want: write the name like us, use dashes "-", underscores "", but _not spaces. The name of the field must not include spaces.

Now we put a comment with a dashed line, because we like to ease the reading, it is simply a visual aid.

# ------------------------------

Decreasing a variable

You will find the line below exactly repeated for each field. It is only the counter. Above we have defined a counter using the $i variable. Now we define an order for the field: we say that we want to sort (the srt) the firstName field (the computer will replace $x by firstName) according to the $i variable. 

$WBF{$x,srt}=$i--;

The sort value is now 999. Why? because at first $i was 1000, but we have added double dashes. That means we want to decrease the $i value of 1 unit.

Controlling the content of a field

We want to restrict what may be entered into the field. We use two parameters for that. One will be understood by the computer, one by the humans. If you don't understand the line 52, you are a human.
The parameter at line 52 is actually the only mandatory parameter for a field. This parameter is named with the field name only (it will replaced the $x variable). The next parameter explain the conditional value to the user.

$WBF{$x} = 'm/[A-Za-z\-\. ]{1,40}/';
$WBF{$x,'cond'} = '1-40 US letters, dots and dashes!';

Line 52 is a RegularExpression, a very useful but rather cryptic subset of perl expressions. It means exactly what is written in plain english at line 53: you can type [ any english letter, lower and upper case A-Za-z, dashes -, dots . and spaces * ], and the field must contain at least 1 character and no more than 40 characters {1,40}*.

Let's help the user to understand what should goes in that field:

$WBF{$x,'help'} = 'Enter the first name followed by any middle initials e.g. <I>John F.</I>';

If there are no conditions for data entry the value of $WBF{$x} would be 

$WBF{$x} = '1;'; # <-- note the semicolon within the value

The semicolon is required to signal to Woda that the value is an expression that should be evaluated, otherwise it is interpreted as a string and the result may not be what you would expect.

And finally the picture parameter define a particular display of the field on the web page. We want big letters. 

$WBF{$x,'picture'} = '"<BIG>$_</BIG>"';

It is a perl expression (double quotes). We use the special _$__ variable. It always contains the value of the current field.

The other fields

We will not comment every lines.

Next field is similar to the first one, except the name.

$x='lastName';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/[A-Za-z\-]{1,40}/';
$WBF{$x,'cond'} = '1-40 US letters, dots and dashes!';
$WBF{$x,'help'} = 'Enter last name. If You have two, separate them with a dash e.g. <I>Martin-Smith</I>';
$WBF{$x,'picture'} = '"<BIG>$_</BIG>"';

Note the $i value at line 59. At first, the $i variable was set to 1000, then the double dash syntax in firstName field definition decrease its value to 999 ((line 51). And now, the same double dash syntax decrease its value again. Guessing what it is? The field is numbered 998.

Adding html parameters with typePar, writing a simple regular expressions

The third field contains 2 new parameters and a different RegularExpression.

$x='username';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'p'} = 'Username';
$WBF{$x} = 'm/[a-z]{2,8}/';
$WBF{$x,'cond'} = '2-8 small US letters';
$WBF{$x,'typePar'} = 'SIZE=8';
$WBF{$x,'help'} = 'Enter your username.';

The p parameter is a short prompt for the user, generally printed above the field. Think of it like a quick help.
typePar is used to pass additional parameter, specific to a type of field. When there is no type setting, field is assumed to be a standard input field, as in html forms. Here we use typePar to pass an html parameter to the form input.
The RegularExpression m/[a-z]{2,8}/ is explained at the next line (cond setting). It is not very different than the first we encountered. Actually, it looks like more simple:

  • what is enclosed in brackets [a-z] define a range of letters, in alphabetical order ; here we define the entire alphabet. If we would have writed [b-h] only b, c, d, e, f, g and h letters would be allowed.
  • {2,8} means that one must type in at least 2 and no more than 8 characters
  • the m/ / syntax means that the input must match (that's the meaning of the m) what is between the slashs /

Special types of fields

Next fields use a type setting. Above, there was no type setting for fields, as it was assumed to be standard default type, which is like INPUT html form. You will use this default standard INPUT type all the time.
But there is allway special cases, where you want to build something different. Next fields describes the other types.

Sending files (IMAGE, USERFILE)

Below we define 2 fields that allows users to send files in the database. A special input form will be displayed that will allow user to chose a file on his computer, this file will be uploaded to the database. I'm sure you already seen something similar on the web.

The field is of IMAGE type. The uploaded file will be displayed as an image. Self-explanatory.

$x='picture';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/gif$|jpg$|^$/';
$WBF{$x,'type'} = 'IMAGE';
$WBF{$x,'help'} = 'Adding an image is optional. But if you have one, upload it!';

The regular expression that we use to control the uploaded content is a bit more complicated than before. Just note that we allow only gif or jpg images.

This field is of USERFILE type. It works like IMAGE type for uploading, but the uploaded file will be displayed as a link. One will be allowed to retrieve it from the database to its computer..

$x='resume';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = 'm/pdf$|doc$|^$/';
$WBF{$x,'type'} = 'USERFILE';
$WBF{$x,'help'} = 'Adding a resume in .pdf or .doc format is also optional. Hey, this is a demo!';

Again, the regular expression allows only pdf or doc files.

The other fields

$x='about';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'HTMLAREA';
$WBF{$x,'typePar'} = 'RICH ROWS=15';    # rich text html editing possible
$WBF{$x,'p'} = 'Tell us more about yourself!';

This field is of HTMLAREA type. Combined with the RICH typePar directive it will display a word-like text editor formating.

$x='title';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'OPTION';
$WBF{$x,'typePar'} = 'RADIO';
$WBF{$x,'options'} = 'Mr.|Mrs.|Ms.|Miss|M.S.|Dr.|Asst.Prof.|Assoc.Prof.|Prof.|Acad.Prof.';

An OPTION field, offering users a choice between predefined values. Only one value can be selected at a time (RADIO typePar). Values can be separated by pipes or by a newline, like in the topic field below.

$x='email';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'d'} = 'info@fagg.uni-lj.si';
$WBF{$x,'type'} = 'EMAIL';
$WBF{$x,'sticky'} = '1';
$WBF{$x,'help'} = 'Enter your email address.';

An EMAIL field with a default value (the d parameter) that users can change. Email syntax will be checked. The field is shown as a Javascript generated link to prevent spammers to use it.

$x='topic';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'p'} = 'Classify the area of your expertise';
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'OPTION';
$WBF{$x,'typePar'} = 'TREE MULTIPLE CHECKBOX';
$WBF{$x,'options'} = '
mathematics
mathematics:algebra
mathematics:analysis
mathematics:geometry
physics
physics:mechanics
physics:nuclear
physics:nuclear:particle
physics:of materials
geodesy
civil engineering
civil engineering:structural
civil engineering:concrete
civil engineering:metal
civil engineering:metal:steel
civil engineering:metal:aluminum
information technology
information technology:programming
information technology:programming:C
information technology:programming:Perl
information technology:programming:Ada
';

This special OPTION field allows MULTIPLE values to be selected. Each value begin on a new line. The database home page will show a link to a TREE display of this field with counted values. Note the : separator, which will create the TREE branches.

$x='homePage';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'URL';
$WBF{$x,'help'} = 'If you have a home page, enter it here.';

URL field for internet links (web adresses).

$x='break';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x,'type'} = 'BREAK';
$WBF{$x} = 'Other data';

This one is not a real field, but a separator.

$x='relatives';
# ------------------------------ 
$WBF{$x,srt}=$i--;
$WBF{$x} = '1;';
$WBF{$x,'type'} = 'COMPUTE';
$WBF{$x,'picture'} = '"<A HREF=$SCRIPT/search?search=$rec{lastName}>Find your relatives</A>"';

Again, not a real field. Nothing to enter here. But an easy way to display a COMPUTED value with records.

#
# now let woda handle this!
#

do main();

See more on [Field types]

Related

Documentation Wiki: Commented samples
Documentation Wiki: Field types
Documentation Wiki: Home