next up previous
Next: 3.7 Topics Up: 3 Administration Previous: 3.5 Site Controls/Vars

Subsections


3.6 Block Editor

Blocks are larger pieces of text that are inserted into the page that Scoop generates. Page templates (3.11) and box templates (3.10) are special blocks.


3.6.1 What's in a Block?

Blocks can contain other blocks or vars. Both blocks and vars are called in the same manner: their name surrounded by vertical pipes. (eg, |header| is replaced with the contents of the block named header)

Some blocks have special vars which do not appear in the lists of either the site control editor or the block editor. The most common of these is |CONTENT|, and these are supplied by the Scoop code from the database. Generally, if a var name is all upper-case, then it's supplied by Scoop.

Blocks can also contain calls to boxes (3.10). You do this with a special form of the vertical pipes, which is ``|BOX,box_name[,arg,arg,...]|''. Only the word ``BOX'', followed by a comma, then the name of a box is required. Args are optional, and most boxes don't use them, or don't require them.


3.6.2 Usage

The block editor is accessed from the admin tools box.

You can create a new block by filling out all of the fields in the form and clicking the "Write Block" button at the top, or fetch an existing block by choosing its name from the drop-down list and clicking the "Get" button. Clicking the "Get" button will fetch whatever block is selected in the drop-down box and will discard any changes made since the last time the block was saved.

The "Name" box is the name of the block, and should contain only letters, numbers, and underscores.

The "Value" box is the content of the block. This can be any length and can contain almost any character. Vertical pipes must be preceded by a backslash if you want them to be displayed as vertical pipes and not as the delimiters of a var or block to be substituted.


3.6.3 Individual Block Descriptions

3.6.3.1 admin_alert

The email address of administrators - used to email alerts when Scoop detects a problem.

3.6.3.2 allowed_html

The HTML tags Scoop will allow users to use in stories and comments. Lists the tag name, followed by an optional comma-separated list of elements allowed inside that tag. If the tag must be closed, end the list with '-close'. Also, you may set constraints on an element by using ``element=<regexp>''. Note that the regexps can't have commas in them, since that's the seperator. Also, the groups that can use elements can be restricted with '-groups'. By default, all groups can use a tag, but if you use '-groups', only the listed ones can use the tag. An example is '-groups=''Superuser Admins Editors'''. Note the seperator is a space, and that the quotes are optional, but recommended.

3.6.3.3 attach_poll_message

The message displayed just above the poll form, below the story submission form, telling the user about the poll.

3.6.3.4 autorelated

The ``What's related'' box lists all the links used in the story, but the autorelated box adds a link to that list if a word (listed here) shows up in the story, whether it is a link or not. List the word you want it to detect, a comma, and the URL, with no spaces and one per line.

3.6.3.5 blank_box

A box template - no title bar or border.

3.6.3.6 blank_template

A page template - no header, footer, or content. This must be a complete HTML page.

3.6.3.7 box

A box template - the default one with the blue title bar. The special vars |title| and |content| are supplied by the box code (in the boxes admin tool (CROSS REF)).

3.6.3.8 box_title_bg

The background colour of the title bar used in a box template. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.9 comment

The structure of comments attached to a story. This should be mostly self-contained (ie, a complete table) and have the replies outside the table at the end.

There are lots of special vars here. In approximately alphabetical order, they are:

|actions| The "Reply to this" and "Parent" links, and the "Rate" form, all depending on what permissions you have and whether or not this comment has a 'Parent'

|cid|Comment ID. The comment number attached to the story
|comment|The text of the comment
|date|The date and time the comment was posted
|email|The fake email the poster supplied on their preferences page, if any
|name|The nickname of the poster
|new|If the visitor has not yet read the comment, the contents of the block new_comment_marker are placed here
|replies|The thread of replies to this comment are placed here
|score|The score (average of all ratings) this comment has earned
|sid|Story ID. What story this comment is attached to
|sig|The poster's signature block
|subject|The subject line/title of the comment
|url|The poster's home page, as a link
|user_info|A link to the user info page for the poster
The normal vars typically used in this block are:

3.6.3.10 commentdisclaimer

Anything you want to display above the comment posting form. This is, by default, a warning that trolling is not tolerated and comments may be deleted. This is pretty much free-form HTML.

3.6.3.11 comment_head_bg

The background colour of the comment title bar. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.12 cron_template

A page template. No header or footer, only |CONTENT| and title. This must be a complete HTML page. This is used for when cron is run, and is parsed (to an extent) by run_cron.pl, so you'd best just leave this be.

3.6.3.13 default_template

A page template. This is the default template, used for most pages on the site.

Be EXTREMELY careful when changing this template! If you mess it up, you may not be able to do anything - the admin pages may use this template!

This must be a complete HTML page.

There are only a few special vars, but they're rather critical:

|STORY|if a story is being displayed it is placed here
|CONTENT|the primary content of whatever page is being viewed
|subtitle|this is replaced with the title of the story, or the site slogan, or whatever seems appropriate.
The normal vars typically used in this block are:

|footer|The footer block, typically containing the copyright disclaimer, search box, link to scoop.kuro5hin.org, etc
|header|The header block, typically containing your site's logo, section links, etc
|sitename|The name of your site
These notes apply to all *_template blocks.

3.6.3.14 dept_font

A complete opening font tag. Used if use_dept is enabled. ("From the [whatever] dept" line under the title of a story)

3.6.3.15 diary_submission_message

The message displayed underneath a user's diary entry when they have just posted it. Basically free-form HTML.

3.6.3.16 digest_headerfooter

The text of the header and footer of emails sent with the story digest system. The strings __FREQUENCY__ and __USERID__ are replaced with the appropriate values when the email is sent. \n is a newline character, though a normal newline also works.

(note: is SITENAME supposed to be replaced by the system, or is it a reminder to the admin to replace it?)

3.6.3.17 digest_storyformat

The format of the stories listed in the digest email. The following strings are replaced:

__title__The story title
__aid__The author's nickname
__time__The time it was posted to the website
__section__What section it was posted in
__tid__What is the topic of the story
__introtext__The introductory text of the story (the paragraph or two that shows up on the front page)
__url__The url of the full story and comments.

3.6.3.18 dot

Any bit of HTML code that produces a dot or bullet or something for lists in the boxes along the side.

3.6.3.19 empty_box

A box template that contains no framing, no formatting, just the content via the special var |content|

3.6.3.20 footer

Whatever HTML you wish to have displayed at the bottom of every page generated. There are no special vars here, just normal ones like |norm_font| and |rootdir|

This is mostly only called from the *_template blocks.

3.6.3.21 fzdisplay_template

3.6.3.22 fz_ad_url

3.6.3.23 fz_navigation_url

These blocks all apply to ForumZilla support, which Scoop has built-in. There should be no need to edit these blocks.

3.6.3.24 header

Whatever HTML you wish to have displayed at the top of every page generated. There are no special vars here, just normal ones.

This is mostly only called from the *_template blocks.

3.6.3.25 hotlist_link

3.6.3.26 hotlist_remove_link

The text of the links provided beside each story title that allow people to add or remove stories from their hotlists.

3.6.3.27 index_template

A page template. This is typically the template used for the front page and section pages, but rarely anything else.

See default_template for more details about special vars, warnings about editing templates, and so on.

3.6.3.28 login_box

Despite the name, this is not a box template. This is the content put into the user box if a visitor is not logged in.

There is only one special var: |LOGIN_ERROR| is replaced by an error message if the visitor tried to log in and failed, and is left blank if there are no errors.

This should contain a form with two text inputs, one named "uname" and one named "pass" for the visitor to input their username and password, respectively, and two submit buttons, one named "login" with a value of "login" and one named "mailpass" with a value of "Mail Password".

3.6.3.29 moderate_head

This is the text put at the top of the moderation box after a visitor has voted on a story.  There are two special vars:

|score|the score of the story so far (sum of moderations)
|votes|the number of votes cast so far.

3.6.3.30 moderation_comment

This is just like the block comment, only it is used for 'editorial' instead of 'topical' comments. In the default install, the only difference between the blocks comment and moderation_comment is the colour of the rim around the title.

This uses all the same special and normal vars as the block comment.

3.6.3.31 new_comment_marker

This is inserted by the code with the comment title if a visitor has not yet read that title. Any bit of html will work, especially if the text is red.

3.6.3.32 next_page_link

This is the text of the link to the next page of stories. It is placed after the last story on a page.

This block uses only one var: |maxstories| is found in site controls.

3.6.3.33 no_body_txt

This is the text of the link used instead of readmore_txt if there is nothing in the body of the story.

3.6.3.34 opcodes

This is a list of the possible op codes: comma separated, usually one per line, though it doesn't matter. If you add an opcode here, then it doesn't do anything until you associate it with a template using the template tool (CROSS REF).

3.6.3.35 op_aliases

This is a list of aliases to various op codes: alias=real, one per line.

3.6.3.36 op_templates

This block sets the rules used for the new URL style. Unless you add an op, or want to tweak the rules, you won't need to change this.

However, if you do need to, it uses a special format. First, each rule is seperated by a comma, and is generally on a new line to make them easier to read. There are two types: a matching rule, and a default rule. A default rule is simple ``op=template'', where op is an op code (not an alias to one, the real one), and template is an op template (see next paragraph). A matching rule takes either a number or the word ``length'' to match, and is in the form ``op.what=match:template''. If what is a number, then it indicates a part of the URL. For instance, if the URL is ``http://scoop.site.com/user/info/foo/'', then a what of 1 would be ``info'' and a what of 2 would be ``foo''. If what is the word ``length'', then in our example, it would be 2. Match is whatever ``what'' should be in order for this template to be used. The first matching template to be found is used, otherwise the default is.

