INSTALLING SIPS 0.2
-------------------

Revised for sips 0.2.4.

Requirements:
Any webserver capable of processing PHP. The oldest PHP version that SIPS will
work with is 3.0.8. The latest PHP4 releases should also work.

This guide assumes a *nix platform with regards to file permissions etc, so
users of non-*nix platforms such as Windows can safely disregard that
information.



1. COPYING FILES

Unpack the sips archive file. Sips requires a special directory where it
stores all kinds of data such as users, stories and php code. This directory
can be anywhere, but if you can, you should place it outside of the public
html area of the server, for security reasons. This directory is referred to
here as "SIPSSYS", but you can call it anything you want. In fact, you _should_
call it something different for security reasons.

Create the SIPSSYS directory, and copy all files in the sipssys directory from
the archive into this directory.

Here's a list of what persmissions you should grant the files and directories
under the SIPSSYS directory:

SIPSSYS                 711
SIPSSYS/boxes           777
SIPSSYS/code            755
SIPSSYS/code/*          644
SIPSSYS/sites           777
SIPSSYS/stories         777
SIPSSYS/themes          711
SIPSSYS/themes/default  755 (also applies to other themes you put here)
SIPSSYS/users           777

This are the minimal values, and sips will probably not function properly with
any less.

Now, copy all the files from the htdocs directory in the archive into the
directory on your webserver that will be the root of your site. This directory
should be chmod'ed to 777 (if you can't do this, sips will error when trying
to put RSS headline files into it, you can solve this by manually creating
the files backend.rss and recent.rss).

All files under "htdocs" need no more than 755 for directories and 644 for
files, with the one exception that htdocs/admin/stories/contrib needs 777 since
sips stores pending story submissions there.

NOTE: Because of how cookies work, you cannot (well you can, but shouldn't)
nest sips-sites. For instance, you cannot run one sips site at
http://yoursite.org and another one at http://yoursite.org/othersite/. However,
you should be able to run one sips site at http://yoursite.org/firstsite/ and
another one at http://yoursite.org/othersite/.


2. INITIAL CONFIGURING OF SIPS

You have to edit the file .sipsconfig.php which is in your webroot. This
file is read by all sips files and contains all parameters of sips that
can be customized. The included file should be sufficiently commented and
self explanatory.


3. BECOMING AN ADMIN

The first thing you should do, is make a user for yourself. Do this by clicking
the registration link in the login box on the front page (if you get errors
doing this, check all your permissions and the settings in your
.sipsconfig.php). When this has been done, go to htdocs/admin/become.php. This
little file makes any one user administrator, no questions asked. Fill in the
username of your new user, and voila, you're now the first administrator of
your sips site. become.php may now have deleted itself for security reasons,
but if it didn't, that means you've been clever in setting the permissions,
and you MUST manually delete become.php. If you don't, your site is wide open
to crackers!

You may later want to have other users become administrators. Do this in the
"administrator" section of the sips admin area.


4. CHANGING THE LOOKS

What sips actually displays to the user in the shape for HTML, is defined in
template files sorted into theme directories in SIPSSYS/themes. If you want
anything better than the super-dull example theme that comes with sips, you
have to change these. Actually, you absolutely _have_ to change them anyway,
since they contain links and references that are fictional and won't work with
your site.

The example theme that comes with sips consists of all the files in
SIPSSYS/themes/default/. You can add as many themes as you want by placing
similar files in other directories in SIPSSYS/themes/, for instance, you
can put your own super-hip template files into SIPSSYS/themes/superhip :)
Users can choose which theme they want in preferences.php.

I'll guide you quickly through all the template files so you get an idea:

* SIPSYS/themes/*/siteheader
   This is the opening part of every sips page. It opens the HTML, writes
   any standard headers, tables etc. that you want for every page, and
   so on.
   #TITLE# - will be replaced with something like "sitename | news" (for the
   front page, similar values for the other pages). Use this between the
   <title> tags.
   #DATE# - prints today's date on the page. Example: "Wednesday, April 12"
