A..16 Ops

The Ops Admin Tool is where you control how Scoop behaves for a given ``op'', the first pseudo-directory in Scoop's virtual path. Subsequent pseudo-directories are handled by the function assigned here, and vary depending on the op. If you are using Scoop version 0.8, this functionality is (poorly) controlled by the Templates Admin Tool, which has been removed between 0.8 and 0.9 and is not documented here.

Ops that do not exist or are not enabled are handed back to Apache to process as a normal directory.

To edit an op, select the name of the op from the top drop-down list and click the ``Get'' button. To create a new one, leave the drop-down list at its dashes and just fill in the fields below.

The fields are:

Op
The name of the op, as it will appear in the URL. Use lowercase letters and underscores, mostly.
Template
The page template that will be used to display the page. Page templates are edited in the Blocks Admin Tool, and are all filed in the ``templates'' category. (See appendix A.7 and section 4.15.)
Function
The function that will run to produce content for the page. For some ops, the function is built into scoop, such as the story and comment display functions. For others, it is provided by a box. If the former, the name of the function is put in this text box; for the latter, the name of the box is put in this text box and the checkbox below is selected.
Function is a box
If the function named above is actually a box, this checkbox should be selected.
Permission
If a permission is needed to use this op, it should be selected here. (See appendix A.12 and section 3.3.) If no permission is needed, this should be left at its dashes.
Enabled
Whether or not this op is enabled at all. If disabled, Scoop acts as if the op does not exist, and hands it back to Apache. Anyone requesting this op usually gets a 404 Page Not Found error, unless by chance you have a directory of the same name as the op available.
Op Aliases
Alternate names that this op recognizes as equivalent. For example, the displaystory op has the alias story, so by default the URL http://www.site.com/displaystory/nnnn/nn/nn/nnnn/nnnn gives the same page as http://www.site.com/story/nnnn/nn/nn/nnnn/nnnn.
URL Templates
Information on how Scoop should interpret the paths it gets, and how to turn them into CGI parameters. There can be multiple templates of varying path length. Each template should be on one line, and multiple templates should be separated by a comma. The details are below.
Description
A description of what the op and its function do, so you don't have to go read the code...
Delete this op
Check this only if you intend to delete the currently selected op when you save it.

To save any changes you have made, click the ``Write Op'' button; to clear them, click the ``Reset'' button.

For more information on adding functionality to Scoop, see section 5.

To understand URL Templates, the first thing you have to know is that they are generally laid out much like the paths that they are used to interpret, except the first pseudo-directory (the op) is not present in the templates. The elements between slashes are CGI parameter names (in the path that the user sees they are the parameter values), and there are various commands that allow you to customize Scoop's interpretation of the path. An overview of how to create a basic URL Template string is below the following examples.

The simplest form can be found, for example, in the section op. The URL template there is /section/page/ which means that when the URL http://www.example.com/section/news/3 is requested, Scoop will first look at the section op to find out what to do with the rest of the path (first pseudo-directory) then set the CGI parameter `section' to news (second pseudo-directory), and the CGI parameter `page' to 3 (third pseudo-directory). The more familiar CGI URL, for those of you who have done web programming before, would be http://www.example.com/?op=section;section=news;page=3 and would get exactly the same page. If there are fewer pseudo-directories in the page request than in the URL template, the last few parameters are undefined.

Looking at the URL template for the comments op, you can see three different `complications' in how the paths are parsed. The first template, with element.1 at the beginning, indicates that this template only applies if the first pseudo-directory after the op is `poll'. (Element 0 is the op itself.) The rest of the URL template is then used as above to assign values to CGI parameter names.

The second and third templates have length= at the beginning. This indicates that they are to apply if the path is of that particular length (again, not counting the op in that length). You can see that the entry with length=2 has two CGI parameters defined, and that the one with length=3 has three parameters defined.

The fourth template shows an entirely different `complication'; sid{5} means that what would otherwise be five seperate items are treated as one parameter called `sid' (including the internal slashes). Story ID, or sid, values consist of five parts, separated by slashes.

The most complicated form can be found in the user op. The URL template there is a block of perl code enclosed in an EVAL{ } statement. This perl code, like boxes, has full access to Scoop's internal functions. The value returned by the code must be a hash with CGI parameter names as the keys and CGI parameter values as the values of the hash. In the case of the user op, it must do such things as translate /my/info to use the user op and the nickname of the user making the request. It can also change the real op entirely: this is how /user/nickname/stories can return search results--the op is changed to be search, and the nickname is used as the search term for an author search.

To create URL Templates, you must first sort out what CGI parameters must be passed to your op for it to do everything it needs to do in a GET request. (CGI parameters that should be posted can be ignored here, since they never appear in the URL.) Then, in general, you should order them from most generic to most specific. For example, the sections op first lists which section (generic) then which page (specific) you are requesting. Optional parameters (like which page) should be last, so they can be left off without messing up the other parameters.

Then, if none of your parameter values have slashes in them, you simply put your parameter names in the URL Templates textarea in order, separated by slashes. (Don't forget - leave off the op.)

If one or more of your parameter values have slashes, such as the sid (story ID), then specify how many `parts' the parameter value has. The sid, for example, has five parts - four slashes in the value, so instead of just /sid/ you would put /sid{5}/ to tell Scoop to slurp up five 'directories' for that CGI parameter instead of the default one.


janra
2004-03-26