NAME
slashguide - The guide to using Slash version 2.0.
So I have Slash installed, what do I do now?
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.
Logging into the admin interface
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).
Logging out
To log out, go to preferences and click the "Logout" link.
Overview of Slash concepts
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:
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.
The story list
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 the Story editing page entry elsewhere in this
document.
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.
Story editing page
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.
Submitting a new story
As admin:
To post a new story, you need to click on the "New" admin menu link.
This takes you to a the Story editing page entry elsewhere in this
document. 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.
Commenting on a story
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,
tags are inserted for you
HTML Formatted HTML tags are interpreted, you must add your own
tags Extrans HTML tags are quoted Code HTML tags are quoted, text is
formatted as code
Approving user submissions
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.
1. 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.
2. The second column is also for classifying submissions. Unless you
have hundreds of submissions like slashdot does, you probably won't
need those fields.
3. The third column is which section the submission is in.
4. The fourth column contains a box that if checked will delete the
submission.
5. The fifth column is the timestamp of the submission.
6. 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 the Story editing
page entry elsewhere in this document, 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.
7. The seventh column is the name of the person who made the
submission.
Topics
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.
Blocks
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
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:
....HTML stuff....
The above shows that the "header (7)" template is being used, from the
"misc" page in the "admin" section.
Site Colors
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.
Sections
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
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.
Variables
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.
CHANGES
$Log: slashguide.pod,v $ 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
AUTHOR
Revised for Slash 2.0.0 by Nathan Vonnahme and Dan Stahlke.
VERSION
$Id: slashguide.pod,v 1.1.2.2 2001/10/10 16:06:26 pudge Exp $