Scoop Administrator Documentation

This document has been out-dated and replaced. See the scoop_admin_guide/ directory for the newer version.

Note: This documentation is incomplete, and may be somewhat inaccurate and/or outdated. If you don't know any perl, but want to help out with the project, and have a grasp of how it works, *please* consider updating this document! The developers will love you for it!

Table of Contents:

  1. Introduction
    1. What is Scoop?
    2. Who should use it?
    3. Who shouldn't use it?
    4. What's the license?
  2. How to install Scoop
  3. Site Administration
    1. Vars and Blocks
      1. What are vars and blocks?
      2. How do I edit them?
      3. Things to know about Vars
      4. Things to know about Blocks
      5. Important Vars
      6. Important Blocks

I. Introduction

1. What is Scoop?

Scoop is a web application designed to make it easy to run your own weblog. A weblog, defined loosely, is a website that posts news, or articles, or even just a personal diary-type thing, and is updated on a fairly regular basis. Many weblogs seek to provide a kind of online community, and allow readers to post comments of their own, and participate in the site in other ways. Scoop attempts to make it pretty easy to run a site that does these things.

2. Who should use it?

Anyone! You can use it, certainly. Scoop will be useful, I think, for people who want to run a weblog, and who don't necessarily feel like programming their own, or tangling with some of the other systems out there, some of which can to be very complicated. Just for fairnesses sake, you have some options in your choice. Other systems that provide similar functionality as Scoop include:

I'm sure there are more, but those are the biggies. For the record, Scoop is written in perl, so language is not the key difference between Scoop and slash. :-)

3. Who shouldn't use it?

If you're running a very high-traffic site, you probably shouldn't use Scoop. And by very high traffic, I mean hundreds or thousands of hits per minute. Scoop doesn't do any static page caching, and is not particularly concerned about using your system resources. For high-volume sites, I'd recommend Slash, since it's had long testing in such an environment.

Now, I don't want to scare anyone away, mind you. Scoop will not suck up 100% of your processor and bleed memeory all over your server room. I run both of my scoop sites from my own machines, both of which I use as workstations on a daily basis, and I've had no trouble whatsoever handling on the order of hundreds of hits per day. But generally, scoop is in the early release stage, and was not written for maximum efficiency. It will be undergoing a rewrite very soon, and you can expect to see it get leaner and more efficient as time goes on.

4. What's the license?

Scoop is released to you under the terms of the GNU General Public License. You will find a copy of this license in the file LICENSE, in the main scoop directory. If you're using free software, you should read the GPL at least once, so go ahead and read it. For more info on free software, look at http://www.opensource.org.

II. How to install Scoop

The instructions for installing Scoop are located in the file INSTALL, in the top-level Scoop directory. Please look there for the latest directions. If you're reading this from somewhere other than your own unpacked tarball (or CVS checkout), the general gist of the install is this:

And thats about it. It's really not too hard. Anyone with any experience running web stuff can do it, and if you don't have much experience, I think the instructions are pretty clear.

III. Site Administration

This is the part you're probably here to see, so I'll get on with it now.

1. Vars and Blocks

a. What are Vars and Blocks?

The look and feel of your Scoop site can be almost entirely configured through the web interface of Scoop itself, using these things called Vars and Blocks. Simply put, Vars are small bits of text, some of which will get plugged in to the html around the site, and some of which control things like how many stories to display on the main page, etc. Blocks are larger chunks of text that create some of the bigger pieces of the scoop output. Blocks can include vars, as will be explained below. A complete list of important vars and blocks is also contained in these docs, and I recommend you look up what they are before you edit them. One other thing, Vars and Blocks are case sensitive. Meaning that "CONTENT" is a different var than "content". Got that? It's important!

b. How do I edit them?

When you log in to your scoop site as an administrator (i.e. a user with seclev >= 1000), you will get a bunch of options that normal users don't get. Many of the scoop configuration tools will be linked in a box called "Admin Tools." Normal users will only see "Story Moderation" in here, but you get some other options. One of them is "Vars/Blocks." Click on this, and you'll go to a screen with editing fields for all of your vars and blocks. Choose from one of the drop-down lists, click on "Get," and you have the current values for that var or block. Edit the value, and click "Write" and your changes are saved. The changes should take effect on the site immediately. There's no need to restart Apache. To create new blocks or vars, just make sure the drop-down is set to "Add New (whatever)." That's really all there is to it.

c. Things to know about Vars

Vars are pretty simple. They each have one key, and one value. The value is restricted to 127 characters, as is the description. The Var name is restricted to 32 characters, and must not contain spaces. Vars are never interpolated, that is, you cannot embed Vars in other Vars and expect that to work.

d. Things to know about Blocks

Blocks are a little more complicated. Block names are restricted to 30 characters, and also must not contain spaces. Block values can be as long as you need them to be. Additionally, you can embed Vars inside Blocks, by including the var name inside pipes within the block value. For example, if I had a var called 'font_color', whose value was '#000000', I could use it in a block like this:

<FONT COLOR="|font_color|" SIZE=3>

When that block was used by the system, the output would look like:
<FONT COLOR="#000000" SIZE=3>

You can even include blocks within other blocks, in the same way. To use a literal pipe character inside a block, escape it with a backslash, like this: \|. That would not be interpreted as an instruction to include a var, but would print out as a '|' character.