A template is in the form ``/arg/arg/arg/etc.''. Basically, if the URL is ``http://scoop.site.com/user/info/foo/'', and the template is ``/tool/nick/'', then the tool arg will become ``info'' and the nick arg will become ``foo''. There are also some special forms for templates. For instance, ``{x}'' will take the next x parts of the URL and put them all in one arg, seperated by slashes (for example, ``sid{5}'' is used for anything related to stories). Also, ``*'' will take everything remaining in the URL and put it into one arg. Naturally, this must be last in the template.

There is an additional form that may be used with default templates which allows you to execute perl code. The form is ``op=EVAL{code}'', where code is any valid perl code. This code has access to the $S object, just as any box would, and also has an array called @path which contains the parsed path information. Note that any commas or pipes should be escaped with a backslash (\, and \|).

3.6.3.37 pendingstory_bg

The background colour of a story that is still in moderation. Used only in the story list. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.38 poll_block

Used by Scoop to format and display a poll.

3.6.3.39 poll_box

A box template. This one is used for the poll, with |title| and |content| supplied by the code.

3.6.3.40 poll_guidelines

Not used.

3.6.3.41 prev_page_link

This is the text of the link to the previous page of stories. It is placed at the top and bottom of the page when a visitor is on a page other than the first, or only the bottom when on the first page.

3.6.3.42 readmore_txt

The text of the link at the bottom of the story summary if the story has body text that is not displayed. If the story does not have body text, the block no_body_text is used instead.

3.6.3.43 rss_box

Template for the ForumZilla boxes. Probably shouldn't change this, since doing so will probably break ForumZilla support.

3.6.3.44 rss_template

Page template used for ForumZilla. Shouldn't change this either.

3.6.3.45 scoop_intro

The 'introduction to scoop' box shown in the left column of the front page of a fresh install. You probably want to note the addresses of the links and remove it from the page before your site goes live.

3.6.3.46 sectiononlystory_bg

The background colour of a story that is displayed only in the section. Used only in the story list. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.47 section_links

The links to the different sections. Usually only displayed in the block header.

3.6.3.48 smallfont

A complete opening font tag for text that must be smaller than normal.

3.6.3.49 smallfont_end

A closing font tag to match block smallfont.

3.6.3.50 story_body

How the body text of a story is displayed. This should be a reasonably self-contained piece of HTML. There is only one special var used: |bodytext| is replaced by the text of the story body.

3.6.3.51 story_info

The bar placed at the top and bottom of the comments. It contains the story name, number and type of comments, and the 'post a comment' link.

There is one special var: |story_info| is replaced with the links and information about the comments.

3.6.3.52 story_mod_bg

The background colour of a story in moderation that the user has not yet voted on.  A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.53 story_nav_bg

The background colour of the story navigation bar. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.54 story_summary

The layout of the story header and introtext. This should be a reasonably self-contained bit of HTML.

There are several special vars:

|hotlist|Either blank, hotlist_link or hotlist_remove_link, depending on whether or not the visitor is logged in and has the story already listed in his hotlist
|info|The link to the user info page of the author, and the author's nickname
|introtext|The intro text of the story
|readmore|A link to the full story and comments, with block readmore_txt or no_body_txt as the text, depending on whether or not there is anything in the body text
|section_link|The link to and name of the section the story is filed in
|stats|The number of words in the story body, the number of total and new comments
|time|The time the story was posted
|title|The title of the story
|topic_img|The image associated with the topic the story is filed in

3.6.3.55 story_template

A page template. This one is used to display the full story and its comments. Special vars are |STORY|, |CONTENT|, and |COMMENTS|. The usual notes about page templates apply. (see default_template)

3.6.3.56 submission_guidelines

Warnings and instructions displayed on the story submission page, just above the form. This is basically free-form HTML.

3.6.3.57 submission_message

The message displayed at the bottom of the story when it has just been posted to the moderation queue, thanking the user for submitting a story.

3.6.3.58 submitrdf_template

A page template. This one is used when users submit RDF feeds. No special vars, just the submit_rdf box.

3.6.3.59 submittedstory_bg

The background colour of a story in the moderation queue. Used only in the story list. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.60 submit_rdf_message

The message displayed explaining how to submit an rdf feed.

3.6.3.61 submit_template

A page template. This one is used when a user is composing a story. Special vars are |STORY| and |CONTENT|. The usual notes about page templates apply. (see default_template)

3.6.3.62 titled_box

A box template. This one has both |title| and |content| but is otherwise plain.

3.6.3.63 title_bgcolor

The background colour used for titles. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.64 undisplayedstory_bg

The background colour used for stories that have been hidden. Used only in the story list. A hexadecimal colour value: #rrggbb (r = red, g = green, b = blue)

3.6.3.65 vote_console

The story moderation form, displayed below the story for stories in the moderation queue. There is only one special var: |vote_form| is replaced with the actual form used to register votes.


3.6.4 Notes

None


3.6.5 Relevant Vars

Lots. It depends on the block.


3.6.6 Relevant Perms

edit_blocks


next up previous
Next: 3.7 Topics Up: 3 Administration Previous: 3.5 Site Controls/Vars