1 files changed, 95 insertions, 0 deletions
diff --git a/docs/users_guide_2_src/15_otherHtml.txt b/docs/users_guide_2_src/15_otherHtml.txt
new file mode 100755
index 0000000..89fd58a
--- /dev/null
+++ b/docs/users_guide_2_src/15_otherHtml.txt
@@ -0,0 +1,95 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{non-Webware HTML output}
+\label{otherHTML}
+
+Cheetah can be used with all types of HTML output, not just with Webware.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Static HTML Pages}
+\label{otherHTML.static}
+
+Some sites like Linux Gazette (\url{http://www.linuxgazette.com/}) require
+completely static pages because they are mirrored on servers running completely
+different software from the main site.  Even dynamic sites may have one or
+two pages that are static for whatever reason, and the site administrator may
+wish to generate those pages from Cheetah templates.
+
+There's nothing special here.  Just create your templates as usual.  Then
+compile and fill them whenever the template definition changes, and fill them
+again whenever the placeholder values change.  You may need an extra step to
+copy the .html files to their final location.  A Makefile (chapter
+\ref{tips.Makefile}) can help encapsulate these steps.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{CGI scripts}
+\label{otherHTML}
+
+Unlike Webware servlets, which don't have to worry about the HTTP headers,
+CGI scripts must emit their own headers.  To make a template CGI aware, add
+this at the top:
+\begin{verbatim}
+#extends Cheetah.Tools.CGITemplate
+#implements respond
+$cgiHeaders#slurp
+\end{verbatim}
+
+Or if your template is inheriting from a Python class:
+\begin{verbatim}
+#extends MyPythonClass
+#implements respond
+$cgiHeaders#slurp
+\end{verbatim}
+
+A sample Python class:
+\begin{verbatim}
+from Cheetah.Tools import CGITemplate
+class MyPythonClass(CGITemplate):
+    def cgiHeadersHook(self):
+        return "Content-Type: text/html; charset=koi8-r\n\n"
+\end{verbatim}
+
+
+Compile the template as usual, put the .py template module in your
+cgi-bin directory and give it execute permission.  \code{.cgiHeaders()} is
+a ``smart'' method that outputs the headers if the module is called as a
+CGI script, or outputs nothing if not.  Being ``called as a CGI script''
+means the environmental variable \code{REQUEST\_METHOD} exists and
+\code{self.isControlledByWebKit} is false.  If you don't agree with that
+definition, override \code{.isCgi()} and provide your own.  
+
+The default header is a simple \verb+Content-type: text/html\n\n+, which works
+with all CGI scripts.  If you want to customize the headers (e.g., to 
+specify the character set), override \code{.cgiHeadersHook()} and return
+a string containing all the headers.  Don't forget to include the extra
+newline at the end of the string: the HTTP protocol requires this empty
+line to mark the end of the headers.
+
+To read GET/POST variables from form input, use the \code{.webInput()} method
+(section \ref{webware.webInput}), or extract them yourself using Python's
+\code{cgi} module or your own function.  Although \code{.webInput()} was
+originally written for Webware servlets, it now handles CGI scripts too.  There
+are a couple behavioral differences between CGI scripts and Webware servlets
+regarding input variables:
+
+\begin{enumerate}
+\item CGI scripts, using Python's \code{cgi} module, believe
+    \code{REQUEST\_METHOD} and recognize {\em either} GET variables {\em or}
+    POST variables, not both.  Webware servlets, doing additional processing,
+    ignore \code{REQUEST\_METHOD} and recognize both, like PHP does.
+\item Webware servlets can ask for cookies or session variables instead of
+    GET/POST variables, by passing the argument \code{src='c'} or
+    \code{src='s'}.  CGI scripts get a \code{RuntimeError} if they try to do
+    this.  
+\end{enumerate}
+
+If you keep your .tmpl files in the same directory as your CGI scripts, make
+sure they don't have execute permission.  Apache at least refuses to serve
+files in a \code{ScriptAlias} directory that don't have execute permission.
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+%# vim: sw=4 ts=4 expandtab