Most of Scoop's layout is in the database, accessible through the Blocks Admin Tool (A.7). Any of the blocks can be altered in any way to change the entire layout of the site; some Scoop sites look nothing like Scoop's default install. Any block can insert any other block simply by calling it by name using the |block_name| convention. Please note that any vertical pipes (|) you want displayed literally must be escaped with a backslash (
|).
Blocks can also insert boxes, by using the |BOX,box_name| convention. Scoop has to be told when the item to insert is a box, because boxes and blocks are treated very differently. Blocks are simply inserted verbatim, replacing their reference; boxes are executed by the mod_perl interpreter, and their output is placed into the content and title special keys of a box template, which then replaces the box key. Boxes are often used when part of a display is conditional, such as the user menu, which shows or hides menu items depending on the user's group permissions.
For most blocks, you can put anything you like in them and just see how it comes out; however, when altering the page templates, keep in mind that the admin pages--specifically, the Blocks Admin Tool--are created using the block admin_template, so if that's screwed up to the point where you can't use the page, you'll have to go into the database to fix it. So take care, ok?
For boxes, if an error appears that is not noticed at compile time, it can cause your site to return a 500 Internal Server Error, so it's good practice to test all boxes on a page template other than the admin_template, which is used to create the admin pages.
Not every block is called directly using keys in other blocks, so tracing how the blocks interact can be difficult. Some block calls appear to call nonexistant blocks, yet content appears in that place; those are special keys, and are specific to the block in which they appear. Most special keys are described in the block descriptions in the database, but some important ones are described here.
The simplest case is when one block calls another; the text |block_name| in the calling block is replaced with the contents of the block block_name. Because tracing blocks and their interactions can be so tricky, it is recommended practice to make all blocks quite self-contained; that is, don't open a tag in one block and close it in another, because that's just a nightmare to debug.
The exceptions to the self-contained rule are things like the font tag blocks; those come in pairs, one that opens the tag and the other that closes it. Nothing but a font (or header, or span) indicator should be in those blocks, and the start and end tags must be balanced.
The first stage of block interaction is when Scoop determines which page template to use for a particular op (the first pseudo-directory), set using the Ops Admin Tool (A.16). The front page, with no visible op, actually uses the op ``main''. The page template is a full HTML page, and provides the core layout and positioning of content. It generally includes a standard header and footer (both also blocks), the sidebar(s), and a special block called CONTENT, but no actual content of its own.
CONTENT is where the output of whichever function (set in the Ops Admin Tool) is called to build the page is placed. The function grabs whichever blocks are needed to build the page, handles any special keys, then puts the whole thing in the place of |CONTENT|, after which the normal keys are interpolated normally.
For example, when you request the front page, Scoop builds the front page using the block story_summary once for each story on the front page. The number of stories to be displayed is fetched from the variable maxstories, and Scoop limits the number of stories pulled from the database accordingly. All the special keys in the story_summary block are filled in with the appropriate information from the database.
Similarly, when you request a specific story, Scoop uses the story_summary, story_separator, and story_body blocks; then it starts and ends the comments with story_info, which has information on the story and comments as well as the comment controls, then displays the comments themselves using the block comment or moderation_comment, depending on whether the comment is topical or editorial. Again, most special keys are filled in with information from the database as described in the block descriptions.
In addition to fully customizing the layout, you can have a different set of customizations appear based on several criteria using Scoop's theme engine.
Using themes, any block at all can be replaced with a themed one, and themes can be layered. A theme can have as few as one block, or can replace all blocks. Themes can be applied based on several criteria: which section is being viewed, both in story and section index views; what user group the visitor is in; what user agent the visitor's browser reports, the site's site_id variable, from the Apache configuration, and the visitor's user preference. More criteria can be added fairly easily with a bit of perl-fu in the theme_chooser box.
Themes are created through the normal block interface. To create a new theme, just add a new block with the name of the theme in the ``Theme'' text box; when you save the new block, the theme will be automatically created. Similarly, to delete a theme, simply delete all the blocks in that theme; when the last block is deleted, the theme will be automatically removed.
Themes are layered by the simple method of replacing any blocks in the parent theme with the block of the same name in the child theme. If more than one layer of theming is desired, debugging is simplified by having the layered themes replace non-overlapping sets of blocks from the default (base) theme.
Non-overlapping themes also allow, for example, a structural theme, modifying the layout of the page, and a `colour' theme, only modifying colours, to be set independantly but apply seamlessly at the same time. For example, a structural theme using tables and one using CSS can both call the same colour theme for a given section. A theme may include blocks not present in the default theme; if that theme is then not applied, any references to blocks only present in that theme are treated as if they don't exist, that is, replaced silently with an empty string.
To manage themes, the variables in the ``Themes'' category of the Site Controls Admin Tool (A.6) contain all the variables you will be using. Themes in general are turned on or off by the variable use_themes. Users may be permitted to select a theme to be layered with any others you have configured if the variable allow_user_themes is turned on. This only allows them to select between ``none'' and the themes listed in the variable user_themes. If the user has not selected a theme, the theme named in the variable user_theme_default is used.
To activate a theme selection criterion, its name must appear in the variable order, which also specifies the order in which themes are layered. The default theme (named in the variable default_theme) is always applied first, to provide a complete foundation for the site. If your themes have been carefully constructed to be non-overlapping, the order will not matter and the order variable simply names the criteria to be used in theme selection. If they do overlap, however, the order in which theme criteria names appear is critical, as themes applied earlier may be overwritten by themes applied later, if there are any duplicate blocks between them.
Once you have decided on the order and criteria to use when applying themes, you must create variables to specify which themes to apply where. (Make sure you file these new variables in the ``Themes'' category so they are easy to find later.)
The variables used to assign themes to criteria contain the name of a single theme as their value, and must be named according to a specific format, namely <criterion>_<item>.
For example, if you have a section with the display name ``Site News'' and the internal name ``site_news'', and you want a theme to apply to the section index page and all stories filed in that section, you would create a text variable called section_site_news and give it the name of the theme you want to use as a value. You must create one such variable for each section you want to apply a theme to. The front page is not assigned a section, so the default theme should contain its specific blocks.
The criterion portion of the variable name must match the criterion name listed in the order variable, and the item portion of the variable name must match the internal name Scoop uses for its sections, user groups, and site ID (set in the httpd.conf file). For the user agent theme, the item must match one of the strings the box detect_agent returns.
User agent detection is currently not functional and always returns an empty string. User agent detection is generally not considered a good idea, as you're not likely to think of every possible user agent that might reach your site. If there is one particular browser that chokes on a particular part of your site, though, you may want to detect that one browser and give it a theme with the troublesome part done in a way it can understand.