A..11 Boxes

The Boxes Admin Tool is where you manage boxes. To use this admin tool, you must have the edit_boxes perm (A.12.9) active for your group.

WARNING: any user with permission to edit boxes can run arbitrary code on the server, with Apache's user and group permissions. Be careful when giving this permission to other people.

Boxes are bits of perl code that have full access to all of Scoop's data and subroutines. They range in complexity from the user_box which checks a few permissions to determine which items to display in the user's customized menu, to a set of boxes which handle the payment processing for advertisements and subscriptions and activate those items once they are paid.

Some features exist only in boxes, and likewise, entirely new features can be added using boxes without touching the underlying code. Boxes can also call external programs on the server, as can any perl script; the fortune_box is a simple example of this, and calls the unix `fortune' program to fetch a random quote, then formats it for display. For more information on adding features to Scoop, see section 5.

To edit a box, first select the desired box from the drop-down box labelled ``Box:'' then click the ``Get Box'' button next to it. The fields below will be filled in with the appropriate information.

To create a new box, leave the drop-down box set to ``Select Box'' and fill in the fields below as appropriate.

To save a new box or changes to an existing box, click the ``Save Box'' button at the bottom of the form.

The fields are:

Box
is the name of the box being edited. When creating a new box, this should be ``Select Box'', and when saving any existing box, it must match the name in the ``Box ID'' field below.
Delete this box
if checked, will cause Scoop to delete the box chosen in the above drop-down box. It is only displayed if a box is loaded into the form.
Box ID
is the name of the box being edited. When saving any existing box, it must match the name in the ``Box'' field above. When creating a new box, this field must contain a value not already used for a box name.
Title
is the display title of the box, and is used in the special key `title' in the box template, unless the title is changed in the box code.
Template
is the HTML used to contain the box's output. This is a block, and can be edited in the Blocks Admin Tool (A.7). The block must contain the special key `content' and may contain the special key `title'. When a box's information is loaded into the form, an edit link appears next to this field which brings you to the Blocks Admin Tool with the box template already loaded for editing.
Allow users to toggle box off
determines whether or not this box is listed in the user's display preferences. Some boxes are integral parts of the interface and shouldn't be optional, while others, like RDF feeds, are extras and make sense as optional boxes.
Description
is, as you would expect, a description of the box and what it does.
Content
is the perl code itself. Boxes can be considered standalone scripts instead of part of a mod_perl program, as they do not need to be in a subroutine or otherwise structurally different than what you'd find in an actual standalone perl script, except they have the advantage of having full access to all of Scoop's data and functionality, through the $S object. (For more information on the $S object and using it, see section 5, Extending Scoop's Abilities.)

The code in a given box can return either one or two values; the single value, or first of a pair, is placed in the special key `content' in the box template. The second value, if present, is placed in the special key `title' in the box template. If the second value is not present, the contents of the ``Title'' field above is used instead.

You should return the values as an anonymous hash. That is,

return \{ content => \$content, title => '\$title' \}


janra
2004-03-26