Additionally, some blocks can include things which are not Vars that you may edit, but are defined by the system when it builds certain pages. For example, the block 'comment' includes several variables, such as |subject|, |name|, |email|, and so on. These are not defined by you, but are created by the system when it uses these blocks. In the block list (elsewhere in this document), any blocks that can use special variables will include the name and purpose of each.

Name collision between special variables and normal Vars is possible, but only in a limited scope. Basically, you can name your Vars anything you want, but if, for example, you create one named 'name', you cannot use it within the block 'comment', because how is the system supposed to know which |name| is the system variable, and which is your Var? You see the problem. Generally, you probably won't need to create many Vars yourself, and if you do, pick a name that is likely to be unique, or check the list of special vars elsewhere in this document.

e. Important Vars

The following is a list of Vars that the system pretty much needs to function right, and what they each do. Please refer to this list when you're going to edit something, to make sure you know what you're doing. Some of them are named badly, and it's not obvious what they do. :-)

Phew! That's all the vars so far. Remember, you can add your own if you want/need to. And now, on to the blocks...

f. Important Blocks

The following is a list of the system default blocks, roughly what they do, and what, if any, special vars they require (or can use). Examples will not be given, since many of them would be long, and all of them are in the default database anyway. For good examples, refer to your scoop site itself.

  • advertisement

    Purpose: This will appear on all the pages wherever you include it in index_template. The idea is that you'd put the code to display a banner ad or whatever here.
    Special Vars: None.

  • autorelated

    Purpose: This one's cool (and not in slash!). You know the "What's Related" box that displays with every story? Well, that automatically parses every HREF from the story itself, but it also searches for any word that you put in here, and when it finds one, adds a link in "What's Related" consisting of the word, and the URL you also provide. The format is "word,url" without quotes, one per line. NO SPACES, and make sure your urls are full path. Add a new one here, and it gets stuck in "Related" every time, without you ever having to link it in the story.
    Special Vars: None, and don't use normal Vars here either. It don't work that way!

  • box

    Purpose: This is the code that creates the standard "box." Should be html, and, to work right, MUST contain the special vars below, somewhere. Each box is separated by a <P>, so you should probably make this a self-contained table, if you're going to change it
    Special Vars:

  • comment

    Purpose: Each comment will be formatted according to this block. It should consist of one or more single-celled table rows (you could just include something else in a <TR><TD></TD></TR>, but it's gotta look like a table row with one cell, on the outside). Many special vars included in this one, so pay attention!
    Special Vars:

  • commentswarning

    Purpose: The legal warning to post before and after comments. Again, it must look like one or more table rows, with one cell each, at least on the outside.
    Special Vars: None

  • comments_head

    Purpose: The bar that goes on top and below comments, with links to the story, the number of comments, etc. As always, must look like a single-celled table row.
    Special Vars:

  • features

    Purpose: The contents of the "Features" box. No special formatting required, just some html.
    Special Vars: None

  • footer

    Purpose: A page footer, stuff that you always want displayed at the bottom of the page. Note that since you can also edit the entire page template (umm, that'd be index_template) in Blocks, you could easily change/move/rename this. But generally, you'll want a footer, and this is where you'd put it. Formatting just has to mesh with index_template.
    Special Vars: None

  • footmenu

    Purpose: Menu for the bottom of the page, probably. Gotchas here are the tendancy to use pipe characters in menu lists. Remember to escape them! ('\|')
    Special Vars: None.

  • header

    Purpose: Stuff to put at the top of every page.
    Special Vars:

  • index_template

    Purpose: This one's pretty important. It controls the layout of your entire standard page. There are two EXTREMELY important special vars here, so read that part carefully. Generally this'll start with <HTML> and end with </HTML>, and what's in the middle is mostly up to you. Experiment carefully though, since if you bork this too badly, the page won't display, and you'll have a hard time changing it back when you can't get to the admin console!
    Special Vars:

  • moderate_head

    Purpose: That's "moderate" the transitive verb, not the adjective. This is the header to put above comments displayed in the story moderation section. Should, of course, look like a single-celled table row.
    Special Vars:

  • moderation

    Purpose: This is the story moderation equivalent of comment. It controls how moderation vote/comment blocks are displayed. Looks like one or more table rows.
    Special Vars:

  • recent_news_box

    Purpose: Makes the "Recent Stories" display. This is basically a list of topic icons, linked to their stories, however many you chose in the var recent_topics_num. Should probably be a table.
    Special Vars:

  • story_mod_controls

    Purpose: HTML to wrap around the story moderation "vote" console. Should look like a table row with one cell, and must contain it's one and only special var.
    Special Vars:

  • story_summary

    Purpose: Controls the look of each "story summery". That is, the short sections displayed on the main page, and that same bit on the full story page. Should be one or more table rows, you knwo the drill.
    Special Vars:

  • submission_guidelines

    Purpose: Some html that will get displayed at the top of the story submission page. Freeform, really.
    Special Vars: None

  • submission_message

    Purpose: Get's displayed after someone submits a story. Whatever you want to say.
    Special Vars: None

    This documentation is not yet complete, but it should at least get you started. For problems, help or bugs, email rusty@kuro5hin.org or visit Scoop Bug Reports.