Goal
Our goal in this tutorial is to add the following feature to Scoop. You can type, anwhere and on any page, something like this into your Scoop blocks:
|BOX,help_link_box,foobar,About Foobar|
(although later we'll discuss how to make |HELP,x,y| an alias for this)
This will create a link that, when clicked, creates a new popup window with help about the topic 'foobar' - the content of which is stored in a block called 'help-foobar'. Although I'm not going to get into the details here, this can be made real pretty with all kinds of fancy Javascript tricks too. I'm going to keep the code in this tutorial Javascript-free, so as not to complicate the issue.
This is going to require a few changes to the Scoop code. Hopefully, you've got the latest version from CVS, although this should all work on any 0.6-based release or prerelease. Also, I'm hoping that the two places that do require changes to the code will eventually be changed so that the changes can be accomplished from the Vars menu instead. I'll have to talk to Rusty about that.
Creating the link
Anyway, back on topic. The first thing we need to do is create a Box that will print out the link when called. This box will not have any HTML associated with it, so we need to create an HTML box template called "raw_box" - which looks like this one line:
|CONTENT|
The code for the box, with boxid help_link_box, looks like this:
#First, get the two arguments, x and y. In our example, $target == "foobar" and
# $label == "What's Foobar?"
my $target = shift @ARGS;
my $label = shift @ARGS;
#This should eventually become a block, but for now just print it out raw
my $content = qq{ <a href="|rootdir|/?op=help;helpid=$target" target=_help>$label</a> };
return { content => $content };
Be sure to associate this box with the raw_box template from the Templates SELECT box in the Boxes control panel.
Creating the "help" opcode
This is one of two places where you'll need to edit the scoop codebase, although like I said I hope that one day we'll get this controlled through a var. The file lib/Scoop/OpTemplates.pm controls which opcodes are shown in the "Templates" control panel (under Admin Tools). Just add "help" to the list of values. Restart Apache, and we're good to go.
Everything else from this point on does not require any changes to the scoop codebase, and can be done through the web interface. We need to create a template for the help display page. Again, this will be another one-line block, call it help_template:
|BOX,help_display_box|
In the Templates control panel, associate the "help" opcode with the "help_template" template.
The help_display_box will be required to provide all of the HTML necessary to make the page look good, so let's give it a nice block to do this in. Call it, for simplicity, help_display_box, and have it look something like this:
<HTML>
<HEAD>
<TITLE>|TITLE|</TITLE>
</HEAD>
<BODY>
<h1>|TITLE|</h1>
<p>
|CONTENT|
</BODY>
</HTML>
Now, it's time to create the help_display_box box. Be sure to associate it with the box template of the same name (it should show up in the "templates" SELECT box in the Boxes control panel). Here's the code for the help_display_box. It could use some additional error checking, etc. but let's keep it short for now:
#get the CGI paramters generated by help_link_box
my $target = $S->{CGI}->param( 'helpid' );
my $title = "Help about $target";
#get the content from the appropriately-named block
my $content = $S->{UI}->{BLOCKS}->{$target} || "Error: no content found for $target";
return { title => $title, content => $content };
Creating the help
That's it for the help system. All that remains is to actually create some help. This is accomplished using the Blocks system. For help about topic foobar, just create a block called "help-foobar" and put whatever HTML-formatted help in it that you would like. This block will automatically get loaded at the right time by the system we just created.
Advanced Topics
There's one more thing that would be nice, and that is to allow using the syntax |HELP,foobar,About Foobar| instead of the clunky |BOX,help_link_box,foobar,About Foobar|. Turns out, this is not so difficult. It requires two changes to the Scoop code, and here they are.
First, in lib/Scoop.pm look for a block like the following (it's line 425 for me):
my $special_keys = {
"BOX" => 'Scoop::box_magic',
"URL" => 'Scoop::make_url',
"A" => 'Scoop::make_anchor'
};
Add another mapping to this list: "HELP" => 'Scoop::make_help'.
Next, open up lib/Scoop/Utility.pm and add a function called make_help. It should look like this:
sub make_help
{
my $S = shift;
my @ARGS = @_;
return $S->box_magic( @ARGS );
}
Restart Apache, and you're done.
Well, folks, that's it for now. Sorry if any parts of this are confusing. This is a first draft, and since I am not near my Scoop install, the code is untested. I'll hopefully get some patches for the current CVS code that are a bit more elaborate than what's described here soon, if there is interest. So let me know if this is something you might find useful.
As always, feedback/questions/criticisms are more than welcome.
