path: root/docs/users_guide_src/introduction.tex

\section{Introduction}
\label{intro}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Who should read this Guide?}
\label{intro.whoShouldRead}

This Users' Guide provides a technical overview and reference for the
Cheetah template system.  Knowledge of Python and object-oriented programming
is assumed.  The emphasis in this Guide is on features useful in a wide variety
of situations.  Information on less common situations and troubleshooting tips
are gradually being moved to the Cheetah FAQ.  There is also a Cheetah
Developer's Guide for those who want to know what goes on under the hood.

%% A gentler introduction for template maintainers who don't know
%% Python will be written later.

This Guide also contains examples of integrating Cheetah with Webware for
Python.  You will have to learn Webware from its own documentation in order to
build a Webware + Cheetah site.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{What is Cheetah?}
\label{intro.whatIs}

Cheetah is a Python-powered template engine and code generator.  It may be used
as a standalone utility or combined with other tools.  Cheetah has
many potential uses, but web developers looking for a viable alternative to ASP,
JSP, PHP and PSP are expected to be its principle user group.

Cheetah:
\begin{itemize}        
\item generates HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any
     other text-based format.  It has also been used to produce Python, Java
     and PHP source code.
     
\item cleanly separates content, graphic design, and program code.  This leads
     to highly modular, flexible, and reusable site architectures; faster
     development time; and HTML and program code that is easier to understand
     and maintain. It is particularly well suited for team efforts.
     
\item blends the power and flexibility of Python with a simple template language
     that non-programmers can understand.
     
\item gives template writers full access in their templates to any Python data
     structure, module, function, object, or method.
     
\item makes code reuse easy by providing an object-oriented interface to
     templates that is accessible from Python code or other Cheetah templates.
     One template can subclass another and selectively reimplement sections of
     it.  A compiled template {\em is} a Python class, so it can subclass a
     pure Python class and vice-versa.
     
\item provides a simple yet powerful caching mechanism 

%% that can dramatically improve the performance of a dynamic website.
\end{itemize}   