* SIPSYS/themes/*/story
   The template used for each story.
   #TITLE# - prints the title of this story
   #AUTHOR# - prints the name of the person who posted the story.
   #TIME# - prints the time of posting (not the date)
   #DATE# - prints the date of the same story
   #TOPICICON# - prints a linked image tag that shows the topic icon which when
   clicked searches for recent stories of the same topic.
   #TOPICTEXT# - Same as #TOPICICON#, only textual, not graphical
   #STORYTEXT# - the actual text of the story. On the frontpage, this will be
   the summary, and when in story.php, this will be summary + body.
   #LINKS# - prints a string of links when on the frontpage. The links may be
   "Full Story", "Related Stories" and "Related Sites".
   NOTE: This keyword must be encapsulated in <LINKS> and </LINKS>. These are
   not HTML tags, but special mark-up that delimits the area to be stripped
   when not relevant (that is, in story.php). So at a minimum, this would read
   "<LINKS>#LINKS#</LINKS>".
* SIPSYS/themes/*/box
   Template used for each box.
   #TITLE# - the title of the box.
   #CONTENT# - the actual content of the box.
* SIPSYS/themes/*/frontpage
   This template is parsed by the frontpage (index.php in your webroot), and
   lays out where the boxes and the stories will go. The example file contains
   a form to search stories. This can't be layed out with keywords, but if
   you want it in your frontpage, simply cut-and-paste it in, beautifying
   it in any way you want
   #BOXES# - prints all the boxes here.
   #STORIES# - all the stories go here.
* SIPSYS/themes/*/post
   Used in post.php, which is the story submission page for users.
   #FORM# - prints the submission form and story preview.
