************************************************************************
* Orca Knowledgebase v2.0b                                             *
*  A small and efficient knowledgebase system                          *
* Copyright (C) 2004 GreyWyvern                                        *
*                                                                      *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or    *
* (at your option) any later version.                                  *
*                                                                      *
* This program is distributed in the hope that it will be useful,      *
* but WITHOUT ANY WARRANTY; without even the implied warranty of       *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
* GNU General Public License for more details.                         *
*                                                                      *
* You should have received a copy of the GNU General Public License    *
* along with this program; if not, write to the Free Software          *
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 *
* USA                                                                  *
************************************************************************

- Script Requirements:

PHP 4.1.0+
MySQL 3.23+


- Changelog
2.0b - Added locale display for dates and times
       - Note that this changes the format of $sData['dateformat']
     - Added Polish language file by Marek Krasa

2.0a - Added French language file by Andy Funnell & Tian
     - Various small layout and asthetic fixes


I. Installation Instructions


1. The Orca Knowledgebase comes with six (6) files:

knowledgebase.php         - Plain knowledgebase setup
knowledgebase-control.php - Knowledgebase control panel
okb_head.php              - Header PHP
okb_body.php              - Body PHP
okb_style.css             - Stylesheet
okb_lang_en.php           - English language file

Make sure you have all of them!


2. Open the "okb_head.php" file.

At the top of the file you'll see a list of variables under the heading
"User Variables".

The SQL variables $hostname, $username, $password, and $database are all
values relating to logging into your database system.  If you don't know
these, your host should.  Send them an email.

$dData['rlistmax'] is the number of knowledgebase questions to list on
the User GUI before the program starts pagination.

The Knowledgebase gives users the option to send you questions they
weren't able to find answers for.  For this ability, you need to include
an email address where you can receive these questions.  Enter it under
$dData['email'].  This address won't be displayed anywhere online.

Finally, the default setting for the script is to display an "Ask the
administrator" email form when the user enters a search.  You can force
this form to appear always by setting $dData['userask'] to true.

You can now close the "okb_head.php" file.

Open the "knowledgebase-control.php" file.

Choose an $admin name and $password for editing your Knowledgebase.  If
you ever forget these values, you can just open this file and retrieve
them.

Fill in the MySQL information again, making sure to specify the same
tablename as in the "okb_head.php" file.

$dData['qlistmax'] is the number of knowledgebase questions to list on
the Control Panel before the program starts pagination.

The $fData['filemax'], $fData['resource'] and $fData['fileext']
variables all control the File Upload capabilities.  "filemax" is the
maximum filesize (in bytes) that the script will accept, while "fileext"
is an array of all the file extensions the script will accept.

$fData['resource'] is the name of the directory where you wish the
Control Panel to store uploaded files.  After you choose a directory,
you'll need to create it manually, and CHMOD it to 766 or 777 on Apache,
or give PHP full writing permission on Windows.  THIS STEP IS IMPORTANT!
The script won't create this directory on its own.

$sData['orderby'] is the default ordering scheme for the question list
in the control panel.  Other options are listed for you to the right.

Finally, make sure to include the appropriate stylesheet and language
file here.

You can now close the "knowledgebase-control.php" file.


3. Place all of the files except "knowledgebase.php" and
"knowledgebase-control.php" in the directory /orca on your web server.

Place "knowledgebase.php" and "knowledgebase-control.php" in the
directory just below /orca which will result in the following setup:

/knowledgebase.php
/knowledgebase-control.php
/orca/okb_head.php
/orca/okb_body.php
/orca/okb_style.css
/orca/okb_lang_en.php

NOTE: You may actually setup the files any way you wish, you only have
to change the includes as listed in "knowledgebase.php" and
"knowledgebase-control.php", but I find it easier to keep them together
in this fashion.


4. Now visit knowledgebase-control.php through your internet browser.
If you get the login form, the knowledgebase has successfully created
the database to store the messages and is ready to go!


II. Using the Control Panel

5. The Orca Knowledgebase uses a Category/Subcategory setup in which to
store questions and answers.  In order to add a Question you'll need to
first create a Category, then a Subcategory to store it in.  Let's do
this now.

