ETD-db: Customizing the Distribution for Your Site



For the most part, the default settings for the ETD-db are tailored to our needs here at Virginia Tech. These pages describe how to change configuration files, graphics, web pages, etc. to customize the ETD-db for your site.


Steps to customize the ETD-db distribution

  1. Edit the global language files
  2. Configure the variables used by the CGI scripts
  3. Customize the "static" web pages
  4. Customize or disable the author survey

Edit the global language files

Under version 1.5, we have completed our implementation of global language files. These files contain all of the text strings, mail messages, and error messages that will be displayed for each of the interfaces and most of the example non-cgi-scripts. These files also contain global lists such as the list of departments, degrees, and document types that are available.

You'll want to take a look at the contents of <ETD-db_root>/language/english, you should edit the global_messages.pl and global_variables.pl files at a bare minimum, these contain critical information like the name of your institution, the departments, the degrees offered, and the email addresses of people at your site.

If you would like to translate the ETD-db into another language (or to change the wording of the english text), the language files will offer you the ability to do just that.

If you want to create a version of the ETD-db that displays messages in your own language (or in wording different from the default), copy the <ETD-db_root>/language/english directory and its contents to <ETD-db_root>/language/my_language, then begin editing the language files in the new directory.

Once you've edited the language files in the new directory, edit the global configuration file <ETD-db_root>/cgi-bin/etd-master-lib.pl and set $language_directory equal to <ETD-db_root>/language/my_language. If you are not translating the messages, and are directly editing the files in <ETD-db_root>/language/english, you will not need to change the $language_directory setting.

Currently, only the VT-specific American English version of the language files and a partial translation into Castillian Spanish are included. If you complete your own translation of the ETD-db using the language files, please get in touch with me (<kdweeks [at] vt [dot] edu>), I'd love be able to include your translations in upcoming distributions.


Configure the Variables Used by the CGI Scripts

Most of the common settings (file locations, database usernames and passwords, etc.) used by the CGI scripts are set using a handful of configuration files. Each individual interface (ETD-submit, ETD-review, etc.) has its own set of local variables as well. In addition, any global variables that have to do with department names, etc. are saved in the file global_variables.pl in the language directory.

Global Settings

