home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / cginb130.zip / readme < prev   
Text File  |  1997-11-14  |  12KB  |  360 lines
  1. 14 November 1997
  2.  
  3.                               CGI Notebook v1.30
  4.  
  5.    It is assumed that you are the Webmaster administrating the server and
  6.    are already familiar with the HTML language tags and their uses. Also,
  7.    that you understand the operation of the OS/2 Warp environment and can
  8.    perform the described tasks in the documentation.
  9.  
  10.  
  11. This software is provided on an "as-is" basis.  I offer no warranty on this
  12. software whatsoever, and you use it at your own risk.
  13.  
  14. This software is freeware so you may freely use and distribute it.
  15.  
  16.  
  17. 1. What is the CGI notebook?
  18.  
  19.     The CGI Notebook is a CGI (Common Gate Interface) program  which allows
  20. you to ask users of your  Web Pages  for some  information  and records the 
  21. information to desired file(s). In addition, visitors of your site can view
  22. the information if you allow it.
  23.     I wrote the program to help Webmasters which are not familiar with  CGI 
  24. programming to record forms (<FORM> tag) data in a file. The Notebook
  25. will help to make Guest Book, Registration Form and so on ...
  26.  
  27. 2. System requirements.
  28.  
  29.     OS/2 Warp 3 or later and Web Server software (e.g. Internet Connection 
  30. Server) installed on your computer. 
  31.  
  32. 3. Installation.
  33.  
  34.     Archive cginb130.zip contains:
  35.         nb.exe        -  executable file
  36.         nb.cfg        -  notebook configuration file
  37.         example.ndf   -  example of notebook definition file
  38.         example.rsp   -  example of response file
  39.         example.snb   -  example of template file for viewing notebook data
  40.         example.usr   -  example of user configuration file
  41.         nb.htm        -  HTML example of using of the Notebook
  42.         readme        -  this file
  43.  
  44.      
  45.     It is easy to install the Notebook. 
  46.     Make directory /notebook inside the /cgi-bin directory of your Web server, 
  47. then put files nb.exe, nb.cfg into /cgi-bin and example.ndf, example.rsp, 
  48. example.snb, example.usr into /cgi-bin/notebook directory.
  49.  
  50.     HTML file nb.htm contains an example of use the Notebook and you may 
  51. put the file whereever you want in your Web pages directories.
  52.  
  53. 4. Using the Notebook.
  54.  
  55.     4.1. Simple use.
  56.  
  57.     Type URL http://yourhost/path_to_nb.htm/nb.htm in your browser. 
  58. You will see an example of using the Notebook.
  59.  
  60.     4.2. Normal use.
  61.     4.2.1. Setting up notebooks.
  62.  
  63.     First you have to describe a notebook in nb.cfg file.
  64. The file contains a number of lines which describe different notebooks.
  65.  
  66. Format of nb.cfg file is:
  67.  
  68. identificator1=notebookDefinitionFile1
  69. identificator2=notebookDefinitionFile2
  70. ...
  71.  
  72. where
  73.     identificatorI - a key string to select the notebook
  74.     notebookDefinitionFileI - file which describes the notebook
  75.  
  76. Example of nb.cfg:
  77.  
  78. main=notebook\example.ndf
  79.  
  80.     Above line says that notebook "main" uses file "notebook\example.ndf" as
  81. a definition file.
  82.  
  83.     Examle of a definition file is example.ndf.
  84. The file is well commented and you should view the file.
  85. There are four keyword which are defined in the file:
  86.  
  87.     Data         - file which data are stored in after submitting
  88.     ResponceFile - file which will be sent to remote after submitting
  89.     ShowFile     - file which is used as a template for viewing
  90.                    notebook data
  91.     UserConfig   - configuration file for the notebook
  92.  
  93.     ResponceFile is a plain HTML document and ShowFile is almost a plain HTML 
  94. document.
  95.  
  96.     UserConfig is intended for setting some parameters, templates and
  97. access filters for the notebook.
  98.     Examle of the file is example.usr.
  99.     The parameters in the UserConfig are:
  100.     
  101.         Title - string, title of the notebook
  102.         WrapLongLines - integer value in range from 0 to 256,
  103.                         if a line in the notebook data will be longer than
  104.                         the value then the line will be wrapped, 0 means 
  105.                         no wrapping
  106.         LinkUrl       - Yes/No, if url will be found in the notebook data
  107.                         then the url will be replaced with
  108.                         <A HREF="url">url</A>
  109.  
  110.     The templates in the UserConfig are:
  111.         BeginShowEntryTemplate - template for showing all entries (records)
  112.                                  in the notebook
  113.                                  The template starts with
  114.  
  115.                                  BeginShowEntryTemplate=
  116.  
  117.                                  and ends with
  118.  
  119.                                  EndShowEntryTemplate
  120.  
  121.         BeginShowVariableTemplate - template for showing all or specific 
  122.                                  variables (fields)
  123.                                  Variable has the same name as a input element
  124.                                  in FORM tag. So for
  125.         <INPUT TYPE="text" NAME="First name" VALUE="" SIZE="25" MAXLENGTH="50">
  126.                                  variable name is "First name".
  127.                                  The template starts with
  128.  
  129.                                  BeginShowVariableTemplate=[variablename]
  130.  
  131.                                  and ends with
  132.  
  133.                                  EndShowEntryTemplate
  134.  
  135.                                  If the variablename is not specified
  136.                                  then the template is used for all 
  137.                                  variables which have not its own template.
  138.  
  139.     In a template you can use metasymbols:
  140.         $d - number of the message
  141.         $rn - remote name
  142.         $ra - remote adr
  143.         $t - time
  144.         $va - all variables should be appeared here (only for ShowEntryTemplate)
  145.         $vn - name of current variable in ShowVariableTemplate
  146.         $vv - value of current variable in ShowVariableTemplate
  147.     
  148.     The filter in the UserConfig is an access filter. You are able to 
  149. specify hosts which can access variables in the notebook.
  150.     The filter starts with
  151.  
  152. Access
  153.  
  154. and ends with
  155.  
  156. EndAccess
  157.  
  158.     Access lists for variables are between these lines.
  159. Format of access list is:
  160.  
  161. Variablename = host1,host2...
  162.  
  163. The variable will be accessed only from these hosts.
  164. If no filter specified for a variable then the variable can be accessed from any 
  165. hosts.
  166.  
  167.     4.2.2. Recording data in a notebook 
  168.  
  169.     After describing a notebook in nb.cfg, you have to insert to your Web page 
  170. the <FORM> tag:
  171.  
  172.    <FORM METHOD="POST" ACTION="/cgi-bin/nb">
  173.     <INPUT TYPE="hidden" NAME="notebookident" VALUE="main">
  174.  
  175.     <!-- Your input elements here -->
  176.  
  177.     <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
  178.    </FORM>
  179.     
  180.     Values are:
  181.  
  182.         notebookident - identificator of the notebook (see nb.cfg format)
  183.  
  184.     If you use Russian language then you have to add line:
  185.  
  186.     <INPUT TYPE="hidden" NAME="codepage" VALUE="ibm866">
  187.  
  188. in FORM tag.
  189.  
  190.     codepage - ibm866, win1251 or koi8r for translation 
  191.                beetwin cyrillic codepages. Set codepage which your
  192.                clients use. 
  193.  
  194.     If you use only English then don't insert codepage line in FORM tag
  195. becouse if codepage variable is defined  then the CGI notebook will go
  196. to cyrillic mode and use Russian messages instead of English.
  197.  
  198.     
  199.     Inside the form you may insert any input elements.
  200.  
  201.     Data are stored in the specified file ( Data keyword in definition file ) 
  202. in the next format:
  203. :START
  204. RemoteName= "remotehostname"
  205. RemoteAddress= "remotehostaddress"
  206. Time= "date&time"
  207. :Variable1
  208. valueofVariable1
  209. :Variable2
  210. valueofVariable2
  211. ...
  212. :END
  213.  
  214.  
  215.     4.2.3. Multiple notebooks support
  216.  
  217.     File 'nb.cfg' and 'notebookident' are needed for handle a number of 
  218. different notebooks.
  219.     For example, you need 2 different notebooks. First notebook is Guestbook,
  220. second is Notebook_for_Clients.
  221. You can do it.
  222. File nb.cfg should contains data like that:
  223.  
  224. Guestbook=notebook/guest
  225. Notebook_for_Clients=notebook/client
  226.  
  227.     The definition file notebook/guest will contain:
  228. Data = guests
  229. ResponceFile = guests.rsp
  230. ShowFile = guests.snb
  231. UserConfig = guests.usr
  232.  
  233.     The definition file notebook/client will contain:
  234. Data = clients
  235. ResponceFile = clients.rsp
  236. ShowFile = clients.snb
  237. UserConfig = clients.usr
  238.         
  239. Then you write in your guest page:
  240.  
  241.    <FORM METHOD="POST" ACTION="/cgi-bin/nb">
  242.     <INPUT TYPE="hidden" NAME="notebookident" VALUE="Guestbook">
  243.  
  244.     <!-- Your input elements here -->
  245.  
  246.     <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
  247.    </FORM>
  248.  
  249. and in clients page
  250.  
  251.    <FORM METHOD="POST" ACTION="/cgi-bin/nb">
  252.     <INPUT TYPE="hidden" NAME="notebookident" VALUE="Notebook_for_Clients">
  253.  
  254.     <!-- Your input elements here -->
  255.  
  256.     <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
  257.    </FORM>
  258.  
  259. So you have 2 different notebooks.
  260.  
  261. First notebook: 
  262. ident = Guestbook
  263. file to save data = notebook/guests
  264. file to send to remote = notebook/guests.rsp
  265. template to view the notebook = notebook/guests.snb
  266. notebook configuration file = notebook/guests.usr
  267.  
  268. Second notebook: 
  269. ident = Notebook_for_Clients
  270. file to save data = notebook/clients
  271. file to send to remote = notebook/clients.rsp
  272. template to view the notebook = notebook/clients.snb
  273. notebook configuration file = notebook/clients.usr
  274.  
  275.     4.2.4. Viewing data in notebook
  276.  
  277.     The CGI notebook allow to view notebook data with Web browser.
  278.  
  279.     To view notebook data you have to insert next FORM tag in your Web page:
  280.  
  281.    <FORM METHOD="POST" ACTION="/cgi-bin/nb">
  282.     <INPUT TYPE="hidden" NAME="notebookident" VALUE="view:main">
  283.     <INPUT TYPE="submit" VALUE="View the Notebook">
  284.    </FORM>
  285.  
  286.     So you have to prepend identificator of a notebook to be viewed with 'view:'.
  287. File example.snb is a template which is used to show notebook data as well as
  288. templates in example.usr
  289.  
  290. NOTE: 
  291. ----
  292. If you use Apache Web Server you have to replace
  293. ACTION="/cgi-bin/nb"
  294. with
  295. ACTION="/cgi-bin/nb.exe"
  296. in all forms
  297.  
  298. ENDNOTE
  299. -------
  300.  
  301. 5. CGI Notebook Revisions.
  302.  
  303. v1.00 - first release, non public, has a great security bug
  304. v1.01 - cyrillic codepage support added. Still non public. 
  305.         Security bug not fixed.
  306. v1.10 - security bug fixed. First version with nb.cfg.
  307. v1.20 - View notebook feature added. Reverse DNS lookup added.
  308. v1.21 - Added support for ICS and GoServer. Little changes in documentaion.
  309. v1.22 - No changes in executables. Corrections in nb.rsp, nb.snb and readme.
  310.         Apache server support: note in documentation.
  311. v1.23 - Little bug in view feature fixed. Added word wrap feature. 
  312.         Changes in documentation. Format of nb.cfg is changed.
  313. v1.24 - Changes in documentation related to PlanetWide Web Server.
  314.         New version 1.13 of the server works properly with CGI.
  315. v1.25 - All messages in cyrillic mode are translated to Russian
  316.         Little quirk when incorrect calling is fixed.
  317. v1.30 - Major release. A lot of features nave been added. Documentation
  318.         has been changed. New format of configuration files and new 
  319.         set of files which is included in the distribution zip.
  320.         New features are:
  321.         1. Human readable text configuration files.
  322.         2. URLs appear as underlined links while viewing.
  323.         3. Configurable templates to view all data and each field in the notebook.
  324.         4. Controlled access to each field stored in the notebook. You can enable 
  325.            access from one host and disable from all other.
  326.  
  327. 6. Acknowledgements.
  328.  
  329.     Special thanks to Ted Romer, who has helped me in improving the CGI 
  330. Notebook.
  331.  
  332. 7. Conclusion.
  333.  
  334.     If you have ANY problems with the Notebook that I can help you with, 
  335. send me E-mail to 
  336.  
  337. Vitali.Pelenyov@dpt.ustu.ru 
  338.  
  339. or leave your message in my notebook: 
  340.  
  341. http://194.226.228.11/eng/nb.htm
  342.  
  343. Latest version of the Notebook is available in my FTP archive
  344.  
  345. ftp://194.226.228.11/pub/os2/tcpip/cginb.zip
  346.  
  347. Mirror of the CGI notebook home page is:
  348.  
  349. http://www.watermaid.dyndns.com/~cosmos/nb/nb.htm
  350.  
  351. My site is up from 4 to 11 GMT.
  352.  
  353. If you use the Notebook, send me some mail and let me know. 
  354. I would love to hear from you.
  355.  
  356. Sorry for any typos and bad grammar. I will gladly accept any corrections to
  357. this short manual.
  358.  
  359. Vitali Pelenyov ( Vitali.Pelenyov@dpt.ustu.ru )
  360.