NewsPro Addon Guide
NewsPro addons work in a
very simple way. They also work very closely with NewsPro, and have
little documentation; to write an addon, you are going to have to
look through parts of newspro.cgi. This guide should explain the
basics that are common to all addons, however.
Creating an
addon and registering it with NewsPro is very simple. Addon
filenames must be in the format npa_something.pl, and addons must
always be located in the same directory as newspro.cgi. If an addon
fulfills both those criteria, newspro.cgi will automatically
incorporate it (via Perl's require function) into itself.
(Viewnews.cgi will do the same if you have changed its $EnableAddons
variable, at the very beginning of the viewnews.cgi
file.)
The first line of an addon should always be
push(@Addons_Loaded, 'Name of addon'); |
and
the last line must always be
A file
called npa_test.pl which contains only the lines:
push(@Addons_Loaded, 'Test Addon');
1; |
is
a perfectly valid addon, though all it does is add "Test Addon" to
the Addons: list on the main page.
(Side note: you would not see
this addon on the Addon Manager page. Addons must explicitly
register themselves with the Addon Manager to appear there. This is
only necessary if your addon is going to be distributed, however,
and for the Addon Manager's upgrade notification to work your addon
has to be registered on the NewsPro server anyway; if you would like
your addon registered on the server and information about the Addon
Manager registration, send an email to the support
address.)
Now comes the more difficult part: how to make your
addon actually do something. The way addons work is by "hooking"
themselves into particular points in newspro.cgi. When the script
reaches one of these points and sees that an addon has hooked itself
in there, it will run a specified subroutine in the addon.
Basically, it is as if code from the addon was inserted into that
point in newspro.cgi.
Hooks are present in quite a few places
in newspro.cgi. There is no central guide to them; to find one, just
look through newspro.cgi until you see something like
if (@Addons_MainPage) {
&RunAddons(@Addons_MainPage);
} |
That
example shows a hook called Addons_MainPage. (This is a real example
- that's the hook to use if you want to add another option to the
main NewsPro page.) Next, the addon has to hook itself in there.
This is done with a line like the following near the beginning of
the addon:
push(@Addons_MainPage, 'MyAddon_MainPage'); |
This
line would cause NewsPro to execute the addon subroutine
MyAddon_MainPage whenever it reaches the Addons_MainPage hook.
(There is no rule as to what addon subroutines must be called, but
to avoid conflict and confusion it is a good idea to use the
convention of NameOfAddon_NameOfHook when naming
subroutines.)
That's about it. See, addons are simple! The
difficult part is, unfortunately, figuring out how newspro.cgi
works. We need an example here, and a good example is an addon that
displays a list of headlines on the Submit News page. Fairly simple,
and possibly useful as well. (By the way, this idea was suggested to
me by KrYo, the same person who wrote the excellent kTalk
addon.)
We'll call this Headline Viewer, and name it
npa_headview.pl. I'll go right into the code now, but I will comment
the code wherever possible.
# The standard first line: name the addon.
push(@Addons_Loaded, 'Headline Viewer');
# Next we have to hook this addon into newspro.cgi.
# We want to display things on the Submit News page,
# and if you look through sub DisplaySubForm in newspro.cgi
# (which controls the Submit News page), you will find hook
# Addons_DisplaySubForm_Post4 in the right place (right after
# the end of the Submit News form itself).
push(@Addons_DisplaySubForm_Post4, 'HeadView_DisplaySubForm_Post4');
# That's all for hooks. Now we have to actually write the subroutine.
sub HeadView_DisplaySubForm_Post4 {
# First, a plan of what we are going to do: simply open headlines.txt
# and print it out. The first step, then, is to get the path to headlines.txt.
# Everything from Change Settings and Advanced Settings (as well as most addon
# settings) is stored in an associative array (a hash) called %NPConfig.
# The path to the HTML files directory is stored in a key called htmlfile_path
$HeadViewPath = "$NPConfig{'htmlfile_path'}/headlines.txt";
# Now begin to print HTML. We will put the headlines in a simple table.
print qq~
<table border="0" align="center">
<tr><td><div align="center"><b>Recent News Items</b></div></td></tr>
<td>
~;
# Now we're ready to print out headlines.txt.
# Normally, to open headlines.txt you would use the Perl open() function.
# However, NewsPro provides NPopen(). In usage, it is equivalent to open()
# but it adds basic security and full error handling.
NPopen('HEADVIEW', $HeadViewPath);
# Now just use standard Perl to print out the contents of the just-opened file.
while (<HEADVIEW>) {
print;
}
# Printed. Now close it.
close('HEADVIEW');
# Finish off the HTML...
print qq~
</td></tr></table>
~;
# ...end the subroutine...
}
# ...and include the mandatory last line. Done!
1; |
That's
it for this guide. The addon architecture itself is quite simple;
the problem is that it is integrated very tightly to NewsPro, and
you will often need to know how NewsPro itself works to write
addons. Usually reading through the relevant parts of newspro.cgi
and nplib.pl will tell you what you need to know; if not, you can
send an e-mail to the support address.
|