basic set up & HTMLs

Before this page
See the advice for a novice first where you make compulsory changes on the first line (path) and the basic set up. You may make any optional changes but please do so after you confirm that the default CGI works.

Simple optional changes
You may make optional changes. Open link.cgi

################
# basic set up #
################
:
:
$lock = 20;
$exprs = 600;

$lock = 20; unlocks CGI when it is locked by an error. (If more than one URL are posted at the same time, the data would crash over the data file link.html. Locking CGI is necessary to avoid such accident. The CGI unlocks itself soonest after it adds an URL.) If, for some reason or other, the CGI quit without unlocking itself, new URL cannot be add thereafter - because it is still locked. But the CGI checks how old the lock is. link.cgi is a small script and an ordinary computer can execute it in few seconds - so a lock older than 20 seconds must be an error. Then CGI unlocks itself automatically. You can set $lock longer if you have a living fossil type server.

$exprs = 600; sets the period for which admin page cache is valid. The default is 600 seconds or 10 minutes. The cache, includes your password, is automatically deleted from your computer after $exprs for safety - good if you share your computer. If you see "cache expired" message frequently as you administer the link page, however, make the value longer.

$erro0 to $erro7 set error messages when something went wrong. As far as you do not write something misleading, you can change them safely.

Find HTML in CGI
I already mentioned add.html and link.html. You can find and modify many HTMLs hidden in the cgi, too. You may import them to homepage authoring soft, change them, open the page sources and copy and paste them back to the cgi.

First, the most important HTML piece, the form a link data is arranged.

### data preparation ###
:
<p>
<b><a href="$data{'url'}">$data{'title'}</a></b>
<br>$data{'descript'}<p>

The part of HTML can be found between $newd = <<"NEW_URL"; and NEW_URL in link.cgi. You can change this part with a little HTML knowedge as far as you do not change names start with "$" namely, $data{'url'}, $data{'title'} and $data{'descript'}. You can relocate them, decorate them with all fancy HTML tag you know, or you can add $data{'name'} and $data{'email'} for the name and email address of the guest, but never change their variable names.

If you want to have a dollar mark inside perl, spell it \$ instead of $. (Price: $50 must be Price: \$50.) Also if you want to have @, write it \@. (So, your@mail.address must be your\@mail.address. Else perl returns an error.) A funny thing is, if you want \, it must be \\ instead. More, perl uses double quotes " for it's own. To avoid confusion, HTML double quotes within perl double quotes must be written \".

Please note, you can find similar

do_something <<"CAPITAL_LETTERS";
     :
     :
CAPITAL_LETTERS

combinations in the cgi. What comes between a pair of capitalized word is a HTML document (or a part of HTML). You can not use the particular capitalized word within the HTML (the word indicates the end of HTML). In other words

print <<"YOUR_HTML_DOC";
     :
     :
You have HTML here.
     :
     :
YOUR_HTML_DOC
     :
     :
HTML continues.
     :
     :
YOUR_HTML_DOC

does not work. HTML continues.. etc. will be ignored at best or CGI malfunctions.

Thank you message
"Thank you message" is also HTML.

#####################
# thank you message #
#####################
     :
     :
     :
<HEAD>
<META HTTP-EQUIV="REFRESH" CONTENT="5;URL=$url">
<TITLE>Thank you :-)</TITLE>
</HEAD>
<BODY>
<H1>
Hello there!
</H1><H2>
$thank
</H2>
You may need to click the reload button to see the latest change on the link page.
</BODY>

$thank says that "an URL is added" or, if the thank-you-page is called after you edit the link page, "it is edited". To change the value of $thank, you need to go a little more than HTML.

<META HTTP-EQUIV="REFRESH" CONTENT="5;URL=$url"> redirects an user back to the link page (now with the new link). If you want to redirect him to other web page, replace $url by that URL. The redirect will take place after 5 seconds. Change the value as you like - 3 for 3 seconds! You may delete this "REFRESH" line. Then you have no redirect.

Error-message page
Error message waits for a guest when something goes wrong.

#####################
# Error No1 message #
#####################
     :
     :
     :
<TITLE>Error!</TITLE>
</HEAD>
<BODY>
<P>
<B>Dear Guest,</B>
<P>
Your command has been averted due :
<BR>$_[0]
<BR>$_[1]
<BR>$_[2]
<BR>$_[3]

Do not change "$_[0]" to "$_[3]" unless you understand them. They are standard error messages defined in the basic setting at the very top and perl's own error message and the line number where error takes place.

HTML doc and JavaScript
I already mentioned add.html and link.html. They are HTML documents and you can work with HTML knowledge. add.html has JavaScript between <script language="JavaScript"> and </script>. Do not change it unless you understand JavaScript. This script gives Add-URL-Form "smart submit" function. The most common mistakes are checked before an URL is submitted.

By default, add.html accepts maximum 800 bytes (or 800 letters and characters) of description. The size of TEXTAREA is 80 x 10 which is equal to 800 bytes. If you want to change the maximum size of description, you may change the size of TEXTAREA so that the guest can easily understand the limit of data length. What is more important is, however, JavaScript. It checks if the description exceeds 800 bytes.

if (document.link.descript.value.length > 800) {msg+="Your description is " + (document.link.descript.value.length - 800) + " bytes too long. "}

Change these two 800 the number you like.

If you are testing your CGI before uploading it to the server, see the advice for a good HTML user.