*********************************
* What, How, Where, Who, When   *
*********************************


As the header says, this tool is a FAQ Manager. As usual implemented as Perl/CGI-BIN...

There is almost nothing to explain here. You probably have seen many FAQs on the Internet, Some of them 
generated by hand, other automatically converted from different text formats. This tool allows you to start a 
fresh FAQ from scratch and you will be able to add/modify/move/delete the question<->answer pairs in one 
touch. 

Author: Bekman Stas <sbekman@hotmail.com>

Last Revision Date: 01/20/98

Current version: 1.01 

Location: Currently at: http://www.eprotect.com/stas/TULARC/works/faq_manager/

*****************
* How it works  *
***************** 

     You create a template HTML file for your FAQ (Just pick the template in the package and modify it). 
     Open this template file in your favorite browser. 
     Follow the link at the bottom of the page (you will have to point it to the faq_manager.pl URL (place 
     where your copy of faq_manager.pl resides on the server). And you will get a form as you have seen in the 
     snapshot. 
     From now on script will work on the temperary copy of your file so if you break something and someone 
     uses the FAQ file you edit , she will never notice a thing.
     Now you can add a new question/answer, modify them , move their locations (e.g you want a last question 
     to become first one), delete them. Any moment you can press a preview button to see how you modified 
     FAQ will look in your browser when saved. If you do a mistake you can always go back by performing 
     'Undo' (Press 'Back' button doesn't always work ) and then redo by pressing 'Redo'.
     Only when satisfied you should press the 'Save' Button to overwrite the original file!

Since there are many FAQ alike actions to perform (link manager, menu managers and soon) I'm working now 
to generalize this tool so it will solve any kind of these tasks. So stay tuned...


*****************
* What you need *
*****************

    
* Perl5
* CGI.pm (you can get it from www.perl.com/CPAN)
* JavaScript enabled browser (yes, it uses js a bit)



*****************
* Installation: *
*****************


# Note : To help you to config this file I'll do a real configuration
# so consider the following layout:
# cgi-bins reside on /home/http/cgi-bin/
# and we call them as http://your.server.com/cgi-bin/
#
# documentation files reside on /home/http/docs/
# and we access them by http://your.server.com/

* Unpack the package zip or tar.gz into some space on your cgi server
 
* cd to faq_manager so now you are in /home/http/cgi-bin/faq_manager

* move the images directory somewhere in your documentation space 
/home/http/docs/ (you will need to set this info later)

* Mofidy the ./setup/config.pl
See the explanations in this file

* check that the faq_manager.pl script is executable 
and the $cgi_obj_dir as chose in config.pl is writable by server
try to minimize the access to them if possible
so if you server can write files with group access with
chmod ug+w data (I assume 'data' is a directory $cgi_obj_dir)
it's a better thing to do

* Take the template faq_template.html and modify it to suite your needs
3 notes:
1. You can modify everything before:
<!--end of top--> line (don't remove it !!!)

2. You can modify almost everything under 
<!--start of bottom--> line (don't remove it !!!)

3. As I said almost in (2) you have to modify a link to 'FAQ Manager' 
to point it to the proper URL to call faq_manager.pl in our case it will be
<A HREF="http://www.nowhere.com/cgi-bin/faq_manager.pl">FAQ Manager </A>
All the rest will be modifyable

*************************************
* How to work with a tool: Details  *
*************************************

All this helps you can get online by pressing a question mark near the action button
       
This is Manager::Add Help Section

       To add a new item fill an input fields and press Add button 

       By default the new item is appended to the end, 
       if you want to place in into a different place, select one of the 
       radio buttons in the 'To' column and the item will be placed into
       specified location!

       For example if you have already 10 items, and you want to place
       a new one between 5 and 6 items, check the 'to' button at the row number 
       6, 6th item will be moved one down and a new item will take its place

       Hint: To reset the checked buttons and whatever text in the input widow(s) -- 
       Press 'Reset' Button!

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
This is Manager::Move Help Section

       To move an item from location n to destination k, select the original
       item in the 'Select' column, then select the button in 'Move To' Column
       Press Move Button, and the item will be moved

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>


This is Manager::Update  Help Section

       To update the existant item. Select it from 'Select' column. The items content will
       show up in the unput windows. Now Do Update. And Press 'Update' Button to submit
       changes.

       You may perform 'Update' and 'Move' in one step if after Modifying the item you will
       select a checkbox in the 'Move To' column. If you do that the item will be modified 
       and moved to a new location. If you leave it untouched the item will stay at the same 
       place

       Hint: To reset the checked buttons and whatever text in the input widow(s) -- 
       Press 'Reset' Button!

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
       
This is Manager::Delete  Help Section

       To delete an existant item -- Select it from 'Select' Column. Then press 'Delete' 
       button -- The entry is gone!

       If you delete by mistake some item you didn\'t mean to, you can always 'Undo' the 
       changes by pressing 'Undo' Button!

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
       
This is Manager::View  Help Section
       
       To preview the changes you did, press 'Preview' button and a new window will pop up,
       it will contain the changes that has been performed. 

       To close that window press on the 'Close window' button at the bottom of that script.
       
       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
       
This is Manager::Undo  Help Section

       If you did some mistake and submitted one of the Delete/Add/Update/Move actions,
       Press 'Undo' Button and your latest changes will be restored. You may continue to 
       Undo your changes untill you reach the original document as you called this script 
       for the time, Alas Here the program will stop Undoing :-0

       If you change your mind you can always 'Redo' Changes (return to your last changes) 
       by pressing the 'Redo' Button.

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
      
This is Manager::Redo  Help Section

       If you decided to 'Undo' the changes and afterwards you have changed your mind, and 
       you still want your changes back -- Press 'Redo' Button.

       As with 'Undo' you can perform a N 'Redo's but it will be possible if you did N 
       'Undo's before in sequence. Ofcourse you will be unable to 'Redo' Something you never
       Did :-)

       You can perform 'Undo' again after 'Redo' .... and soon.

       <FONT COLOR="red"> Remember to press Save when you finish all the changes !!!</FONT>
 
       
This is Manager::Save  Help Section

       To save the changes into an original file press 'Save' button.
       Untill then, all the changes will be stored internally and no modification to the 
       original file will be performed. Note that includes the 'Preview' Action -- When you
       'Preview' you see a temperary copy of the "would be" file and not the original!!! 




*******************************
* More technical Information  *
*******************************

How do things realy work.

When you access some of the empty fresh FAQ html pages or a working one (under use) and follow 
the link at the bottom of the page, this script is getting called. It retrieves the HTTP_REFERER
to learn what html page it should work with. Then by using $base_dir and $base_url it translates 
the URL of the page to the real path to it on the server. 

Once page is read in, it's getting parsed.
First we split the page into 3 parts top, body, and bottom by using $top_sep $bottom_sep separators
We remember the top and bottom since we will need them back when we will write back the modified 
document. 

Next step is to parse the body and extract all the questions and answers into @questions and @answers 
lists. We do it with help of $q_begin_sep $q_end_sep $a_begin_sep $a_end_sep separators. 

Then we create a unique string to name the temp file for the cgi object

Cgi object is created by CGI.pm , and saved into uniq file in $cgi_obj_dir with an extension '.0' so 
we know that this is the original version. We save inside session_id the same as a filename, top, 
bottom, and a numbered list of questions and answers.

Now we create a form with list of already existant questions and to columns 'Select' and 'Move To'
We pass a hidden session id variable

With help of javascript we fill the question/answer input form with preset values of the selected 
question from 'Select' column . Now we can modify the contents. Or if we want to add a new pair 
of question/answer we fill the input form. (Read more about other options in Usage section: 
[How to work with a tool: Details]

How script knows what to move, delete, add or modify? By passing the 'Select' and 'Move To' (if move)
values of radio buttons

The we simply retrieve the previous cgi object ( we know which one since we get it from the form submit)
read in the list of questions and answers apply splice() on the list and we get a new updated list,
which saved back into the cgi object , not the original but the new one with the extension '.1'
then as before we return the form with updated contents.

Every time we increase the index of the object .2 .3 ... etc

We need that feature so we will be able to do 'Undo' and 'Redo' actions by reading the previous or the 
following CGI object.

The directory of objects $cgi_obj_dir is getting cleaned when the script called for a first time per faq
it check fo files older than 2 days and delete them. ofcourse you can change that value

It's important to note that faq_manager never overwrites the original file till you press 'Save', thus 
allowing you to apply a lot of changes to the faq while users can keep on using the previous version of 
the document

That's all. If you want to learn even more, read the code :-) It's pretty commented.

