next up previous
Next: 3.11 Templates Up: 3 Administration Previous: 3.9 Special Pages

Subsections


3.10 Boxes

Boxes are one of the most powerful aspects of the scoop system. Boxes are written in perl and cached within scoop. So it would be a good idea to have a basic understanding of perl before attacking boxes. They are essentially a way to embed a small perl cgi with full access to Scoop's internal functions in a page, and have it cached too so its not recompiled every time. Boxes could take up a whole administrator's guide themselves, so this will be a quick once-over of how they work and what you can do with them.


3.10.1 Usage

3.10.1.1 Editing

To edit boxes you use the admin tool box editor. You need edit_boxes permission to edit these. At the top of the form is a pull down box to choose which box to edit. Click Get Box when you have the box you want chosen. If you are creating a new box, then leave it as Select Box. Below that is the Box ID. This is what you will use to reference the box within blocks, so it should only have letters, underscores, and numbers like most other id's in Scoop.

The Title is used for when you make boxes like user_box or admin_tools, it is what is displayed at the top of the box if you use the box template. The Template pull-down menu is how you choose how the box will get displayed when you embed it in a block. The templates are edited and created in the Block editor (3.6), and identified from other boxes by a trailing _box at the end of their name (similar to page Templates (3.11) ). The only exception to this rule is the box box template. It is the box template that most boxes use.

The Description box is there for your convenience, make notes about what a box does, what its for, or anything else. Nobody will see this but the person editing the box.

Content. Where it all happens. Inside Content is all of the perl code that makes up boxes. Whatever code you write in this section, it only has to have one thing, which is the return. Without a return no data will be displayed. The return statement should return an anonymous hash reference with at least one key, two max. The necessary key is content, and the optional one is title. Generally boxes will build up a $content string thoughout the box and return it as:

return { content => $content,
         title   => $title,
       };
All of the arguments passed to a box (more on that later) are also accessible via @ARGS. More importantly (or usefully, as the case may be) you have access to Scoop's $S object. This is the main object in scoop, and with it you can access the database, use any of the functions in scoop, and generally do anything you could do by editing Scoop's modules directly. For more information on how $S is set up, and what you can do with it, you should read the Hacking (4) section of this document.

Lastly, save the box by clicking on Save Box. To reset the box to what it was before you started playing with it, click Reset.

3.10.1.2 Embedding Boxes

Ok, so you can create these nifty boxes, but how do you use them? Well, insert them into a block. This can be a regular block, or a page template, but pretty much anything you can edit in the Block Editor you can put a box in.

To put it in a block, insert the following:

|BOX,<I>box_name</I>,<I>arg1</I>,<I>arg2</I>|
This will insert at that point in the block the data returned from the box box_name called with the arguments arg1, and arg2. You can specify as many arguments as you like, and the box can access them through its @ARGS array.


3.10.2 Notes

When you edit a box, then finally click Save Box, it will eval() all of the code in the box and cache it. If there were any errors when compiling the box, it will say so at the top, and the form will contain the code that caused the error, for you to fix. Its hard editing code within a textbox, so we reccomend using boxtool, its a script Keith Smiley put together that allows you to edit boxes (or blocks or special pages) from the command line in your favorite editor, save them and load them back into the database. Much handier than textboxes in a browser.


3.10.3 Relevant Vars

None


3.10.4 Relevant Perms

edit_boxes


next up previous
Next: 3.11 Templates Up: 3 Administration Previous: 3.9 Special Pages