Log in to the Control Panel using the login form on the front page.  A
list of headings will appear.  If a heading appears in blue text (you
can change this colour in the stylesheet) you can click on it to expand
more options.  If JavaScript is disabled, these menus will be expanded
by default.

The Orca Knowledgebase operates in two modes: Editing and Uploading.

a) Editing Mode:

In the Editing mode, a unique design of the Orca Knowledgebase is that
if the options are available, that menu will always be displayed, no
matter what operation you are currently performing.  This means that in
the middle of typing in a Question, you can decide to cancel it, and add
a new Category instead, all without going back on your browser.  The
option to add a Category is always available.

So let's add our first Category.  It would be good planning to draw out
your Category/Subcategory system before you start adding them, but you
can always change them later.  Click on the "Category Controls" heading
to expand the menu.  You'll see an "Add Category" option.

Type in the name of your first Category and click "Add".  Now when you
click the "Category Controls" heading, more options will appear.  Most
important is the "Select Working Category" option.  This option will
tell the script to remember what Category you're working in, so you edit
the Subcategories of that Category.  So in the "Select Working Category"
dropdown menu, select the category that you created and click "Select".

Notice that the current working Category is displayed in the "Category
Controls" heading, and the "Subcategory Controls" are now available.  We
can now add a Subcategory.  Do this in the same way you created a
Category, then choose it as the Working Subcategory just like you
selected the Working Category.  You can now add your first Question in
this Subcategory!

Click the "Add" button in the Question Controls menu.  This will bring
up a form with a number of entry fields.  The first is the Category.
You must select *at least* a Category before you can add questions.  You
can add questions before you select a Subcategory, but you'll be asked
to specify or create a new one before your entry is accepted.  In this
way, select a Subcategory to add your Question in, or create a new one
by selecting "New Subcategory >>" and enter the new Subcategory name in
the blank field.  If you have already selected a Working Subcategory,
that Subcategory will be selected as default.  If you add a new
Subcategory, it will be added to the current Working Category.

Next comes the "Online" checkbox.  Checking this box will display it in
the list of searchable questions in the User GUI, while leaving it
unchecked will keep the question private.  This feature allows you to
edit a question over a period of time before it is complete and ready to
be displayed on the User GUI.

Now type the Question which this entry will answer.  The best questions
make sense out of context, describe the problem efficiently, and are
keyword rich.  Remember that this is the phrase users are going to see
up front on the User GUI, and will be the deciding factor in whether
they click on it or not.

Next insert your answer.  This field can accept HTML so feel free to
spice up your answer with headings, lists, paragraphs, bolds, italics
etc.

If JavaScript is enabled, two buttons will appear beneath the Answer
textarea.  These are quick-add buttons which will add the appropriate
HTML code to insert images and links.  All you need to do is point them
at the right files and/or fill out the link text.

Finally, insert keywords for this Question in the textarea provided.
When searching, the script will examine both the Question and Answer for
the terms.  If you feel this Question requires more importance for
certain terms, including them as keywords will ensure that this question
ranks higher than similar questions without those specified keywords.

Click "Add" to add your question to the database.  Your entry *must*
have at least the Subcategory, Question and Answer fields filled in
order to be accepted.

Your Question will now appear under the "Question Database" header with
a small button marked "E" which stands for Edit.  Clicking this button
will bring up a form similar to the Add Question form, allowing you to
edit that Question.  However, there are some important differences, so
click the Edit button and let's take a look.

The Edit Question form first displays some vital information about the
current question.  Namely its Question ID#, the date it was Last Updated
and the number of hits it has received from the User GUI.  When editing
a Question, you are now able to change the Category the Question resides
in.  Doing this will prompt you to select or create a new Subcategory
when you are finished editing.  You can only select existing categories,
and the current Working Category will be selected by default.

The rest of the form works in the same way as the Add Question form, so
nothing new here.  Click "Finished Editing" to submit your changes.

Lastly, going back to the "Category Controls" and "Subcategory Controls"
menus, there are also options to rename and delete categories and
subcategories.

By renaming a category/subcategory, all associated questions will be
updated with the new name.  To delete a Category/Subcategory, you'll
need to check the three checkboxes to confirm your action.  Deleting a
Category/Subcategory WILL DELETE ALL QUESTIONS CURRENTLY IN THAT
CATEGORY/SUBCATEGORY.

Once you have a lot of questions stacked up in the "Question Database",
the list will start to paginate and get lengthy.  To help you organize
your Questions, you can click on the linked column headers (QID,
Category, Question, Last Updated, and Hits) to sort the list based on
your choice.  The list will remain sorted this way until you select a
new sort method.  You can set the default sort method by opening the
"knowledgebase-control.php" file and editing the $sData['orderby']
variable.

b) Uploading Mode

To enter the File Upload Manager, click the "Upload Accessory Files"
button.  If you haven't yet created and/or CHMODed the files directory
to 777, you'll get an error message here.  If no error, you're ready to
upload.

Uploading a file is as simple as selecting a file off your hard drive
and hitting the "Upload" button.  Uploaded files will appear in a list
below the upload form.  From this list you'll be able to view (click on
the filename) and delete each file as you desire.  Keep in mind the
"File Size Limit" and "File Types Allowed" as you upload a few files.

Once you've uploaded a few items, hit the "Return to Editing Mode"
button, and we'll see one more feature that has been enabled.  Select a
question to edit, or add a new one to bring up the Question/Answer form.

Beside the Quick-add buttons in between the Answer and Keywords fields
is now a dropdown menu of all the files you've uploaded.  Select a file,
then click one of the two buttons to automatically insert the
appropriate image or link HTML pointing to that file.  It's that easy!


III. Using the User GUI

6. Once you've added a question or two, point your browser to the User
GUI at "knowledgebase.php", or whatever you named it.  Using the User
GUI is meant to be as simple as possible for first time users coming to
your site.  At the same time, advanced features are available for those
who know exactly what they're looking for.

The GUI consists of two parts, the Controls and the Display.  The
Controls are, by default, contained in a box at the top of the script.
Here you can find three different methods to narrow a search.  The
Display is everything below the Controls.

Looking at the Controls, the first form is the actual "Search" tool. 
Simply fill in some terms in the Search text field and away you go.

Next, for those who know what answer they're looking for and want to
revisit it for review or to check for updates, there is a smaller form
beneath the search field.  Just type in the ID of the question you were
looking at to go to it right away.

Notice that the way these forms work is by GET, and not by POST. This
means that the variables passed when you use either form are visible in
the address bar.  If you want to bookmark a search or a question ID, all
you have to do is copy the URI from the address bar and use it as your
link!  For example, on another page with "cars" as its topic, you could
have a link to your answer on "cars" (which has qid of 0) like so:

<a href="http://www.yourdomain.com/knowledgebase.php?qid=0">Cars</a>

You could also put this code in Knowledgebase Answers to direct users to
other answers which could solve their problem!

On the other side of the Controls is a filtering form.  Users can select
the categories and subcategories they wish to display, excluding
questions which aren't related to their query.  The results of this form
are held in a cookie until the "Clear" link is selected.  Thus a search
for "cars" when your User has excluded the "cars" subcategory might
bring up zero results.  Filtering provides an excellent way to narrow a
search within a specific topic.

Finally, after a user performs a search (or on every page, if you set it
as such in the okb_head.php file) a form will be displayed which allows
users to send you questions they feel were not answered by your
knowledgebase.  This is a good source of new questions and will help you
add to your list of questions faster than just waiting for feedback.


IV. Customization

7. "knowledgebase.php" is really just a simple setup for the User GUI.
Let's see how we can embed our knowledgebase into an existing website.

Open the "knowledgebase.php" file.

The Orca Knowledgebase requires the following setup:

a) The files "okb_lang_en.php" and "okb_head.php" included at the very
top of the page before any whitespace or HTML code.  The order is
important. Always include the language file before the head file.

b) The "okb_style.css" file included as a stylesheet using a <link> tag.

c) The "okb_body.php" file included wherever page content normally goes
on your website.

Other than that, the rest of the HTML/PHP is all up to you!  The
knowledgebase is almost 100% styleable using the CSS in the
okb_style.css file.  A bit of editing and you can make it look like you
built your site around the knowledgebase, instead of the other way
around!


************************************************************************
* Please send all questions/comments/bugs to orcakbase@greywyvern.com  *
*                      -------------------------                       *
* Thanks for using my scripts!  I hope you enjoy them as much as I do  *
************************************************************************