* SIPSYS/themes/*/sitefooter
   Closes the HTML. This is the last thing being sent to the browser, so be
   sure to close any tables etc. that you opened in siteheader, and of course,
   close the body and the html.
   
   
You can omit any of the keywords in any of the files if you want. For example,
you may not want to print the date in siteheader. Of course, omitting things
like #STORIES# in frontpage isn't going to make much sense! ;)

Although the same keywords are seen in different template files, they are not
the same. They have special meaning in each file. Also, you cannot mix the
keywords into files in which they don't belong. So using #DATE# in
sitefooter won't work (this would simply show the string "#DATE#" in the
browser...).

Additionally, you can put a file called .themeconfig.php in with the rest of
the theme files. In this file, you can override any of the items in
.sipsconfig.php on a per-theme basis. If you're a complete idiot, you'll
override such items as $config["sitename"] or $config["httpbase"], which is
guarranteed to get you into trouble. However, overriding
$config["lightmarkcolor"] and $config["darkmarkcolor"] makes perfect sense
since you might want different markup colors for your different themes. Also,
you might change the cachetimes (for some reason) or $config["maxstories"] to
better match your visual design for that theme. In summary, use with sense!!


5. SETTING UP TOPICS

Each story you post to your sips site belongs to a topic. This allows for
categorization of news. In admin->Topics->Add, you can add topics you
expect to be relevant for your site. Follow the on-screen instructions
for uploading the topic icon which must be in place.

There is always one topic present: the "general" topic. You cannot
remove this topic. (You can of course change the topic icon though ;)


6. SETTING UP BOXES

"Boxes" are the things on the right side on the front page of the default
sips, often displaying news headers from other sites, or things like login
boxes or other messages to the user.

Sips boxes can consist of up to five things: An identifying title, a header,
an URL, static text (often HTML formatted) and an absolute path to a file to
be included. All but the name and title are optional, but you really want at
least a header and either an include file or static text.

You can make your own custom boxes in admin->Boxes->Add. To grab headlines from
other sites, you have two possibilites. In the best case, the site of interest
offers an RSS file (often referred to as RDF). This is an XML application that
describes the site and lists the newest headlines. sips can read these files
and use the headline listings. To do this, simply fill in the complete URL to
the RSS file in the "Include" field of the form, prefixed with "RSS:", for
example "RSS:http://www.mysite.org/mynews.rss". You also have to fill in a
name and a title for the box as a minimum. In good spirit you should also
fill in the URL field to make the title link to the site.

If the site offers a file of a format different from RSS, you can still grab
it's headlines, but you'll need a custom PHP script that parses that file.
A whole lot of these scripts are found at
<URL:http://swamp.chl.chalmers.se/backends/>. Fill in the path to this script
in the Include field (note - local path, not URL).

A special box is included that is called "login". This box simply deals with
displaying login information and a login form. You can't edit this box within
sips, but if you really need to, edit SIPSSYS/boxes/login in an editor.

Users generally depend on the "login" box to be able to log in. If you don't
want _any_ boxes though (that is, you don't have #BOXES# in the frontpage
template), you should provide a link to login.php somewhere in the siteheader
or sitefooter template if you want users to be able to log in, and another
link to register.php if you want new users to be able to register themselves.

You might want to have a box in which you display "recent stories", that is,
stories that have recently been taken off the front page listing. This is
very simple: In your .sipsconfig.php, set $config["enable-recent-rss"] = 1.
This will make sips keep an RSS file of your recent stories. This file will
be placed at http://yoursite/recent.rss (make the obvious
substitutions). Use this URL as a value for the Include field of a box, again
prefixed with "RSS:" since it's an RSS file afterall, and voila.


7. SETTING UP USER ACCOUNTS

This is handled pretty automatically. You do have to give the SIPSSYS/users 
directory 777 in access rights. All data on all users are saved in this 
directory.

In addition, you have to configure the default user. This is the user for 
visitors who aren't logged in, and many of the values for this user are
given to new users as default values, which makes this user particularly
important. By editing SIPSSYS/users/d/default/user, you can specify which boxes
that will show up for this user. By minimum, it should have these three lines:

-  "Boxes::login". This will allow people to create users for themselves. Of
   course, if you want a user-less system, you can omit this box too. You can
   add as many boxes as you want, seperating them by commas. For example, to
   have default readers see the login box as well as a "recent stories" box you
   have created, have the line read "Boxes::login,recentstories".
-  "Timezone::Greenwich Mean". This specifies which timezone the default user
   will have. All subsequent users will inherit this value. If you want to
   set a different timezone, use one of the values in
   SIPSSYS/code/timezones.inc.php (the strings, not the numbers :)
-  "Theme:default". Specifies which theme the default user get, and which theme
   is set by default for new users. Can be any of the directory names in
   SIPSSYS/themes.


8. SETTING UP THE SEARCH ENGINE

If you enabled the search engine in .sipsconfig.php, you want to enter some sites
into it. A site consists of a title, a description, and of course a URL. Each
site is part of one category, and categories can be nested. If you add a keyword
to stories as you post them, the story will appear on the front page with a link
to a search for that keyword in your sips search engine, and you want something
to come up on that search, so every keyword you use should have at least one
matching search engine hit. If this isn't the case when you post with a
keyword, a form will come up to let you enter a corresponding site.

Also, if you have something special to say for your search engine, you may want
to edit the welcoming text in WEBROOT/search/index.php.


9. EXPORTING NEWS

Other sites can import the headers and links of your latest stories by parsing
the automatically generated RSS file which is in the html root of your sips
site. The file is called backend.rss. The file will reside in the root of your
sips site.

Setting $config["export-rss"] = 0 in .sipsconfig.php will disable the generation
of the RSS file, if that is what you want. Although there may be valid reasons
for wanting this, the general rule is: export your headlines for other sites
to grab, it'll give you more publicity (and hey, information wants to be
free ;).


Good luck with sips, and please send your feedback (good or bad or both) to
haakon@nilsen.com!
