Where to Start?
First, I'll explain the basic building blocks of how Scoop displays a page. There are three main tools that control this: Site Controls, Blocks, and Boxes. There are also sections and topics, but those are fairly self-explanatory so I'll let you explore those on your own. After you've learned the initial tools, you can move on to more advanced features like Groups, Ops, and Hooks.
Site Controls:
We will start our Scoop customization by looking at the site controls. 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, or a variety of other things.
When you login to Scoop with your superuser account, you should see a link for "Site Controls" in the admin toolbox. Choose that, and click on the link for "General." This should take you to a page that lists a lot of general options for you to change. If you want to test changing something to see how it works, try changing the "sitename" and "slogan" site controls to something more appropriate for your site.
Once you get the hang of Scoop and all of the available features, 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.
Blocks:
Now we'll move on to the most basic element of Scoop, the blocks. A block is simply a chunk of HTML code that can be referenced from any page by name. In the admin toolbox choose "Blocks," and choose the link "site_html". From there you can see a listing of blocks that control various aspects of the display.
You can change and customize these blocks according to your own site design. A good starting place 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 called by most pages by default.
The best part of the blocks system is the ability to call other blocks. To show you what I mean, look carefully at the header block. You will notice that mixed in with the HTML elements and text are little items marked off by pipes (|). There is a reference to |section_links| which when called will take the value from the section_links block and seamlessly place it within the header.
Blocks: Templates:
With this knowledge you can really begin the task of making your Scoop site look unique. However, you need to know where to begin. The key is the group of blocks called "templates". The template is a master block for displaying an entire page. Your front page (and section pages) will use index_template, viewing a story uses the story_template, and most admin pages use default_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, from within the block editor choose the "templates" link and scroll down to view the contents of the "index_template" block. For example, you can see near the top there is a reference 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 block |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.
Boxes:
Blocks are only the beginning of the story, however. You will notice that the templates also contain references like |BOX,login_box| and |BOX,user_box|. Unlike the blocks that we have just looked at, boxes are chunks of code written in the Perl programming language that will return HTML to the page. Don't be too scared by this, because you don't have to learn very much of Perl to change some basic functionality of the boxes.
If you already know Perl, you will find Boxes to be an invaluable way to customize your Scoop site. If not, you will be limited to tweaking the existing boxes, or borrowing code from the Scoop Box Exchange. To edit or add a box, select "Boxes" from the Admin Tools menu. I am not going to provide a Perl tutorial for you here, but if you are interesting in some light hacking just examine some of the boxes that ship with Scoop.
More advanced features:
This is only part of the story, once you get past the basics there are many other ways to extend your default Scoop install.
Groups/Perms:
Obviously you don't want every user to have the same amount of access that you do. The ability for Scoop to control access to various areas of your site is located under the Admin Tool "Groups". Select the group "users" from the group dropdown box and click on the get button to open up the set of permissions.
You will see a giant list of permissions, but most of them are self explanatory. Some interesting ones that aren't enabled by default include "view_comment_ip" and "use_spellcheck", each required in order for the respective functionalities to work. Try to leave most everything enabled for the superuser group, otherwise you have the potential to lock yourself out of functionality.
If you ever need to add a new permission, the master list is stored in the block "perms". When you add a new perm it will default to being unselected for all groups. If for any reason you delete a perm from that list, the perm will still be set for all users that formerly had it, so make sure you've removed the permission from the group first.
Ops:
Simply put, an op is the first pseudo-directory that a user can enter on your site. For example, the op for http://www.kuro5hin.org/story/2002/1/15/231539/319 is "story". If you open the Ops Admin tool you can see a list the ops that are currently on your system. Open up the op "newuser" and check out how that op is set up.
You can see that newuser uses the template default_template, but it is simple to change to any of the templates including any new ones that you might want to create.
You will also see an area to select a function, and a checkbox called "function is a box". The newuser op starts with the function "newuser", and this shouldn't be changed under most circumstances. However if you want to, you can make an op call a different function if need be. If the function is already provided by Scoop you just have to reference it by name, otherwise you can create a box, reference the box name and make sure the checkbox is selected.
As for security, this is controlled by the dropdown box "Permission", and the checkbox for "enabled". If the user viewing the site doesn't have the perm selected in the dropdown, they will get a message saying "permission denied". If the enabled checkbox is not checked, the op will not exist at all and the user will get a "Page Not Found" 404 error.
I hope you can see by now that with the combination of Ops, Block Templates, and Boxes, you can do most anything you wish with your site design. At least, anything that is possible in MySQL and Perl.
Hooks:
As if that wasn't enough, Scoop has functionality called hooks, found under the Hooks admin tool. A hook is a way to make a action link to something else, like a box or a scoop function. Scoop doesn't ship with any hooks enabled, so I can't give you any examples.
Like an op, you can bind a hook to a box or other scoop function that isn't enabled by default. For example, if you wanted scoop to email you when a story was posted, you could create a box that did the email, and then bind the function story_post to your new box.
Go to work:
That should be more than enough to get you started. I hope you enjoy customizing your scoop site!
