Subsections


5.3 Working with Boxes

New features can be easily added to Scoop using its unique box system. Boxes are chunks of perl code with complete access to all of Scoop's data and functions. Many boxes are used for simple purposes such as adding or removing items from the user and admin menus, depending on permissions. Other boxes provide functionality that appears completely built in, such as the commentless, sidebarless story view with the full URL at the bottom used for a printable copy. Others display site statistics such as the number of stories and comments posted, or the stories hotlisted by the most people.

Boxes can be either embedded in the page as a small, modular bit of code as with the user menu, or they can generate the entire page on their own as with the printable version of a story. Boxes embedded in the page are `normal' boxes, while boxes used to generate the entire page (such as the printable story view mentioned above) are referred to as `box ops'. The two types of boxes are mostly written in the same way, but are placed on the page in very different ways. They can also run as a scheduled item through Scoop's cron system (A.14).

5.3.1 Box structure

Box code generally looks like what you'd find in a typical perl script. You do not need to put the #! line at the top, nor a subroutine name, nor a `my $S = shift;' - all that is handled by Scoop's box handler. You simply write the code that would be inside the subroutine. Boxes placed on the page with a box key can take arguments; you then call them with |BOX,boxname,arg1,arg2| and you can get the values of the arguments from the @ARGS array.

Boxes must return an anonymous hash with the keys `content' and `title'. The key `title' is optional; if omitted, the text in the Title field of the Boxes Admin Tool (A.11) form is used.

Boxes cannot use block or box keys as part of their code, but can return them as part of the title or content string.

Don't use subroutines in boxes. It will sometimes work, but is not reliable and will sometimes fail with an Internal Server Error.

5.3.2 Adding new features

Quite a few features can be added entirely through boxes. Other features which modify a `core' feature of Scoop, such as how stories and comments are handled, must be done in the perl modules or in a combination of modules and boxes. See section 5.4 for more information on adding new features in general.

If a feature makes sense as a separate `op', such as the printable version of a story, you can designate the box as the function for the new op, using the Ops Admin Tool (A.16) so that it generates the entire page and handles any parameters passed to that op. Parameters are available to the box code as CGI parameters, with the names of those that appear in the path defined in the URL Templates field of the Ops Admin Tool.


janra
2004-03-26