diff options
Diffstat (limited to 'docs/users_guide_src/introduction.tex')
| -rwxr-xr-x | docs/users_guide_src/introduction.tex | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/docs/users_guide_src/introduction.tex b/docs/users_guide_src/introduction.tex new file mode 100755 index 0000000..be34fc6 --- /dev/null +++ b/docs/users_guide_src/introduction.tex @@ -0,0 +1,392 @@ +\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: |