Cheetah integrates tightly with {\bf Webware for Python}
(\url{http://webware.sourceforge.net/}): a Python-powered application server and
persistent servlet framework. Webware provides automatic session, cookie, and
user management and can be used with almost any operating-system, web server, or
database. Through Python, it works with XML, SOAP, XML-RPC, CORBA, COM, DCOM,
LDAP, IMAP, POP3, FTP, SSL, etc.. Python supports structured exception handling,
threading, object serialization, unicode, string internationalization, advanced
cryptography and more. It can also be extended with code and libraries written
in C, C++, Java and other languages.

Like Python, Cheetah and Webware are Open Source software and are supported by
active user communities.  Together, they are a powerful and elegant framework
for building dynamic web sites. 

Like its namesake, Cheetah is fast, flexible and powerful.

% @@MO: Repeat picture of cheetah.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{What is the philosophy behind Cheetah?}
\label{intro.philosophy}

Cheetah's design was guided by these principles:
\begin{itemize}
\item Python for the back end, Cheetah for the front end.  Cheetah was
     designed to complement Python, not replace it.
     
\item Cheetah's core syntax should be easy for non-programmers to learn.
          
\item Cheetah should make code reuse easy by providing an object-oriented
     interface to templates that is accessible from Python code or other
     Cheetah templates.
     
\item Python objects, functions, and other data structures should be fully
     accessible in Cheetah.
       
\item Cheetah should provide flow control and error handling.  Logic
     that belongs in the front end shouldn't be relegated to the 
     back end simply because it's complex.

\item It should be easy to {\bf separate} content, graphic design, and program
     code, but also easy to {\bf integrate} them.

     A clean separation makes it easier for a team of content writers,
     HTML/graphic designers, and programmers to work together without stepping
     on each other's toes and polluting each other's work.  The HTML framework
     and the content it contains are two separate things, and analytical
     calculations (program code) is a third thing.  Each team member should be
     able to concentrate on their specialty and to implement their changes
     without having to go through one of the others (i.e., the dreaded
     ``webmaster bottleneck'').
     
     While it should be easy to develop content, graphics and program
     code separately, it should be easy to integrate them together into a 
     website.  In particular, it should be easy:

     \begin{itemize}
     \item for {\bf programmers} to create reusable components and functions
          that are accessible and understandable to designers.
     \item for {\bf designers} to mark out placeholders for content and 
          dynamic components in their templates.
     \item for {\bf designers} to soft-code aspects of their design that are
          either repeated in several places or are subject to change.
     \item for {\bf designers} to reuse and extend existing templates and thus
          minimize duplication of effort and code.
     \item and, of course, for {\bf content writers} to use the templates that
          designers have created.
     \end{itemize}

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Why Cheetah doesn't use HTML-style tags}
\label{intro.htmlStyleTags}

Cheetah does not use HTML/XML-style tags like some other template languages for
the following reasons:
 Cheetah is not limited to HTML,
 HTML-style tags are hard to distinguish from real HTML tags,
 HTML-style tags are not visible in rendered HTML when something goes wrong,
 HTML-style tags often lead to invalid HTML (e.g., 
\code{<img src="<template-directive>">}),
Cheetah tags are less verbose and easier to understand than HTML-style tags, 
and HTML-style tags aren't compatible with most WYSIWYG editors

Besides being much more compact, Cheetah also has some advantages over
languages that put information inside the HTML tags, such as Zope Page
Templates or PHP:
 HTML or XML-bound languages do not work well with other languages,
 While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors,
     they also give up a significant advantage of those editors -- concrete
     editing of the document.  When logic is hidden away in (largely
     inaccessible) tags it is hard to understand a page simply by viewing it,
     and it is hard to confirm or modify that logic.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Give me an example!}
\label{intro.example}

Here's a very simple example that illustrates some of Cheetah's basic syntax:

\begin{verbatim}

<HTML>
<HEAD><TITLE>$title</TITLE></HEAD>
<BODY>

<TABLE>
#for $client in $clients
<TR>
<TD>$client.surname, $client.firstname</TD>
<TD><A HREF="mailto:$client.email">$client.email</A></TD>
</TR>
#end for
</TABLE>

</BODY>
</HTML>
\end{verbatim}

Compare this with PSP:

\begin{verbatim}
<HTML>
<HEAD><TITLE><%=title%></TITLE></HEAD>
<BODY>

<TABLE>
<% for client in clients: %>
<TR>
<TD><%=client['surname']%>, <%=client['firstname']%></TD>
<TD><A HREF="mailto:<%=client['email']%>"><%=client['email']%></A></TD>
</TR>
<%end%>
</TABLE>

</BODY>
</HTML>
\end{verbatim}

Section \ref{gettingStarted.tutorial} has a more typical example that shows
how to get the plug-in values {\em into} Cheetah, and section
\ref{howWorks.cheetah-compile} explains how to turn your template definition
into an object-oriented Python module.

%% @@TR: I'm going to extend this and briefly introduce: 
%% - Template objects vs. .tmpl files.
%% - how to get data into it 
%% @@MO: If you do this, reconcile this example and the one in gettingStarted.
%%   Keep two examples or collapse into one?


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Give me an example of a Webware servlet!}
\label{intro.example.servlet}

This example uses an HTML form to ask the user's name, then invokes itself
again to display a {\em personalized} friendly greeting.  

\begin{verbatim}
<HTML><HEAD><TITLE>My Template-Servlet</TITLE></HEAD><BODY>   
#set $name = $request.field('name', None)
#if $name  
Hello $name
#else
<FORM ACTION="" METHOD="GET">
Name: <INPUT TYPE="text" NAME="name"><BR>
<INPUT TYPE="submit">
</FORM>
#end if
</BODY></HTML>
\end{verbatim}

To try it out for yourself on a Webware system:
\begin{enumerate}
\item copy the template definition to a file {\bf test.tmpl} in your
    Webware servlet directory.
\item Run ``\code{cheetah compile test.tmpl}''.  This produces
    {\bf test.py} (a .py template module) in the same directory.
\item In your web browser, go to {\bf test.py}, using whatever site and
    directory is appropriate.  Depending on your Webware configuration, you may
    also be able to go to {\bf test}.
\end{enumerate}

At the first request, field `name' will be blank (false) so the ``\#else''
portion will execute and present a form.  You type your name and press submit.
The form invokes the same page.  Now `name' is true so the ``\#if'' portion
executes, which displays the greeting.  The ``\#set'' directive creates a
local variable that lasts while the template is being filled.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{How mature is Cheetah?}
\label{intro.mature}

Cheetah is stable, production quality, post-beta code. Cheetah's syntax,
semantics and performance have been generally stable since a performance
overhaul in mid 2001. Most of the changes since October 2001 have
been in response to specific requests by production sites, things they need that
we hadn't considered.

As of summer 2003, we are putting in the final touches before the 1.0 release.

The {\bf TODO} and {\bf BUGS} files in the Cheetah distribution show what we're
working on now or planning to work on.  There's also a {\bf ToDo} page on the
wiki (see below), which is updated less often.  The {\bf WishList} page on the
wiki shows requested features we're considering but haven't commited to.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Where can I get news?}
\label{intro.news}

