What is in this directory
=========================

This directory and the directory internal/c++/include/internal/hello/include 
contain the application "hello.cgi", which is a simple demo cgi application.

The general purpose of the program is that it reads input from a web server and 
from a configuration file ("hello.cgi.ini"), and creates a web page using the 
file "html/template.html" and dynamically generated html.


Program flow
============

The main application class is CHelloApp (in chelloapp.*pp) which is derived from 
CCgiApplication. This class has three main parts Init(), Run(), and Exit(), 
called in that order.  Exit() does not do anything of particular interest in 
hello.cgi.

Init() loads the CNcbiRegistry class and makes it a member of CHelloApp.  
CNcbiRegistry contains methods for accessing the .ini configuration file.  
Init also loads a copy of CHelloResource via HelloApp::LoadResource() and puts 
the commands to be executed in it.  The main purpose of the CHelloResource class
(found in hellores.*pp) is to hold commands and other classes related to a 
particular database.

Run() is where the html generation takes place.  First, Run() creates a copy 
of CCgiContext, which in turn contains the CCgiRequest and CCgiResponse classes 
used to communicate to the web server. Then Run() processes the CGI request via 
NcbiResource::HandleRequest(), which in turn goes through the list of commands 
attempting to match any of the cgi request name, value pairs to 
CNcbiCommand::GetEntry(), CNcbiCommand::GetName().  If it finds a match, it 
calls Execute() on the command.

CNcbiCommand::Execute() is where the template html file is read in and where 
<@VIEW@> tags in the html are replace with html generated by 
CNcbiCommand::CreateView().  Execute() then prints the page to the 
CCgiResponse class, sending the html to the web server.


Files
=====

helloapp.*pp: contains CHelloApp
hellocmd.*pp: contains the CNcbiCommand commands that create the web pages
hellores.*pp: contains CHelloResource, which holds the list of commands
html/*html: the html templates
Makefile.in: the recursive makefile that points to...
Makefile.hello.app: makes the program
hello.cgi.ini: the configuration file


How to modify the program
=========================

- Create your own command classes derived from CNcbiCommand.  The important 
member functions to modify are:
  - GetName(): the value in the cgi request.
  - GetEntry(): the name in the cgi request.
  - Clone(): make a new copy of the command.
  - CreateView(): creates the html for the page.
- Modify CHelloResource::DefaultCommand() to point at your default command.
- Add your commands in CHelloApp::LoadResource().

- if you want to use the html template without the sidebar, edit hello.cgi.ini 
so that htmlBaseFile points to html/nosidebar.html.


Running the program
===================

To run the program after making it, copy "hello.cgi", "hello.cgi.ini", and 
"html/*.html" over to a directory where you can run cgi programs. Make sure 
that you "chmod o+x hello.cgi" on the copy of "hello.cgi" in the cgi directory 
so that the web server can run it. 



Feedback to: lewisg@ncbi.nlm.nih.gov