• Important information for Upgraders!

1. Create Script Directory
2. Set Script Variables
3. Upload Scripts & Templates
4. Create Data Directory
5. Try It Out!

6. Troubleshooting
7. Secure It

With one exception, you will not want to overwrite your existing template files (*.tpl or *.bit). The one exception is Admin.tpl which should be uploaded to the directory from where you run administrative duties.

. . . . . . .
If you're upgrading from version 1.4a through 1.4f

If you have version 1.4a or higher, your configuration settings are kept in a single perl file (Cfg.pl) that will work fine with this new code.

However: there have been some additions to the configuration file (Cfg.pl) in this release (v1.4g). As mentioned, your existing Cfg.pl file will work fine with the new script. The new script will simply default any features where it would normally use the new Cfg.pl values.

If you would like to update your Cfg.pl file you may. In this case simply copy all your configuration field values from your existing Cfg.pl file to the new Cfg.pl file that ships with this version (1.4g) release.

If you have chosen to use your existing Cfg.pl file, upload all the '.pl' files except Cfg.pl to your cgi-bin directory. That is, upload the following files:

• Admin.pl
• Funcs.pl
• GetTerm.pl
• Glossary.pl

If you've decided to use the new Cfg.pl file as well, upload it along with the above .pl files AFTER you've made the edits to include your existing configuration values.

. . . . . . .
If you're upgrading from an earlier version (pre 1.4a)

You will have to copy your configuration settings into Cfg.pl from the settings found at the top of each of the following three existing files: Glossary.pl, GetTerm.pl, and Admin.pl.

Then, upload the four files listed above AND the Cfg.pl file you've just edited.

You should keep your existing template files.

All user configuration variables used by Creativyst(R) Glossary are set in Cfg.pl.

There are technically only two variables (shown in bold below) that you MUST change to have the script work. Once you get the scripts working you then must set other variables in order to make your script secure.

For now, set up the script to run in unsecured, test mode. This will allow you to get past the normal issues with getting a script running on your server, and put off the details of making the script secure.

Only two variables in Cfg.pl need to be set to get the scripts working initially.

1. $UrlScriptBase
   Set this to the full URL directory where your scripts reside. A URL directory, means a URL like the one you'd type into the location bar of a web browser.

   Example: $UrlScriptBase = "http://www.mydom.com/cgi-bin/Glossary/"

2. $FileDataDir
   Set this to the full DISK path to the place on your servers disk drive where you want Creativyst(R) Glossary to maintain your database of terms and definitions. You will be creating this directory in the next installation step.

   Example: $FileDataDir = "/big/dom/xmydom/data/Glossary/"

The Cfg.pl script itself includes some terse commenting explaining what each variable does.

Script files are written in Perl and have a ".pl" extension. Template files are HTML pages but with a ".tpl" or ".bit" extension. They are used to specify how glossary related pages and menus look when displayed (more about templates can be found in the Administration document). All scripts and templates go into the same directory under your cgi (or cgi- bin) directory.

• In your browser's location bar type: http://www.MyDomain.com/cgi-bin/G/Glossary.pl?edit=the Where "MyDomain.com/cgi-bin/G" is your domain name and cgi directory name where you've installed Glossary's script and template files.

• A blank term-entry form is displayed. Enter a term and a definition. Perhaps "Glossary" in the term field and "A list of words and definitions" in the definition field. Then push the button labeled "Submit/List".
• A single glossary entry is displayed for the term: "Glossary"

• Now type: http://www.MyDomain.com/cgi-bin/G/GetTerm.pl?fsGetTerm=Glossary on your browser's location bar. A word list (with only the one word you've defined thus far) will display on the left and the entry for the word "Glossary" will display on the right.

1. Server Errors
2. Script Configuration Errors

