Modifications in 2.2
Fields now can be defined as text, checkbox, or selection list.
JavaScript has beed added to the modify fields page to assist in creation of new fields.
e-mail (*@*.*) and URLs (http://*) are automatically converted to links.
 Modifications in 2.1
Administrators can now change the color, header text, field sequence, and sort order of user search results table.
A Customize Reports button has been added to the Administration page.
The reports page has a box for an HTML color or Hex Triplet (#RRGGBB)
The reports page has a large textarea for header code. This can contain HTML tags including links and images.
Admins can click the available fields to choose the sequence of columns in the report table. This also allows
users to omit fields which they would like to leave hidden.
Admins can select the field by which they would like to sort.
Customized User Search pages are no longer restricted by sequence, they are driven by fieldname.
Default input boxes have been expanded to 60 characters.
A 'Delete Found Set' button has beed added to the Administration Search Results, allowing the administrator to delete multiple records.
Modifications in 2.0
A bug has been fixed which prevented MSIE4 users from adding records.
The installer now asks whether visitors should be allowed to add records.
The installer now asks whether visitors should be allowed to search for records.
A bug has been fixed which caused user searches to sometimes be added.
The default line in the data file is now visible so that it can be deleted once data is added
The Admin can now create 'member' accounts in which members can enter a unique password and add, modify, or delete only their own records.
The readme now includes instructions for remote installation without telnet access.
 
 

DIRECTIONS FOR INSTALLATION

Part 1.
Create a directory under your homepage directory
called webdata.  Upload the 2 files,
    install.pl
    webdata.cgi
into the webdata directory.
IMPORTANT: Be sure your FTP program is set to ASCII mode.

Part 2.

Before you run the installer program, you will need to complete this worksheet.  It will be easiest
to write on a printout of this page before running the installer. There is an explanation of each question below the form.

The installer will prompt you for this information.  If you are unsure about any of this, you should contact your
system administrator.

Windows Web Server Users, you only need to answer the questions marked with a [W].
Read the special Windows instructions in Italics below.

[W]1.  Choose a short name for this database.

2.  CGI scripts are stored:
                   ___ 1.  only in the cgi-bin directory
                   ___ 2.  in any directory, so long as the filename ends with .cgi

[W]3.  If you answered 1 above or you are running a Windows Server, what is the path to the cgi-bin

4.  What is the path to Perl 5?

[W]5.  What would you like your password to be?

[W]6.  The ABSOLUTE PATH to the current directory is (path to webdata directory on your server)
What is the URL to the current directory?
(start with http://)

[W]7. The log files contain all of your data, fields, members, and preferences.
For security reasons, we recommend you store these files in a directory which is outside the
viewable web pages.  A typical directory structure might look like this:

                |-----------|
                | top level |
                |___________|
                  /       \
                 /         \
    |----------------|   |---------------|
    | all .html pages|   |    logfiles   |
    | and other web  |   | (not viewable |
    | related stuff  |   |  via the web) |
    |________________|   |_______________|

Your current directory path is (path)
Enter the path to the directory you would like to use for the log files.
If the directory you enter does not exist, the installer will try to create it.
Press [ENTER] to use the current directory.

    It is simple to add or remove field names after you have entered them in, you just need a few to get started.  Keep the names short and simple.
 
 

FIELDS	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________
	________________________  .

Part 3.

When you have completed this worksheet,

Get to a command prompt in the Webdata directory and type
    perl install.pl
Answer the questions using this worksheet.

When you are done, you can point your browser
to webdata/[dbname]_admin.html  to begin adding records.  Where [dbname] is the name you chose in question #1.  You may wish to bookmark that page.
Create a link on your homepage to webdata/[dbname]_form.html
for your guests.  This page allows readers to search (and add to if you selected it) the database, but not modify it.
If you will allow members to modify their own records, members can log in at webdata/[dbname]_members.html
You can also choose to allow new visitors to create their own memberships at webdata/[dbname]_instantmember.html and then add records to the database.  Instant members can log in later at webdata/[dbname]_members.html to modify or delete only their own listings.
 

You must have Perl installed on your server to run Webdata or the installer.  You can
download Perl for free from this site.
http://www.ActiveState.com/software/Perl_for_Win32.htm
NOTE: The IIS webserver takes some configuration to execute Perl CGI scripts.  INSTRUCTIONS
 

Double click on the winstall.pl icon.  A DOS window should appear with some text.
If you have difficulty, be sure the ".pl" extension is associated with Perl.  You can also
launch the winstall.pl program by opening a DOS prompt, cd to the webdata directory,
and type 'perl winstall.pl'  .

Answer the questions using this worksheet.

*****************************************************************************************************

DETAILS ABOUT THE INSTALLATION QUESTIONS

1. Choose a short name for the database

You may change the names of the 2 .htm pages if you wish, but not the log files or the cgi.

2. Do CGI scripts have to go in the cgi-bin directory?

In some cases, you will be required to use a special directory which is not named cgi-bin.  If you have been designated a special directory other than cgi-bin for your cgi scripts, here is what you should do.
 

• Choose Option 1 for this question.
• Enter the path to your special CGI directory for question 3.
• After the installation is complete, you will need to open the two HTML files in the webdata directory.  They are named [dbname]_form.html, and [dbname]_admin.html.  In each of these files you will find a path to the cgi script in the <FORM> tag near the top.  It will look like this:  <FORM ACTION="/cgi-bin/webdata_[dbname].cgi">
• Adjust the path next to ACTION= so that it points to your custom cgi directory.

• Open a telnet session to your web server.
• Go to question 4, get the path to Perl on your system.
• Copy the following text to a simple text editor such as Notepad.

#!/usr/bin/perl
#
print "Content-type: text/html\n\n";
print "<H1>Hello World</H1>";

• Replace the words /usr/bin/perl with the path to Perl on YOUR system.
• Save the file as hello.cgi
• Upload hello.cgi to your web server

      (Be sure the FTP program is set to ASCII, not binary mode)
• Change to the directory on your server which contains hello.cgi.
• Type chmod a+rx hello.cgi and press [ENTER].

Point your browser to hello.cgi the same way you would to view an html page.
 
• If all 4 lines of the program appear on the screen, the answer is 1 - cgi scripts must live in a cgi-bin directory. Check option 1 and proceed to find the cgi-bin.
• If Forbidden or Permission Denied appears on the screen, type the chmod command again. If it still appears, the answer is 1 - cgi scripts must live in a cgi-bin directory.
• If Hello World appears on your screen, the answer is 2 - CGI scripts can live anywhere, so long as the name ends with .cgi.
• If Server Error appears on your screen there is a mistake in the code, or it was not uploaded in ascii mode. Either way, since the program even tried to run, the answer is 2 - CGI scripts can live anywhere, so long as the name ends with .cgi.

3. Locating the /cgi-bin/ directory

 find / -name cgi-bin -print |& grep -v denied

[W]Windows users - you know where your file search tools are.

4. Locating the Perl 5 program

The installer will automatically detect Perl 5 if it is in any of the default locations.  If it finds it, it will notify you that it found Perl 5, and skip to the next question.

From the command prompt, type  which perl and press [ENTER].

Hopefully, the system returned a line similar to this:

/usr/bin/perl
or
/usr/local/bin/perl

Write down the result.  This is the location of Perl on your system, and you will need it.

If the system did not return a result, try this:
 

Type whereis perl and press [ENTER].

Again, you are looking for a path similar to the ones described above.  You may get several results, but only one should end with just perl and nothing else. Write down the result if you get one.

5. What would you like your password to be?

6.  The ABSOLUTE PATH to the current directory is (path to webdata directory on your server)
What is the URL to the current directory? (start with http://)
[W] read this...

In other words, what would you type into the location box of a web browser to see this directory?

For example, if I had a domain named "myserver.com" and all of my web pages were under the /user/myname/htdocs directory:
The installer would probably tell me that the absolute path to the current directory is /user/myname/htdocs/webdata
and I would type:  http://www.myserver.com/webdata into the  installer at this time.

NOTE: If you do not have telnet access and you will be using the FTP installation web page, you will need to create a folder in the same directory as the webdata html pages named uploads.  Enter the absolute path (begins with a slash or drive letter) to the uploads directory in box 6a, enter the URL (begins with http://) to the uploads directory in box 6b.

7. The log files contain all of your data, fields, members, and preferences.
For security reasons, we recommend you store these files in a directory which is outside the
viewable web pages.  A typical directory structure might look like this:

                |-----------|
                | top level |
                |___________|
                  /       \
                 /         \
    |----------------|   |---------------|
    | all .html pages|   |    logfiles   |
    | and other web  |   | (not viewable |
    | related stuff  |   |  via the web) |
    |________________|   |_______________|

Your current directory path is (path)
Enter the path to the directory you would like to use for the log files.
If the directory you enter does not exist, the installer will try to create it.
Press [ENTER] to use the current directory.

[W] read this...

Using the example in question 6, if all of my web pages were under the /user/myname/htdocs directory, I might choose to enter:
/user/myname/webdata_logs into the installer at this time.  The installer will create a directory named webdata_logs at that location if I (the person that executed the program) have permission to do so.  The advantage to this configuration is the webdata program will be able to read and write to the log files, but the log files will not be accessable via the web directly.

If you do not have telnet access, obviously the installer cannot create this directory for you.  Create the directory using your FTP program, then enter the absolute path (begins with a slash or a drive letter) into the box on the FTP installation web page.
 

8. What field names would you like in your database?

MANUAL INSTALLATION

You will not need to edit the webdata_[dbname].pl script unless you have difficulty with the automatic installer.  In that case, the following diagram shows a sample installation.

Customizing Webdata

 To Customize the User Search page
The page you will link users to is called [database name]_form.html.  It will automatically query the Webdata CGI to read your list of fieldnames, and generate a search form "on-the-fly."  The advantage to this method is that if you should change your list of fields, the user search form will automatically reflect those changes.  The disadvantage is that it creates a rather plain beige screen, without your site's text and graphics.  You can save this page and modify it to match the look and feel of your site.

1. Point your browser to [dbname]_form.html

The program should create a user search form.
2. Choose SAVE AS from the FILE menu, and choose a name and location for the custom form. For example, you may call it "search.html"
3. Open the custom form you just saved in any text editor and make changes.  You may add titles, images, and text anywhere you wish.  There are just a few rules you need to keep in mind:
• If your server uses a cgi-bin, you will need to redefine the "ACTION=" in the <FORM> tag.

Replace the text
  ACTION="webdata_[dbname].cgi"
with
  ACTION="/cgi-bin/webdata_[dbname].cgi"
• Do not change the names of the fields. They must be identical (case sensitive) to the field names as they appear on the administration page.
• Do not change the name or value of the submit buttons.  They must pass the name/value pair "cgifunction=Search" or "cgifunction=Add" to the script.
4. Upload the page to your server and enter the URL of your new search page into the box labeled "If you would like to use a customized search page" on the "Customize Pages" screen.

To customize Search Results
Go to the [dbname]_admin.html page, enter your password. When the administration page loads, click on 'Customize Pages'. Here you can change the color, add header HTML code, select which fields to display in what column sequence, choose a sort order, number of results per page, and whether to display the "view" button and what it should be labeled.
With version 2.28, Webteacher's Webdata is 100% customizable to match the look and feel of your site.  See "Using Templates" further down.
When you have made your selection, click 'Modify Report' and wait for the page to reload. Then follow the link to the user's search page to see your modifications.

The "view" button is a good tool for databases that have a lot of fields.  If you cannot display all of the information in a single row of the results table, simply choose only the 3 or 4 most descriptive fields in the "column-sequence" box.  Then, check the "view button" checkbox.  When a user searches your database, he/she will see a concise list of search results, each with a "view" button.  Clicking on the "view" button will display all the information about that record.

---

Instructions for general use

Creating lists, comment boxes, checkboxes, text boxes, and upload fields.

When you have defined your upload field, you will notice that any screen that is used for adding records now has a "browse" button next to that field.
Simply click the browse button and select your file, and it will be uploaded when you add the record.  Then, when the user searches the database, if the file is an image, the image will be displayed.  If the file is of any other type, the file's name will appear as a link to view the file.  How the file is viewed is up to the user's browser settings for that file extension.

How it works:
The files are stored in the 'uploads' directory using the following naming structure:  [recordID]_[fieldname]_[filename].[ext].
The URL to the file is stored in the field.  This can be clearly seen when searching as admin, and the URL can be manually adjusted
in the maintenance screen if necessary.

During searching, if the URL ends with .gif or .jpg, the program will simply display the image.  If the URL ends with anything else, and
the field is defined as an upload field, the program will display only the last part ([filename].[ext]) as a link to the entire URL.

---

Adding Members

Members can go to the [dbname]_members.html page to gain access to their records.

NOTE: Both the administration pages and the member pages use cookies to avoid prompting for a password more than once.  The cookies will expire each time you exit your browser.  If you are logged in as an administrator, and you wish to test the member pages, you will need to log in from the [dbname]_members.html page  to see the effects.  Members that share a terminal should be warned to exit the browser when they are finished.

If you check "allow instant members" in the admin preferences, first time users can come to the [dbname]_instantmember.html page, choose a username and password, and then begin adding items to the database.  They may return to the [dbname]_members.html page later and log in to add, modify, or delete their own listings, but they cannot effect anyone else's information.

Adding pictures and links

The search results are displayed inside an HTML table.  All HTML commands will work inside the table with the exception of SSI .  You can display a word in bold by simply typing <B>my text</B>.

Now in version 2.25, a field that contains only a URL will automatically be converted to an <A HREF> link when the user search is displayed.
A field that contains only an e-mail address will will be converted to a mailto: link.
A field that contains only a string of text ending with .gif or .jpg will automatically be converted to an <IMG> tag.

To add a picture, you may use either an absolute URL (begins with http://) or a filepath relative to the cgi script.  So, for example, if my website looked like this:

                   myaccount (at http://www.myaccount.com)
                  /         \
              htdocs         cgi-bin
             /   \                |
       images   webdata     webdata_[dbname].cgi
         |
      duck.gif
      swan.gif
      goose.gif

I could enter the image either of these 2 ways.
http://www.myaccount.com/images/duck.gif
or
../htdocs/images/duck.gif

NOTE: You may still enter an <IMG> tag manually if you would like to add special parameters such as "width=72" or "border=2".
 

Using Templates

Creating a template for the list of search results
If you don't like the table format which is Webdata's default, you can design your own layout for each found record.  Let's say that the user searches for Ford Explorer, and we have 3 of them.  I want the user to see a pattern that I design, like this:
 

Make: Ford	Model: Explorer	Year: 1997
Extras:  PL PW PS ABS CRUISE TILE CD		Price: $17285

I want to see three of these data blocks, because 3 cars came up when we searched for Ford Explorer.  Here's what I would do:
1. Use any HTML editor or word processor to make a page that looks just the way I want using sample data.
2. Go through the HTML code I just created with a word processor, and make the following substitutions:

I locate the word "Ford" or whatever the first piece of text is that will be replaced by data from the database.
I look on the conversion chart above the 'search template' box, you will see the word $data[#] next to every field in our database, with a
different number in each one.  If 'MAKE" is the first field, the substitution code for it will be $data[0].  Simply take out the word "Ford" or whatever
we used for sample data, and insert the text: $data[0] .  That's all there is to it.  In our example, wherever the template sees the word $data[0] it will insert the Make of the vehicle it is displaying.  Likewise, if Price is the fifth field, I would look it up on the conversion chart and see that it corresponds to "$data[4]".  Therefore,
wherever I type $data[4] in the template, the price of the current vehicle will be displayed.

Finally, there is the view button.  First, you will see a box on the 'customize pages' screen where I may enter the label of the 'view' button.  I would type 'Click here for details' into that box.  Then, where I want the button (and the form tags around it) to go, I would enter the word $viewbutton.  The template will automatically replace the word $viewbutton with the tags: <FORM><INPUT TYPE=BUTTON VALUE="(what you chose)" onClick="(script to get the form)"></FORM>.

In our example, the text I paste into the search template box on the 'customize pages' screen might look like this:
<TABLE BGCOLOR="lightblue">
<TR>
      <TD><B>Make:</B> $data[0] </TD>
      <TD><B>Model:</B> $data[1] </TD>
      <TD BGCOLOR="beige"><B>Year: </B> $data[2]</TD>
</TR>
<TR>
      <TD BGCOLOR="beige" COLSPAN=2><B>Extras:</B> $data[3]  </TD>
      <TD><B>Price:</B> $$data[4] <./TD>
</TR>
<TR>
      <TD BGCOLOR="pink" COLSPAN=3 ALIGN="center"> $viewbutton </TD>
</TR>
</TABLE>
 

Technical Notes

• [dbname]_form.html - This page uses the location.replace() JavaScript method to forward the visitor to the correct CGI location without disabling the BACK button.  If you do not wish to use JavaScript, make a copy of the CGI results from this page.  See 'Customizing Webdata' above for instructions.
• [dbname]_admin.html - This page prompts the user for a password, then calls the CGI to return the main Administration page.
• [dbname]_members.html - This page prompts members for a username and password, then calls the members page, from which members can add or modify their own entries, but not any other records.
• [dbname]_instantmember.html - If you check "allow instant members" in the admin preferences, users can come to this page, choose a username and password, and then begin adding items to the database.  They may return to the "[dbname]_members.html" page later and log in add, modify, or delete their own listings, but they cannot effect anyone else's information.
• [dbname]_members.log - This file stores the username and passwords for member accounts.  The passwords are encrypted with Perl's crypt() function.
• index.htm - This page simply forwards the user to the [dbname]_form.html page.  Feel free to replace it with any welcome information you wish.  It is created primarally as a security measure prevent users from seeing the contents of your webdata directory.
• [dbname]_fields.log - This is your list of fields.  You should never need to open this file.  The field list should be edited with the 'MODIFY FIELDS' button on the main administration page to ensure that the proper sequence is maintained.  The format for each field is the fieldname, then a double colon, then the field type (text, checkbox, or list), then a single colon, then for text boxes the number of characters, for lists, a comma delimited list of values.
• [dbname]_report.log - This contains the page color of your user search form and search results, any header HTML, the sequence of fields, the field number for sorting, the number of results per page, and dozens of other preferences.
• [dbname]_data.log - This is the delimeted text file of all of your data.  If for some reason you find that you need to make an edit without using the Webdata interface, you may open this file in any (plain) text editor and make your changes.  For example, if you wish to change a large quantity of records at one time, it will be faster to use MS Word's auto-replace, than to select and delete each one individually in Webdata.  You should always backup a log file before making changes to it.
• webdata_[dbname].cgi - This is the main engine of the database.  The database name appears at the end so that multiple Webdata programs will be clustered together in the cgi-bin.  Here is a brief synopsis of how the program works:

 
Every time the Webdata program is called, it uses the readparse subroutine to import the CGI data and assign it to the $user_data{} and @value array.

It then assigns the user customized variables located in lines 7-15.  This tells the program the correct location of the datafiles, the password, the name of the cgi program, and where to send the homepage links, where to send the "search again" link for users, and how many results to display to users.

The program then executes one of the 18 subroutines, depending on the value of "cgifunction".
 

  http://www.dynamicnet.net/support/fp/perlwithPWS.htm
   Thanks to Dynamic Net for providing these instructions.
 

Instructions for beta testing the ODBC routine
The ODBC routine is commented out because we could not identify the cause of some connection failures during testing.  If you would like to
try it, you are welcome to, but please do not complain to us if it doesn't work.  You must have the Win32::ODBC module to use this routine.

LOCATE the following lines and remove the # from the beginning of each line (except the first and last):
#*********** BEGIN ODBC ********************
#print "
#<P><HR><P>
#<B>Use an ODBC Database instead of Webdata's datafile.</B>
#<INPUT TYPE=CHECKBOX NAME=\"usesql\"";
#print " CHECKED" if $usesql==1;
#print "><BR>
#<I>You must have the Win32::ODBC module to use this option.</I><BR>
#<B>DSN Name</B> <INPUT TYPE=TEXT SIZE=20 NAME=\"dsn\" VALUE=\"$dsn\"><BR>
#<B>Table Name</B> <INPUT TYPE=TEXT SIZE=20 NAME=\"tablename\" VALUE=\"$tablename\"><BR>
#<B>Primary Key</B> <SELECT NAME=\"primarykey\">\n";
#$count=0;
#foreach (@fields) {
#  print "<OPTION VALUE=\"$count\"";
#  print " SELECTED" if $count eq $primarykey;
#  $count++;
#  print ">$_";
#}
#print "\n</SELECT>
#";
#************ END ODBC **********************

Then, you should be able to define a DSN in your ODBC control panel, and enter the DSN name and table name in the appropriate boxes on the 'customize pages' screen.  Modify your Webdata fields to match the fields in your ODBC table exactly.  Case counts.
 

Running Multiple Databases

You should install all of your databases such that the webdata_[dbname].pl scripts are in the same directory.  On most servers they would all go in the cgi-bin anyway.
Register the first database you install, once you are satisfied that Webteacher's Webdata will meet your needs.  Then, in each additional database, click on
"Customize Pages", and scroll down to the bottom of the page.  Enter the name of the webdata_[dbname].pl file for the registered database, and the new database will become registered as well.