Cheetah releases and other stuff can be obtained from the the Cheetah 
{\bf Web site}:
\url{http://CheetahTemplate.sourceforge.net}

Cheetah discussions take place on the {\bf mailing list}
\email{cheetahtemplate-discuss@lists.sourceforge.net}.  This is where to hear
the latest news first.

The Cheetah {\bf wiki} is becoming an increasingly popular place to list
examples of Cheetah in use, provide cookbook tips for solving various problems,
and brainstorm ideas for future versions of Cheetah.
\url{http://www.cheetahtemplate.org/wiki}
(The wiki is actually hosted at
\url{http://cheetah.colorstudy.net/twiki/bin/view/Cheetah/WebHome}, but the 
other URL is easier to remember.)
For those unfamiliar with a wiki, it's a type of Web site that readers can edit
themselves to make additions or corrections to.  Try it.  Examples and tips 
from the wiki will also be considered for inclusion in future versions of this
Users' Guide.

If you encounter difficulties, or are unsure about how to do something,
please post a detailed message to the list.  

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{How can I contribute?}
\label{intro.contribute}

Cheetah is the work of many volunteers.  If you use Cheetah please share your
experiences, tricks, customizations, and frustrations.

\subsubsection{Bug reports and patches}

If you think there is a bug in Cheetah, send a message to the e-mail list
with the following information:

\begin{enumerate}
\item a description of what you were trying to do and what happened
\item all tracebacks and error output
\item your version of Cheetah
\item your version of Python
\item your operating system
\item whether you have changed anything in the Cheetah installation
\end{enumerate}

\subsubsection{Example sites and tutorials}
If you're developing a website with Cheetah, please put a link on the wiki on
the {\bf WhoIsUsingCheetah} page, and mention it on the list.  Also, if you
discover new and interesting ways to use Cheetah, please put a quick tutorial
(HOWTO) about your technique on the {\bf CheetahRecipies} page on the wiki.

\subsubsection{Template libraries and function libraries}
We hope to build up a framework of Template libraries (see section
\ref{libraries.templates}) to distribute with Cheetah and would appreciate any
contributions.

\subsubsection{Test cases}
Cheetah is packaged with a regression testing suite that is run with each
new release to ensure that everything is working as expected and that recent
changes haven't broken anything.  The test cases are in the Cheetah.Tests
module.  If you find a reproduceable bug please consider writing a test case
that will pass only when the bug is fixed.  Send any new test cases to the email
list with the subject-line ``new test case for Cheetah.''

\subsubsection{Publicity}
Help spread the word ... recommend it to others, write articles about it, etc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Acknowledgements}
\label{intro.acknowledgments}
    
Cheetah is one of several templating frameworks that grew out of a `templates'
thread on the Webware For Python email list.  Tavis Rudd, Mike Orr, Chuck
Esterbrook and Ian Bicking are the core developers.

We'd like to thank the following people for contributing valuable advice, code
and encouragement: Geoff Talvola, Jeff Johnson, Graham Dumpleton, Clark C.
Evans, Craig Kattner, Franz Geiger, Geir Magnusson, Tom Schwaller, Rober Kuzelj,
Jay Love, Terrel Shumway, Sasa Zivkov, Arkaitz Bitorika, Jeremiah Bellomy,
Baruch Even, Paul Boddie, Stephan Diehl, Chui Tey, Michael Halle, Edmund Lian
and Aaron Held.
    
The Velocity, WebMacro and Smarty projects provided inspiration and design
ideas.  Cheetah has benefitted from the creativity and energy of their
developers. Thank you.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{License}
\label{intro.license}

\paragraph*{The gist}
Cheetah is open source, but products developed with Cheetah or derived
from Cheetah may be open source or closed source.

{\bf Cheetah.Utils.optik} is based on a third-party package Optik by Gregory
P Ward.  Optik's license is in appendix \ref{optikLicense}.


\paragraph*{Legal terms}
Copyright \copyright 2001, The Cheetah Development Team: Tavis Rudd, Mike Orr,
Ian Bicking, Chuck Esterbrook.

Permission to use, copy, modify, and distribute this software for any purpose
and without fee is hereby granted, provided that the above copyright notice
appear in all copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the names of the authors not
be used in advertising or publicity pertaining to distribution of the software
without specific, written prior permission.

THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

These terms do not apply to the {\bf Cheetah.Utils.optik} package.  Optik's
license is in appendix \ref{optikLicense}.

% Local Variables:
% TeX-master: "users_guide"
% End: