Scoop pulls basically everything from the database, including many of its features. Unless you are adding major new functionality to Scoop, you will do all customization through the web interface it provides. Some display text and settings are still in the code, but they are being moved to the database as developers find them.
Scoop builds every page from building blocks known as Blocks and Boxes, and many options are set in Site Controls; all three can be found in the Admin Tools menu when you're logged in as an administrator.
It can often be tricky to figure out where the item you're looking for is, or what it's called. The Search Admin Tool (A.21) lets you search through values and descriptions for several of the other admin tools.
You should start your customization in Site Controls. We already looked at a few of the variables available in section 3.1. Site Controls are Scoop's equivalent to what other programs call ``preferences'' or ``options''. Here you can enable and disable features such as the spellchecker, advertising, polls, diaries, and a variety of other things, as well as changing the configuration for those features.
Once you get the hang of Scoop, the various Site Controls will make more sense to you. Scrolling through the categories can give you some idea of the basic functionality that Scoop ships with. Each control also has a description to tell you what effect it will have on your site.
Section 4 refers to all the relevant Site Controls for each feature it describes, and gives a brief overview of how they work together while describing the feature.
A few preferences are group-specific, that is, you want certain people to have one setting, and certain others to have a different setting. Those preferences are generally found in the Groups Admin Tool, and are referred to within Scoop as permissions, or `perms'.
Some others are section-specific, or both section- and group-specific. Those are generally found in the Sections Admin Tool, and are referred to within Scoop as `section perms'.
The preferences found in Site Controls are global to the site.
The most basic elements of Scoop's generated pages are the blocks. A block is simply a chunk of text or HTML code that is used when generating a page. Blocks should be (and usually are) fairly self-contained; that is, any tags that you open in a block should be closed in the same block, and the block shouldn't break anything horribly if you put it in a different location on the page.
You can customize these blocks according to your own site design. To do any significant customization, you'll need to have a working knowledge of HTML.
A good starting place, just to test the waters, might be the header and footer blocks. Make a few small changes to these, and hit the ``Save'' button. When the page reloads, see how the changes you made were already implemented? This is because the header and footer blocks are used when creating most pages.
The best part of the blocks system is the ability to include other blocks within a block. Look carefully at the header block. You will notice that, mixed in with the HTML elements and text, are a few items marked off by pipes (|). Where you see the key `|section_links|', Scoop will take the value from the section_links block and seamlessly replace the key with it.
If you refer to a block that doesn't exist, possibly by making a typo in a key that should refer to a block that does exist, Scoop silently replaces it with an empty string. If you're quite sure you put a block there and nothing is showing up, double-check your spelling.
Now that you know this, you can start changing the look of your site. But it's easy to very quickly get lost in the maze of blocks and keys, especially with ``special keys'', so the best place to start is at the top level--the page templates in the templates category.
A page template is just another block, but it's the first one Scoop pulls up when it's building a page because it is a complete HTML page, starting with <html> and ending with </html>.
Your front page (and section pages) will use index_template, viewing a story uses the story_template, and most admin pages use admin_template. Be very careful changing these, because, if you mess it up, you might not be able to view your site.
To change a template, go to the block editor and choose the ``templates'' link, then scroll down to view the contents of the ``index_template'' block. You can see near the top there is a key called |header|. As you can probably guess, this is a reference back to the header that we changed a few paragraphs before. It also contains the special key |CONTENT|, which is where all of the stories for the page are inserted. By changing this page you can drastically alter how your site appears. The special block |CONTENT| is critical, as it is replaced with the main content--in the case of the index_template, it is replaced with the headlines and story summaries.
There are several special keys, most specific to a particular block and filled from the database. For example, the comment block, in the content category, has special keys for the comment subject, author, rating, and so on; those special keys have no meaning outside the comment block and corresponding blocks will not be found in the Blocks Admin Tool.
For more details on special keys and how the blocks fit together, see section 4.15.
Blocks are only the beginning of the story, however, and since they always return (roughly) the same thing, they can't provide some of the more customized content.
You will notice that the templates also contain keys like |BOX,login_box| and |BOX,user_box|. Unlike the blocks that we have just looked at, a box is a chunk of Perl code that generally has HTML as output. Don't be too scared by this, because you don't have to learn very much Perl to change some basic functionality of the boxes.
Boxes can include keys as part of their output, and those will be interpolated in the same way as keys included in blocks.
If you already know Perl, you will find Boxes to be an invaluable way to customize your Scoop site. Some fairly significant features have been done entirely in boxes, since boxes have access to every Scoop function and every bit of data Scoop carries.
If you don't know Perl, you will be limited to tweaking the existing boxes, or borrowing code from the Scoop Box Exchange. I am not going to provide a Perl tutorial for you here, but if you are interested in some light customization, just examine some of the boxes that ship with Scoop. If you like, you can look at a Perl tutorial so you can go a bit farther.
For more information on customizing your site using boxes, see section 5.
One warning, though: be very careful about who you give permission to edit boxes to, because boxes can run any program on your system. This is considered a feature; it's just dangerous if you're not careful about your permissions (3.3.3).