slashguide - The Slash Developer's and Administrator's Guidebook
Anyone who wants to run a Slash site. By "run" we mean install, maintain, administer, and oversee. You'll learn what the major components of the software are, and background to help you diagnose problems. You won't become best friends with every single function in the API but you will
This guide is also for developers who would like to add to the Slash code, whether sharing patches publicly (thanks!) or working on your own site privately.
You must be familiar with Perl. If you aren't confident you know about objects and methods, basic regexes, and how to use CPAN, you won't get much out of this. You should know some SQL; if you don't know what a one-to-many relationship is, or why a performance goal is to reduce the number of tables used in a join, you won't get much out of this.
This guide is probably too in-depth for authors who just post stories to a Slash site; you need a tutorial on admin.pl (and someday we hope to have one for you).
This guide is for the Slash code as of mid-2003, and much of what is here will not apply to version 2.0. Some may not apply to 2.2.
Since the Slash site you will want to run probably doesn't look exactly like the default "slashcode" theme, you will have to customize it. You'll first need to know what themes and plugins are and how they work.
"Theme" is commonly used to mean a skin, a swappable module that affects only the look of a site or program. Slash's themes do control almost every aspect of how a site looks, but it ends there: our themes run much deeper. They are the base code that generates pages, the base code that runs in the background, and they include variables that control most tunable parameters.
The .pm files live outside of themes, providing an API that any theme can use for basic functionality: accessing the database in useful ways, generating data, and so on. (The conceptual distinction is that any "business logic" -- code that might be customized differently for different Slash sites -- belongs in the .pl files, while the .pm modules provide an API that will be general enough for many sites' .pl files to use.)
When you design your own site, you will want to start with our "slashcode" theme (since it's the only one provided at the moment -- submissions welcome!) and modify it to suit your needs.
Since we recommend working from a CVS checkout, you will want a way to keep your modified theme up to date when you upgrade to later releases (whether for features we add, or security fixes that may be necessary).
Once you get a cvs checkout of the slashcode module from cvs.slashcode.com, do a "cp -a themes/slashcode themes/mytheme". By duplicating the associated CVS files, you get a sister directory that CVS will be just as happy to upgrade with your future "cvs update" commands. (Some cvs clients will automatically recurse into that directory with a "cvs update" from the checkout root, which is handy.) The sister starts out as a twin, but you'll be customizing her in the days to come.
The important thing here is that, if you change a file in your customized version, a "cvs update" will properly import new patches to that file while leaving your changes alone; this is part of what CVS is all about, of course. By keeping themes/slashcode in place you will have a reference point to compare again. And our "make install" is set up to copy all subdirectories of the themes directory into place, with each of them becoming a new theme recognized by Slash -- notably by the Slash::Install module, and by the install-slashsite, template-tool and symlink-tool scripts (more on those later).
Our recommended procedure for doing an install of a CVS checkout is not to issue the "make install" from within the checkout, but instead to do a slightly-cleaner copy of the checkout to a new directory and then "make install" from there. The make can leave a few files around that CVS doesn't know what to do with.
If you are installing multiple Slash sites, you probably want to create multiple subdirectories, one theme for each site.
Plugins modify the behavior of themes by installing extra code and data. They commonly have a .pl script which becomes a webpage. They often include one or more .pl scripts which run as background tasks (via slashd). They frequently include templates which provide data, and sometimes include a class, in the Slash:: hierarchy, providing an API to something specialized. They can also include changes to the DB schema, and data to load into the DB, both applied when the plugin is installed.
Normally you will install a theme and most plugins together, using the bin/install-slashsite script. Occasionally, when a site has already been installed, you may add a plugin with the bin/install-plugin script.
These scripts use Slash::Install to determine which files will be used. That module reads the THEME or PLUGIN file at the root of the relevant subdirectory, so e.g., themes/slashcode/THEME or plugins/Admin/PLUGIN. The file format should be obvious on examination.
The first thing you'll want to do with your new theme is to edit its THEME file and edit its name and description. Any templates you add need to be added here, ditto htdocs, images, tasks, and so on.
When you run install-slashsite (or -plugin), we strongly recommend that you do use symlinks. Again, this makes upgrading much easier.
There is an alternate way to write your own theme, and it is to use the include_theme directive in your THEME file. We use this for the slashdot theme that is customized for Slashdot.org but we're not going to go into a lot of detail here about how to use this feature. Essentially it pulls in the templates from another theme (slashcode) and only overrides them where specifically listed -- other files besides templates are still done the same way. This is mostly just useful for us, because we often develop on both themes at the same time and don't want our templates stepping on each other. Read the Slash::Install source if you really want to know more.
Slash makes extensive use of the Template Toolkit, a collection of CPAN modules. Do a perldoc on Template and Template::Manual for details.
Slash loads its templates from the DB; template files on disk are parsed and written into the DB by the template-tool script. We have a three-tier naming system by which any given template is identified. The second and third parts of the name are the page and section, respectively. The page is basically the script name as pulled from the current URI, so when viewing index.pl it's "index". Section is a property of data like stories or polls (and there are two fake sections, "admin" and "light").
On disk, the three parts of the name are separated by semicolons, thus: "themes/slashcode/templates/header;misc;default". Note that on Unix, the semicolon must usually be backslash-escaped on the command line. Inside the file, you will find the "__section__" token followed by the name of the section on the next line. (If you ever goof up and write a file whose name and internal data disagrees, template-tool will let you know next time you run it.)
When retrieving a template, often for display of HTML to the reader, your site will usually just specify the name of the template ("header") and allow getTemplateByName() to figure out which is meant. Usually this is done through a call to Slash::Display::slashDisplay() which takes the name of the template, the data to pass to it, and optional arguments (which, among other things, can override the current page and section).
When you update a site, the template-tool script, when invoked with -U, will read your site's site_info table to find which one theme and zero-or-more plugins you are using; it will scan the /usr/local/slash/{themes,plugins} hierarchy to find the THEME and PLUGIN files needed; then it will scan the /usr/local/slash hierarchy again to find the template files you need. It will write them into the templates table of your site's database (except those marked placeholder, which means template-tool -U ignores them).
Note that if, in writing your theme, you decide you want to override a plugin's template, you can do so by just adding a template of the same name. template-tool -U will overwrite plugins' versions with themes'. Of course, if you really want to change around a plugin a lot, do the "cp -a" trick, rename it, edit it, and edit your THEME file to include your new version instead of our stock version.
After you update templates in your DB, you will want to stop/start both slashd and Apache.
We enjoy the power of the Template Toolkit, it is an effective way to store data mixed with a bit of logic. But for speed, you'll probably want to cache compiled templates [and RAM concerns, etc.]
Even with all templates compiled, TT can be too slow for a very busy production site. For three key functions, Slashdot uses a hardcoded workaround. Grep the code for 'sub _hard_' to see where.
Let's just get this out of the way: in the code, for historical reasons, we have silly names for things related to our four main global variables.
It's these four from which our code gets most of its connection-specific "global" data, in other words, the data which applies only for this one click and can be accessed from anywhere in the codebase (even templates!).
(They are "globals" in the sense that they can be accessed from anywhere. They're actually stored as fields in the Apache request object, see e.g. getCurrentUser() in Environment.pm. The access functions are plain functions, not methods.)
Our constants are not entirely constant; 95% of them you will never need to change, but 5% you may want to tweak from day to day or month to month -- and there is also a handful of vars that are written-to by the code itself. By convention they are always stored in a hashref named $constants.
That hashref is returned by the function getCurrentStatic(), NOT as you might expect getCurrentConstants() -- and to make matters worse its data is primarily loaded from the table named "vars". OK? Vars, Static, Constants, three names for the same data, and yes we realize they are contradictory. (Some constants are loaded from other places, see MySQL.pm getSlashConf() for details.)
$slashdb is the standard name for an object of class Slash::DB::MySQL, which has a dbh (DB handle) pointing to the main (aka writer) DB. Note that in slashd tasks it will be of class Slash::DB::Static::MySQL which is the same thing plus a few extra methods. This is returned by getCurrentDB().
(Handles to other DBs, and/or object wrappers around those handles of different classes, will be returned by getObject(). Yes, we called it getObject() even though the only objects it ever returns are wrappers around DB handles. Anyway, by passing getObject() different arguments, you can get an object of type Slash::Stats, for example, which gives you extra methods to access the DB in addition to the usual ones in Slash::DB::MySQL. Or you can get a handle to a read-only replicated DB, see "MySQL Replication" below for more.)
getCurrentUser() returns you the current user object. It has fields for every column in the user* tables associated with the current user, plus a number of other calculated fields based mostly on that data. For example, $user->{is_admin} and $user->{is_subscriber} are booleans calculated based on other data.
In particular, $user->{state} contains data calculated to be part of the current state of this user for this particular page. Your code shouldn't write to any part of $user except the state field, because it might be the Anonymous Coward and might be reused on the next click.
getCurrentForm() returns you the current form object. This is all the data submitted on the current click. URL parameters from a GET show up here, e.g. $form->{sid}. And POST data appears here too, all processed for your code in the way you'd expect.
If you want multiple values, e.g. Slashdot's use of &tid=1&tid=2 in its URLs, you can find them in an arrayref at $form->{_multi}{tid}.
An important part of Slash's security is in the filter_param() function in Environment.pm. This function knows the names of several dozen params and ensures that the data passed in matches a regex before being stored in $form. For example, everywhere in the Slash code, $form->{cid} is guaranteed to be numeric (if it exists). That means it can be inserted into SQL strings without being quoted, which closes off one particular avenue of attack.
In your code, if a param is not on filter_param's list, remember to wrap $slashdb->sqlQuote() around its data before inserting into an SQL string. Every param NOT on the list is untrustworthy. You must be vigilant about quoting data from untrusted sources -- as a programmer, that is your responsibility -- and all that filter_param allows you to do is relax your guard on the more common inputs.
There are other quasi-globals defined in Environment.pm, but they aren't used nearly as much. For example, getCurrentAnonymousCoward, getCurrentCookie...
All Slash pages have a header, the main body of the page, and a footer.
The header and footer look much the same across the entire site. (Except for admin.pl pages which don't have much of a header.) The header and footer will be loaded from an include file on disk for static pages (slashhead.inc, slashfoot.inc, generated by tasks/new_headfoot.pl) and generated by a template for dynamic pages (templates named header and footer).
The header starts at the top of the page and runs down to include the left column with its menus and links (again, except for admin.pl). The leftmost column of what is called the "maintable" contains a fairly standard menu and some slashboxes with a bit of information about your site. In the stock slashcode distribution you will find the organisation [sic] template there, for example.
The next column over, still part of the header template or slashhead.inc file, is a spacer.
The next column over, in the maintable, will be the main body of the page. Actually its <TD> tag is still created by the header, then what's inside the <TD> is generated by the rest of the page. On index.pl it is the list of most current stories. On users.pl it is the information requested for that hit. On article.pl it is the introtext and bodytext of the story, plus comments. And so on.
The 4th column, where it exists, is another spacer. This is still part of the main body of the page (not header or footer, and generated by whichever page script is running).
And the rightmost column, where it exists, typically contains more slashboxes. On index.pl it is highly user-customizable but typically contains older stories, sectional slashboxes, the current poll, RSS feeds, etc. On users.pl it will contain information about the user being looked at (the userboxes template).
There the main body of the page ends. The footer of the page takes care of closing the </TD> tag, and then having a final table row which typically includes a pithy quote or a search box or what-have-you.
Because different pages have different numbers of columns -- and on Slashdot, the five columns are not the same as the slashcode theme's five columns, the spacers are in different places -- we use a system of processed templates to handle the <TD> and </TD> tags. If you customize templates that require you to open and close those tags, instead of putting the <TD> in the template directly, insert a [% PROCESS maintable_td %]. That keeps track of the rows and columns in your maintable, so when the footer template finally is reached, it knows how many table tags to close up, leaving a nice compliant HTML table. For more on how the maintable is dynamically rendered, grep the templates directory on 'PROCESS maintable'.
Blocks static, portald, and color Apache configuration PerlAccessHandlers, PerlCleanupHandlers, PerlTransHandlers Slash::DB::Utility Slash::DB::MySQL and Slash::DB::Static::MySQL no more postgres
This is a bit of a speciality topic, but if you're interested in running a Slash site, you're probably concerned about performance. One of Slash's key selling points is that it has been proven to scale well to communities of hundreds of thousands of users and millions of largely-dynamic pageviews per day -- and given proper hardware, can probably scale well beyond that.
MySQL supports master-slave replication and it would be wise to use it to achieve best performance. Slash has support built in.
Designate one DB your master ("writer") and create a DBIx::Password virtual_user for it like you would normally do. Then, create one or more DBs which slave off it ("reader"s), start them replicating, and create DBIx::Password virtual_users for them as well.
Then, to take advantage of your new readers and offload a great deal of work from your writer, all you have to do is create entries in your table named "dbs". The format should be obvious: type is either writer or reader, and if you have multiple readers, you will have multiple rows with type="reader". For each such row, the virtual_user column points to a DBIx::Password virtual user, which points to one of your DBs.
If isalive="no", then that reader will not be used until it gets set back to "yes" -- and that setting is not cached, so changes will take effect starting with the next click. If you want to write an "angel" script to turn off this feature when a reader DB goes down, just write values into isalive. Of course, assuming you have just one writer,
The "log" and "log_slave" types are special. Slash writes a lot of data about each click, which lets us keep really detailed stats -- and we scan that log hourly to decide who to give moderator points to. In fact, the I/O load for the accesslog table is several times the I/O of all other database writes combined. And that's assuming you don't log image hits! (Slashdot's load balancer sets image hits to static web servers which don't have the PerlCleanupHandler Slash::Apache::Log.)
There are two ways you can reduce your accesslog load. The first is to just create a type="log_slave" row in the dbs table, pointing to a virtual_user, that points to a DB which replicates only the accesslog table from your main writer DB. That will take the accesslog reads, the hourly moderatorlog scan and the daily stats scan, off your main DB.
The second is to create a separate DB which has only two tables, accesslog and accesslog_admin. This becomes a second writer DB, but a writer which handles only logging. Point a row in the dbs table to it and Slash will automatically direct writes there. For best results, replicate another DB off your type="log" and point a type="log_slave" at it; this ensures that even while moderatorlog and stats are churning away on the slave, the master log DB still have maximum I/O throughput.
All this work with the dbs table is handled through getObject(), which, as mentioned earlier, is only for making database objects. Almost every time we instantiate a DB object which can use a DB other than the master, we call getObject() with the db_type option. If you have set up your dbs table, getObject() will transparently take advantage of all your DBs.
One last comment on replication. Some MySQL table types have advantages over others. As of this writing (summer 2003), we greatly prefer the InnoDB table type for its row-level locking, faster I/O and quicker crash recovery. But the MyISAM table type has FULLTEXT indexing on BLOB columns, which InnoDB does not currently support.
The Slash code doesn't much care what table types you use -- except the Search plugin. Search will try to do MATCH() on columns which it expects to have FULLTEXT indexes; if they don't, for example if you changed that table to InnoDB, it will (as of this writing, and yes we know this is bad) crash. In future, we will fix this so it falls back on a slower search method, but the point is that if you are using master-slave replication, you can gain some additional speed advantage by manipulating table types, but you do have to keep track of them.
The type="search" option in the dbs table is for this purpose. You can have your story_text table as InnoDB on your writer, and replicate it to a slave DB which is for searching only -- your slave will be TYPE=MyISAM on that table (and the half-dozen others that require it). Replication can easily mix types in this way, just read the plugins/Search/mysql_prep file, realize that those changes were probably already applied to your master, then either go undo them on the master or do them only on your search reader DB(s).
In future, MySQL may support better ways of distributing reader load, and when they do we'll look at enabling support in Slash, but for now, this is the best way to do this.
Slash::Utility::Anchor, headers and footers and ads hooks Slash::Test Slash::Constants slashd and tasks freshenup and the importance of rendered .shtml pages adminmail and stats_daily "task_timespec_foo" vars to override tasks/foo.pl's timespec users the users_* tables, why so many? the A.C.(s) seclevs ACL (cf. AL2) authors vs. admins vs. regular users stories, story_text they own discussions, and normal form is broken by pulling up disc data into stories table writestatus, freshenup, and the archiving process the hitparade, freshenup, and the kludgy comment-counting process displaystatus: AD/sectional/ND performance issues, mostly thanks to "ORDER BY time" someday we'll have a numeric primary key discussions and comments discussion id at the root, cid-pid tree growing from it some discussions get archived, some get recycled /comments.pl?op=user_created_index commentstatus ("who can post?") other discussion owners: journals, polls, user-created moderation goals the rules: tokens, handing out tokens (tasks/run_moderatord.pl), points, expiration (stirring), inactive, other modifiers meta-moderation goals the rules: tokens, inactive, frequency, reconcilation (tasks/run_moderatord.pl) plugins/Messages: the messaging system (pudge: what to say about this?) AL2 and Slash::Apache::Banlist writing RSS pages: open_backend.pl plugins/HumanConf sections index.pl isn't always the homepage subdirectories and virtualhosts
The site is running, you can get a front page to display, and slashd is generating static .shtml files. What do I do now? How do I administer the site? How do I change the way it looks? How do I post stories or user submissions? This guide is to answer these and other questions, questions that I've seen asked on the mailing list time and time again. There's been a great need to explain the admin interface for quite some time now. This should hopefully satisfy this need.
The first thing you need to do (and you should do this to get the most out of this document) it log in as an author. (note: make sure that the author you log in as has a seclev of at least 10000. The default author that you set up when you use install-slashsite has this security level.) You can find the login form on the front page or at http://yoursite/users.pl .
After you have logged in as an author, you will now see a navigation bar, or navigation list on the top of the page. This is the admin menu. In this list there are the URLs to the various functions of the admin interface. This admin navigation bar will only show links to the admin tasks that the user you're logged in has access to (the "seclev" value for this author).
To log out, go to preferences and click the "Log out" link.
- Stories:
-
Stories reside in the middle section of the page and have the intro-text of the stories along with the authors and what departments they are from.
- Comments:
-
Users may write comments about a story.
- Submissions:
-
Stories are submitted by users, and then approved by authors.
- Users:
-
Users are registered to use the site, all other visitors are logged as Anonymous.
-
Authors approve submissions, have the authority to change the look of the site, and can moderate.
- Sections & Topics:
-
Seem similar.
Sections are similar to the way a newspaper is laid out, i.e.: business section, sports section, local section, etc.
Topics can appear anywhere, share similar concepts.
The home page has stuff from all sections.
- Blocks:
-
Located on the right hand side, blocks can be customized by users.
- Templates:
-
These store the html for boxes, fancy boxes, headers, footers, etc. The template is where the look of the site can be changed. Inside the templates is where you will spend the majority of your time for site design changes.
- Variables:
-
Govern how links are created, etc.; don't normally need to change them.
Click on the link "Stories" on the admin menu. On this page you'll see the stories that are running on the site, grouped by the day that they are running on.
The first column is a number. This is a link to edit the story. Go ahead and click on any one of the numbers for any story that's running. This will take you to a "Story editing page".
The second column just links you to the story as the story will be seen (to article.pl).
The third column is the author of the story, the fourth column is the topic, the fifth column the section. The sixth column has two numbers - the first is the total hits for the story, the second number is how many comments there are. The final column is the timestamp of the story.
The top of the page is the title and body of the story, as it would be displayed.
Going down, next you'll see a block that has three buttons, three pulldowns, and two text fields. The buttons do what they are labeled as, the first pulldown is the topic the story is categorised into, the next pulldown is what section the story is running in, the third pulldown is the author the story is running as. The next text field is the stories title, and the text field below that is the department that it runs as. (Each word that you type in this text field is displayed with dashes between each word. If you enter "this is a test", it will be displayed as "from the this-is-a-test dept.".) Next, you'll see two more pulldown and a text field containing a date. The first pulldown gives you three display options. You can select to not display the story at all, restrict it to one section, or run it for every section (default). The next pulldown selects whether a story can have comments or not. You can use this to restrict the story to being read-only.
The fixquotes checkbox is for fixing curly quotes if you've pasted text that includes them. The autonode checkbox is for automatically creating glossary-style links to http://everything2.com but it doesn't seem to work anymore. The fastforward checkbox moves a story to the first position on the page (by changing its date).
The timestamp text field contains the time and date that the story will run on. You can set it to a future date if you want a story to be delayed. Below this you'll see a text area for the story copy. This is the full text of the story. You can put html tags in your text if you wish. Below this box, are the same three buttons that you see above. These have the same form action as the ones above, and are only there for convenience. Below this is the extended copy text area. This is if you're doing a longer article such as a book review, or a commentary. Below that is an "import image". This is something that is being worked on. In other words, it doesn't really work yet! You can see how this page works by changing any on of these values for the story. If you select "preview" it will only display what the change would look like, if you hit "update", it will update the story in the database (and on the site), and display what the change looks like.
As admin:
To post a new story, you need to click on the "New" admin menu link. This takes you to a "Story editing page". Fill out this form with all the values for the story you want to run. To view it before saving, click on the "preview" button. Once you feel that the story is ready to be published, you can click on "save". This will save the story to the database. You may post-date the story to run at another time in the time stamp field, if you want. This is often handy when you want some time to decide if you really want to run a particular story.
As a regular user:
Same as above, but use the "Submit Story" link from the main menu. The story must be approved by an author before it appears.
Below the story, there is a bar with a "Reply" button which can be used to post a comment on a story. Each comment has a "Reply to This" link which can be used to comment on that comment.
There is a selection box that will allow you to format your message in any of four ways:
Plain Old Text HTML tags are interpreted, <br> tags are inserted for you HTML Formatted HTML tags are interpreted, you must add your own <br> tags Extrans HTML tags are quoted Code HTML tags are quoted, text is formatted as code
To approve user submissions so they show up as stories, click on the "XX Submissions" link (XX being a number). This will take you to a page listing user submissions.
Above the submissions list are links that will reload this page according to sections. For instance, if you click on the link for "articles" this page will only display submissions that are in the "articles" section. The links on the left are categories set by the second column.
Next is the submissions list.
The first column is a notes block. This is for the author to write a note pertaining to a particular submission, so the author, or other authors, can have something to refer to in the case where they may not want to publish a particular until a later time.
The second column is also for classifying submissions. Unless you have hundreds of submissions like slashdot does, you probably won't need those fields.
The third column is which section the submission is in.
The fourth column contains a box that if checked will delete the submission.
The fifth column is the timestamp of the submission.
The sixth column is the title of the submission, which is a link to edit the submission. If this is clicked, it takes you to a submission editing page that works just like the "Story editing page", and in fact if the author previews the submission, the submission then is pulled up in the story editing page where the author can edit the submission further, and decide if the story should be published or not.
The seventh column is the name of the person who made the submission.
To edit, add, or delete a topic, click on "Topics" from the admin menu. This will take you to a page showing all of the site's topics icons, with a topic name listed below each icon, which is a URL to edit that topic. If this URL is clicked, you will be taken to a page that allows you to edit the topic, select a new topic to edit, create a new topic, or delete the topic.
The first item on the page is a pulldown with all topics. You can change the topic you want to edit by selecting whatever topic you want from the pulldown and clicking "Select topic". If you want to create a new topic, you click on "Create new topic". Below that, the icon for the topic is displayed (as it would be seen). Next is the "Tid" text field. This is the topic ID. Next are the width and height that the image is displayed as, and the text that's displayed in the "alt" tag. Next is a pulldown of all the images that are available in the images/topics directory. If you want to have a new image to select from, you'll need to upload and/or copy it to that directory. Finally, there are the "Save Topic" and "Delete Topic" buttons. They do what they say they do.
Most important to how the site looks are the blocks, which are edited, added, and deleted via the block editing form. This form essentially manipulates the blocks and sectionblocks tables. To get to the block editing page, click on "Blocks" from the admin menu.
On this page, you start out with two pulldowns, each having two buttons: one for editing the block, and one for deleting the block. The first pulldown selects all non-portald blocks, meaning blocks that aren't populated by portald. They are static blocks, their content (what's contained in the column "block" in the blocks table) doesn't change unless you change it, whereas the portald blocks are updated by portald. Below these two pulldowns is a "Create a new block" button, which you can use to create a new block. Upon selecting a block and clicking "Edit Block" (or creating a new block), the block is pulled up in the block editing form. This form has these elements:
Block ID The block ID Title A title for the block Seclev The minimum security level an author must have in order to edit this block Type The type of block that it is. This is a new concept for blocks and is still being developed, but the current type of blocks are color, static, and portald. If you end up setting a blocks type as "portald", it will then be seen in the portald pulldown, otherwise, it will appear in the static blocks pulldown. Section If a block is set with a specific section, the block will only appear in that section if its "portal" value is one (meaning it's a user selectable slashbox). Ordernum This is the order number of the blocks that appear on the right side of the page. These are the default blocks for all users. If the ordernumber is -1, it's a user selectable slashbox, if the ordernum is 0, it doesn't appear at all. If the number is 1 or greater, this is the order that it appears on the right side of the page for Anonymous Cowards and users that have not specified their own preferences for slashboxes. Portal If this is checked, then this block shows up on the slashboxes selection in users.pl. Retrieve If this is a portald type block, and this is checked, portald will retrieve the content for this block from the URL listed in the next box, RDF/URL. RDF/URL The URL from which portald gets the content for this particular block. Description A text description of the block. Block The actual block itself. You can only change non-portald blocks (well you can change portald blocks, but portald will overwrite your changes). Revert to default Use this if you make a mistake while editing the block, or want to revert to what it was originally. Save as default Use this if you are confident that you want this to be the saved default, in case you later edit the block and want something to revert back to. Save Block Saves the block Create a new block Opens a new form to create a new block. Preview This previews slashboxes. Don't try it with blocks that are code blocks, or partial blocks, it won't work correctly.
Templates contain the actual HTML that is used to generate all of the dynamic pages in Slash. Click on the "Templates" link from the admin menu. There are three drop-down menus: Section, Page, and Templates. The "sections" on this page have nothing to do with the "sections" that contain the Slash topics.
There are three sections:
admin Contains the templates for admin pages light Contains the templates to be used when users are in "light" mode. These pages are designed for people with slow connections and should not contain too many large graphics. default Contains everything else
In addition, you can choose "All" for the section in order to access all of the sections at once.
When you click the "Select section" button, the page will refresh and the "Templates" menu will contain a list of all the templates in that section.
The "Page" menu can be used to select the templates from a particular page. Pages generated by a CGI script will generally use templates from the page that has the same name as the script (eg. "users.pl" uses templates from the "users" page). The "Select page" button will cause the page to refresh, and the "Templates" menu will contain all of the templates from that page.
You can select either a section or a page, but not both.
The "Templates" menu will contain a list of the selected templates. Each template has both a name and a number. Two templates from different sections or pages may have the same name, but the number will always be unique. Templates with higher numbers were created after the ones with smaller numbers. Once a template is chosen, it can be either edited or deleted. The "Create new template" button on the bottom of the page allows you to create new templates.
The template editing page will allow you to change the text and the properties of a template. The "Seclev" field sets the minimum security level that is required in order to edit the template. At the bottom of the page, there is a textbox field containing the text of the template. Anything enclosed within [% ... %] will be interpreted by the template-toolkit. To learn about this syntax, go to http://www.template-toolkit.com.
You can view the source of any Slash page in order to see which templates are being used. The source will contain the names of the templates enclosed in html comments. For example, at the beginning of the template editor page:
<!-- start template: ID 7, header;misc;admin -->
....HTML stuff....
<!-- end template: ID 7, header;misc;admin -->
The above shows that the "header (7)" template is being used, from the "misc" page in the "admin" section.
This is where you can change the colors of the site. Click on the "Site Colors" link from the admin menu. This will take you to a form that has a pulldown to select which colorblock you want to edit (you can have a colorblock for each section, which you would create in the block editor, and it must be named "section"_colors). Click on the "Edit Colors" button to edit the color block you select (the default is the main color block "colors"). You will then see a list of eight colors, with four columns:
The color name The name of the color, and the variable it gets assigned to The color value The actual value of the color, hex or canonical. Make sure this is a valid color, or it might not display properly. The color name displayed in the font color selected The color A table cell with the selected color
Next are the buttons. If you click on "Preview", you'll see the color you are selecting, as well as providing a link at the top of the page that's a URL to index.pl which will display using the color you want to preview. Clicking on "Save Colors" will save the colors you've selected, "Revert to saved" will reload the form with the last saved values of colors, "Revert to default" will reload the page with the default colors, and "Save as default" saves the colors as the default. Again, as with the blocks, you want to make sure this is what you want saved as the default for your site.
Click on "Sections" from the admin menu. This will take you to a page with a URL list of the site's sections. If you click on a particular section, it will then take you to a form for editing the section. This form contains:
Section name contains the section id Article Count the value for how many articles to display on section index Title the canonical name for the section Polls for this section selects which poll to display for the section Isolate mode determines whether the section is part of the site or standalone Issue mode whether the section is issue oriented, article based, both, or neither Edit section URLs to the block editor for blocks that are specific to the section save section save changes that you've made to the section add section opens up a new form to create a new section delete section delete the section
Comment filters are regular expressions that are run against content, the comment subject or comment body. If a particular filter is encountered, a message is displayed informing the user, both on submit and preview of the comment. This gives you the ability to prevent certain things from being posted on your site which is totally dependent on what you want to filter, or not filter. Click on "Comment Filters" from the admin menu. This will take you to listing of all the comment filters. This list shows various columns for each filter:
Filter id the ID for the filter. This is a URL that brings up the filter in a filter editing page. Regex this is the core regex of the filter Modifier the modifier that would go on the end of the regex, ie. if the modifier is "gi" the regex would be evaluated as /xxx/gi Field The form field that the filter is run against. Currently, only postersubj (the comment subject) and postercomment (the comment body) are supported. Ratio The percentage that the match will check for. For example, if "Regex" is "(flame)", "Ratio" is 0.1000, the text being checked is 100 characters in size, the regex is put together as /(flame){50,}/. If you have the field "Minimum match" set greater than zero, this won't be used. This won't be used if set to zero. Minimum match This is a hard coded minimum match for the regex. If "Regex" is "(flame)" and Minimum match is 4, the regex constructed will be /(flame){4,}/. Ratio will not be used if this is set greater than zero. This won't be used if set to zero. Minimum length The minimum length the field must be for the filter to apply Maximum length The maximum length the field must be for the filter to apply Error Message The message that's displayed after the "Lameness filter encountered".
You can also create a new filter with the "Create a new filter" button.
This is for editing site variables. Select one from the menu and click the 'vars' button to see its current value and a description. You'll need to restart apache and slashd for changes to the vars to show up.
The main ones you'll want to edit for now are slogan and sitename.
Turn cache_enabled off to get faster responses while you're working with templates.
The send_mail var turns the headline mailer on/off. You may need to set smtp_server too. And the stats_reports one will get you a daily stats report.
Revision 1.7 2004/10/18 16:56:15 jamiemccarthy Allow vars to override task timespecs. Don't know why we didn't do this a couple of years ago, this is simple and will work.
Revision 1.6 2003/07/07 22:18:24 jamie Filled in skeleton for themes/plugins, templates, page layout and replication.
Revision 1.5 2003/06/30 19:06:30 jamie MySQL notes.
Revision 1.4 2003/06/23 13:28:16 jamie Bad syntax, but includes the skeleton of what I hope this will become.
Revision 1.3 2002/04/22 14:01:50 pudge Various login fixes: s/(log)(in|out)/$1 $2/gi for @verbs; add proper links to creating accounts etc. on login forms; fix ~$nickname URIs for when $nickname contains some encoded characters (like "/").
Revision 1.2 2001/11/03 04:22:45 brian Fry :)
Revision 1.1.2.2 2001/10/10 16:06:26 pudge Doc updates
Revision 1.1.2.1 2001/10/09 17:54:04 pudge Add in slashguide (rewrite of getting_started) and update docs
Revised for Slash 2.0.0 by Nathan Vonnahme and Dan Stahlke.