1. Server Errors are sometimes called "500" errors because of the numbers used by HTTP to relate them. You will know these errors by the message they return to your web browser. It will usually say "Server Error" or more often than not "500" error (or some number in the 500's).

These represent the "first hurdle" you must get through when installing scripts. They are caused because the server had some trouble running the script through its CGI interface. In other words, the script never got a chance to run, because the server interface didn't get that far.

When the server tries to run a Perl script, the first thing it has to do is find the Perl interpreter. Scripts tell the server where to find the interpreter using the very first line of the script, through something called a "shebang" line. As mentioned, this is always the first line of the script, and looks something like this:

This particular one tells CGI that your server's Perl interpreter is located in the directory at /usr/local/bin. You should insure this is set to the correct path, where the Perl interpreter is installed on your server. If you are not sure, check with your hosting service. They usually provide a page that lists all these paths for various facilities on their servers.

Some servers will insist on specific access attribute (chmod) settings on the script files. These are often 755, but check with your hosting service.

One other common problem we see is caused by using Wordpad to edit your scripts and configuration files. When you save a text file with Wordpad, it will help you by adding special formatting and character codes. These turn your script into one big syntax error. Wordpad and any other text editor that insists on helping you by adding special codes to your script files simply can't be used.

2. Script Configuration Errors are caused by a mis-configuration in your script file. These occur when the script runs, but then finds it doesn't have the information it needs to do its job properly. This usually happens when you get a letter-case wrong or from some other typing error while entering configuration variables in Cfg.pl. Here is an example of what you will see on your web browser when a script configuration error occurs.

Usually, the message given will be helpful in fixing the problem. This means you've cleared the first hurdle and are actually running the script on your server.

A typical configuration is to provide view-only (unsecured) access to the glossary on the open web, while providing special secure access for your glossarists to add and edit terms and definitions to your database. The best way to do this is to provide two different directories: one for your regular visitors with no security, and another secure directory where you glossarists must log in.

    |
    +--cgi-bin/
    |       |
    |       +--Glossary/
    |       |   |
    |       |   |--Admin.pl     (delete this)
    |       |   |--GetTerm.pl
    |       |   |--Glossary.pl
    |       |   |--Cfg.pl
    |       |   |--Funcs.pl     (optionally, delete this)
    |       |   \--*.tpl/bit
    |       |
    |       |
    |       |
    |       +--GlossarySecure/  
    |           |
    |           |--.htaccess (limits this directory to members)
    |           |
    |           |--Admin.pl
    |           |--GetTerm.pl
    |           |--Glossary.pl
    |           |--Cfg.pl
    |           |--Funcs.pl
    |           \--*.tpl/bit
    |

In this configuration, each directory contains its own templates and configuration files, sharing only the database of terms. More directories can be added in similar fashion to, for example, provide an accessible set of glossary pages. In this configuration you should modfify the Cfg.pl in each directory to point to the file and script location for that directory. You will also want to remove the Admin.pl file from the "outside" directory (cgi-bin/Glossary/).

You may also add extra security to this by placiing Funcs.pl in a server directory outside of your DOC area (off-world). To do this, set the $FileFuncsDir variable to the full path of the directory where you've placed the function library, e.g.

$FileFuncsDir = "/my/domain/bin/lib/Glossary/";

Security Alternatives

1. You have a members only site, but you only want some of your members to be 
able to add and edit definitions. 

2. What about Admin.pl?

The template files are simply HTML page files with special tags to indicate where glossary controls are to be placed. The tags are disguised as HTML comments that start like this: <!--~: and contain a tag name to be replace. For example, to place the term being looked up in a template file type the tag <!--~:Term --> anywhere you want it to be printed.

There are currently five template files you can edit:

• HlpShare.htm
  This file shows outside webmasters how to link to your glossary from their own site. If you are considering making your glossary available to other web sites, you should change all the primary glossary references from Creativyst.com's glossary location to the location of yours. This includes both the actual links as well as the links given in the example code (the code for cut and paste). Also, if you are an associate you may want to include your associate number in the query strings to ga.pl. While this isn't absolutely necessary, it doesn't hurt to be complete.
• fsGetTerm.tpl
  This is a frameset definition containing a thin word list on one side and a definition area on the other. When you call GetTerm.pl with GetTerm.pl?fsGetTerm= (instead of just GetTerm=), it will return a frameset (using fsGetTerm.tpl) with the word and any other parameters (such as alternate glossaries) displayed. This generally doesn't need any modification at all, but if you have some specific frame layout in mind, you may set it up here.