Library Web Chic

I’ve spent a lot of time the last month working to get ETD-db up and running. One frustration I’m having with this process is the lack of documentation concerning how to customize the system. So I’m going to post some of my notes from my install and customization process.

Installation

The installation instruction for ETD-db while complete are not particularly enlightening if you want to install the software in a different place from what the software reccomends. Particularly if you want to install the Perl scripts of ETD-db in a different place (ie your cgi-bin). You can move things around but if you do you need to edit the etd-master-lib.pl which typically lives at the top level of your ETD-db cgi-bin files. Also if you change where you put the files this will also change the instructions for creating Script Aliases

Another installation problem I encountered was where ETD-db thought Perl was located on my system. This can quickly be fixed by creating a symbolic link from where ETD-db wants Perl to be to Perl’s actual location.

It is also important to note that when you change the location of the files, this may break Perl code that includes other Perl files (typically these are lines that say ‘required …’). Most notably this happens to the non-cgi-bin files. This is very fixable. Look for lines that say:

unless ($cgi_system_root) { $cgi_system_root = “/export/ETD-db”;}
require “$cgi_system_root/non-cgi-scripts/etd-non-cgi-lib.pl”;
and change them to

require “etd-non-cgi-lib.pl”;

Once you’ve installed ETD-db you probably want to customize it in some ways. However, the documentation on customization is a bit sparse. Below are some tips I’ve garnered via our customization process.

Customization

There are several places one should look in order to customize various screens in ETD-db. Where you look to customize a screen depends on if that screen is an HTML page or being generated by a Perl script. Most of the screens within ETD-db are created by Perl scripts. However some are HTML files which you need to edit. The most important of these are the index.html file which controls the main ETD-db page and the HTML file located in the help directory.
If the screen you want to alter is created by a Perl script, the first place is the /language/english directory. There are many “message” files here which govern what the screens look like and the information that appears on them. The first thing you need know is that ETD-db has groups its screens by the “process” which is taking place. These processes corresponded to particular Perl scripts that live in the ETD-db directory structure. Below is a list of the ETD-db processes, the corresponding directories and message files.

Remember that if you want to change a something about a particular screen for example you want to change how the “Add Advisor” screen works that there is an add advisor screen present in all of the following processes (Submit an ETD, Manage available ETDs, Review submitted ETDs, and Manage withheld ETDs) so you will need to change it in all these places.

The /language/english directory also contains a global_messages.pl file that control some universal things like the header and footer for each of the screens. It also contains the non-cgi_messages.pl file which is used by the scripts in the non-cgi-script directory and controls the output created by these scripts.

Most of the HTML generated by ETD-db is HTML 4.01 so if you want your ETD-db installation to be XHTML compliant then you will need to do some major work rewriting and cleaning up the message files. This process is tedious but not overly time consuming if you know which files you need to alter. Plus a good text editor with the ability to globally find and replace with several files will make the process go smoother.

Changing the screens in ETD-db is relatively simple as long as you aren’t adding new fields. If you do decide to add new fields (as we chose to do) then this will be a more complicated process. Below are some basic steps for adding a new “text” field.

1. Add new fields to all the relevant ETD-db databases (in most cases this is etd_submitted, etd_available, and etd_withheld)
2. Add new fields to global variables (language/english/global_variables.pl
3. Edit all of the forms so that the reflect the new field (these forms exist in the submit_messages.pl, review_messages.pl, maint_messages.pl - In submit_messages they are called manage_etd_table, modify_etd_form, enter_title_page_form. In the other message files they are modify_etd_main_table, view_etd_main_table)
4. Edit the scripts which process the form data and add it to the database. (ETD-submit/add_etd, ETD-submit/update_etd, ETD-review,maint,withheld/update_etd)
5. Edit form that generates title page for each dissertation (language/english/non-cgi_messages.pl)

The process becomes slightly more complicated if you want to add a new drop-down menu.

1. Add new fields to all the relevant ETD-db databases (in most cases this is etd_submitted, etd_available, and etd_withheld)
2. Add new fields to global variables (language/english/global_variables.pl
3. Create array of items in the new drop-down in languages/english/global_variables.pl
   Example:
   @department_list = (
   “College of Music”,
   “College of Natural Sciences”
   );
4. Edit all of the forms so that the reflect the new field (these forms exist in the submit_messages.pl, review_messages.pl, maint_messages.pl - In submit_messages they are called manage_etd_table, modify_etd_form, enter_title_page_form. In the other message files they are modify_etd_main_table, view_etd_main_table)
5. Edit the perl script that generates the form to create the drop-down menu (ETD-submit/enter_title_page , ETD-submit/modify_etd , ETD-review,maint,withheld/modify_etd)
6. Edit the scripts which process the form data and add it to the database. (ETD-submit/add_etd, ETD-submit/update_etd, ETD-review,maint,withheld/update_etd)
7. Edit form that generates title page for each dissertation (language/english/non-cgi_messages.pl)

If you want more information on customizing ETD-db, feel free to contact me. I’m not a Perl expert. However, I’m spent a lot of time figuring out how the system works to get it working right for us.

I’ve also worked out the issues with ETD-db and authentication. Coming soon a post on mod_auth_mysql!