Making an Add-On

So, how do I make an Add-On? Unless you know PERL, I wouldn't recommend even bothering. What I will cover here is how to integrate each of the three pieces of an Add-On.


Part 1: The Add-On Box on the Edit Settings Page
This part of the add-on is actual code that is executed by add.cgi. The code is executed after all of the UHSD's built-in security measures. You can look at add.cgi's source for more detailed information about that. Okay, here are the important variables in a Magic Table o' Clarification:

Variable

What it stores

@scores

The current, formatted score data from scores.dat. The currently submitted score has not yet been added. Each fieldof a particular score is seperated by a pipe character ("|").

@ascores The current, formatted all-time score data from ascores.dat. The currently submitted score has not yet been added. Each fieldof a particular score is seperated by a pipe character ("|").
%entry This hash stores the submitted data. Any data that has been submitted, even if there is no UHSD field for it, will be in this hash. All keys are lower-case. Changing any values will permanently change the submitted data.
@fields A list containing all of the UHSD field names.
%properties A hash containing the type of data a field is. 0=string and 1=number
%number A hash containing the current location of a field name in the @fields list.
&prepare_entry A subroutine that returns the formatted score data for the submitted score.
sort_numbers A sort algorith for sorting numbers. It is used in the format "sort sort_numbers array."
sort_strings A sort algorith for sorting strings. It is used in the format "sort sort_strings array."

When trying to access files, use the format of "$entry{'game'}filename." Each game has its own seperate directory. Everything is formatted for you, so don't worry about formatting it yourself. If you have any questions about this, let me know.


Part 2: The Add-On Navigation Box on the Edit Universal Settings Page
This part of the add-on is more PERL code. It is executed whenever a the main screen is displayed (where all of the buttons are for accessing different functions). The code is executed after all off the built-in functions are displayed. I'd just like to point out that you only need this if you want the user to be able to access any external scripts included with your add-on. There are only a few variables that you need to know for Add-On Navigation:

Variable

What it stores

$name This stores the name of the user currently logged-on. If you want to keep your add-on secure, you'll need to pass this via a hidden form entry.
$password This stores the password of the user currently logged-on. If you want to keep your add-on secure, you'll need to pass this via a hidden form entry.
$gameselect This stores the HTML gode for a dropdown list containing each game. It's form entry's name is game. If you're not making a universal add-on, you'll need this.

What you need to do is simply print an HTML form with the action pointing to whatever external script you want. Don't forget to close your form. Feel free to add whatever form fields you'd like. If you have any questions about this, let me know.


Part 3: The External Scripts
This part of add-on is the most varied. You can use whatever external scripts you'd like. You can do them in whatever style you'd like as well. The only restriction is that the form entry containing the name of the current game will be game. I would recommend, though, that you keep the name and password entry fields as name and password (you'd have to decide this in your Add-On Navigation). Don't feel that you have to add all of your external add-on scripts to the Add-On Navigation because you don't have to. Here are some of the pieces of code found throughout the UHSD that you might want to use:

Function of Code

Actual Code

This code gets the data submitted from the form. It stores all of the submitted values in the format of $form{'name'}. if($ENV{'CONTENT_LENGTH'} > 3)
{
read (STDIN, $unformatted, $ENV{'CONTENT_LENGTH'});
@pairs = split(/&/,$unformatted);
foreach $pair(@pairs)
{
($name,$value) = split(/=/,$pair);
$value =~ s/\+/ /g;
$value =~ s/%(..)/pack("c",hex($1))/ge;
$form{$name} = "$value";
}
}
This code verifies the user name and password. $pass = crypt($form{'password'}, "MM");
open(USERS, "jxzdfx.dat");
$users = <USERS>;
close(USERS);
%users = split(/\,/,$users);
if($users{$form{'name'}} ne $pass)
{
#Log-in failed. Do whatever.
}
else
{
#Log-in succeded. Do your stuff.
}
This code displays the main screen (navigation stuff). open(SET,"uniset.dat");
$set = <SET>;
close(SET);
@unisettings = split(/,/,$set);
$help = $unisettings[2];
$title = "Title to Use";
open(PAGE, "nav.dat");
while(<PAGE>)
{
$row = $_;
$chopped = chop($row);
if($chopped ne "\n")
{$row = $row.$chopped;}
$page = $page."$row\n";
}
close(PAGE);
eval($page);

Part 3b: Naming the External Scripts

The last thing I want to discuss is the naming of external files. You must use the format of aoauthornumberfunction.ext. Author should be a short name or a set of initials. I use MoB. Number should be an identifier that tells the user to which add-on the file belongs. Function should be a word or piece of a word that just allows you to distinguish between the different files in your add-on. For example, one of my add-on files might be named aoMoB2editusers.cgi. If you have any questions about this, let me know.


What to Do After Completing an Add-On

After your add-on is done, e-mail it to me. I'll test it out (that doesn't mean that you do not have to test it) to make sure it works. I'll also check for malicious code. If you'd like to include integrated help files in your add-on, make some help files in HTML (using the same general format that I have used) and let me know that you want them added to the main UHSD help files. If you don't make any, I may make some brief help files for your add-on. Also, make sure that you followed the proper file naming format for external files. In addition, you must put the Add-On Navigation code into a file named aoauthornumbernav.txt and the Add-On Box code into a file named aoauthornumberscript.txt. If there are any special installation instructions (by that, I mean any in addition to or that differ from the normal installation procedure), you must put them in a file named aoauthornumberinfo.txt. If you've done everything correctly and if everything works, I'll add your add-on to the official list, and I will create or update your author profile. For your first add-on, feel free to include information for your author profile (name, e-mail, home page, etc.).


Back to Index