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) { ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() } |
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) { ![]() } else { ![]() } |
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>) { ![]() ![]() ![]() ![]() ![]() ![]() } 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.).