The configuration file <ETD-db_root>/cgi-bin/etd-master-lib.pl is used by all of the CGI scripts, and contains a few common routines as well as a large number of variables. The following are descriptions of the most important variables and what you'll be changing if you alter their default values:

  1. $logfile
    This is where all actions performed using the scripts are logged to. Of course, the directory it's in has to exist and be writable by the user your web server runs as (usually "nobody").
  2. $institution
    The name of your institution. I forget why this isn't set in the global language files, but there's probably a good reason... :)
  3. $server_name
    The name of your server (don't include http://). If you're using a port other than the default (port 80), make sure to add it at the end of the server name (example: myserver.com:81).
  4. $system_root
    The system location of the directories which will house author title pages and files. You may certainly store your materials under the /ETD-db tree if you like, just make sure this variable points to the immediate parent directory under which the individual categories (available, submitted, etc.) will be stored.
  5. $web_root
    This should be the relative location on your web server of the directory above. For example: on our site, our system_root is /theses_1, which shows up on our web server as /theses.
  6. $available_dir
    This is the name of the available directory relative to both the system and web root. You probably shouldn't change this.
  7. $submitted_dir
    This is the name of the submitted directory relative to both the system and web root, you probably shouldn't change this either.
  8. $withheld_dir
    This is the name of the withheld directory relative to both the system and web root, again, you probably shouldn't change this.
  9. $cgi_root
    This variable is a bit confusing, as it's possible for this variable to be the same as the web_root if you put everything under /ETD-db. In short: this variable indicates the immediate parent directory as seen using a web browser. On our site, since our categories show up as /ETD-db/ETD-submit, etc., this is set to /ETD-db.
  10. $cgi_system_root
    This variable is not as widely used as the previous variable, but it is critical if you expect survey logging to work correctly. It should be set to the system location of the previous directory (if you read my installation notes, /export/ETD-db was the suggested location.)
  11. $sendmail
    This is the location on your system of sendmail or an equivalent command-line mailer. This program will be used to send all messages. Include the name of the program in the variable, i.e. /usr/lib/sendmail.
  12. $sendmailflags
    Sendmail can be quirky, if you need to put in special flags (aka command-line options) to use it on your site, this is where you'd do it.
  13. $date_bin
    The location of a program on the system that will return the date. Used for the logging, mostly.

Settings for Each Sub-interface

Each category of scripts includes its own configuration file. These configuration files contain routines and variables that are more specific to the individual interfaces. There are only a handful of variables and routines you should really change. Here are the configuration files you should look at:

  1. <ETD-db_root>/cgi-bin/ETD-submit/etd-submit-lib.pl
  2. <ETD-db_root>/cgi-bin/ETD-review/etd-review-lib.pl
  3. <ETD-db_root>/cgi-bin/ETD-catalog/etd-catalog-lib.pl
  4. <ETD-db_root>/cgi-bin/ETD-maint/etd-maint-lib.pl
  5. <ETD-db_root>/cgi-bin/ETD-withheld/etd-withheld-lib.pl
  6. <ETD-db_root>/cgi-bin/ETD-browse/etd-browse-lib.pl
  7. <ETD-db_root>/cgi-bin/ETD-search/etd-search-lib.pl
  8. <ETD-db_root>/non-cgi-scripts/etd-non-cgi-lib.pl

In each of these files, the following variables should be set:

  1. $DB_HOST
    This is the hostname on which the database is housed, you'll need to set this if you're running mysql on another server. Otherwise, the default value of localhost is fine.
  2. $DB_NAME
    This is the database name the set of scripts will be connecting to. Change these only if you really need to.
  3. $DB_USERNAME
    This is the username the set of scripts will use to connect to $DB_NAME and all other databases it works with. You should have set these up much earlier in the process, now's the time these really matter. For the record, I don't really recommend changing the usernames, as there's really no reason to.
  4. $DB_PASSWD
    This is the password used by $DB_USERNAME to connect to $DB_NAME. You should have selected different passwords when you set up the users originally, if you did, this is where you enter them.
  5. $language_directory
    This is the directory in which your language files are stored.
  6. $interface
    This is used to tell which files in the language directory are relevant for this interface. You shouldn't need to change this. In fact, things will probably go completely haywire if you do.

Each of the files also contains an html_header and html_footer routine, the output from every script is sandwiched between the relevant html_header and html_footer routines. Note that each category of scripts has its own very similar routine, this should allow you a lot of flexibility when customizing the headers and footers of different parts of the interface


Customize the static web pages

The "static" (not generated from the database) web pages included in <ETD-db_root>/web_root may be freely modified. Most pages use the DLA logobar and "VT ETD collection" logo found in <ETD-db_root>/web_root/images, if you rename those and put your own in their place, you'll immediately change the look of 90% of the pages and scripts. You may also want to put your own contact information on the pages that will be used by your authors.

The help pages included with this distribution are located in <ETD-db_root>/web_root/help. These help files deal with a variety of generic issues that have come up in our enviroment. A link to this help directory is included on all of the submission pages your authors will be using, making this a very good place to put site-specific help (or even links to site-specific help).


Customize or Disable the Author Survey

The ETD-db is designed to require each author to complete a brief survey once they have completed their initial submission. The location of this survey is configured by changing the value of $survey_completed in <ETD-db_root>/cgi-bin/ETD-submit/etd-submit-lib.pl.

We currently make use of a survey database we've developed, which is located at http://lumiere.lib.vt.edu/surveys/. The survey database can be used to manage surveys that are to be taken using a web interface. The survey database requires an account to create or edit surveys, contact anthony.atkins@vt.edu for more information.

If you will be using your own survey form and processing the results yourself, make sure that the script or program that processes the author survey results is set to direct the authors to <ETD-db_root>/cgi-bin/ETD-submit/process_survey after their results have been recorded. The "process_survey" script updates an author's database record to indicate that they no longer need to take a survey.

If you would like to completely disable the survey requirement, you'll need to alter the etd_main table that's part of the etd_submitted database. To do this, you should:

  1. Connect to the etd_submitted database using a command like:
    mysql -uroot -proot_password etd_submitted
  2. Issue the following command at the mysql prompt:
    alter table etd_main 
    change column survey_completed 
    survey_completed char(3) default 'YES';

This will set up the database authors add their ETDs to so that when a new record is created, the system will record that the author has already completed a survey. To reenable the survey requirement, simply use the commands above, but set the default to NO instead.



Want to help improve this system? Take a quick survey online!