diff options
Diffstat (limited to 'www/users_guide/intro.rst')
| -rw-r--r-- | www/users_guide/intro.rst | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/www/users_guide/intro.rst b/www/users_guide/intro.rst new file mode 100644 index 0000000..b7525ea --- /dev/null +++ b/www/users_guide/intro.rst @@ -0,0 +1,313 @@ +Introduction +=============== + +Who should read this Guide? +--------------------------- + +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. + +What is Cheetah? +---------------- + +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: + + +- 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. + +- 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. + +- blends the power and flexibility of Python with a simple + template language that non-programmers can understand. + +- gives template writers full access in their templates to any + Python data structure, module, function, object, or method. + +- 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 **is** a Python + class, so it can subclass a pure Python class and vice-versa. + +- provides a simple yet powerful caching mechanism + +Like its namesake, Cheetah is fast, flexible and powerful. + + +What is the philosophy behind Cheetah? +-------------------------------------- +Cheetah's design was guided by these principles: + + +- Python for the back end, Cheetah for the front end. Cheetah was + designed to complement Python, not replace it. + +- Cheetah's core syntax should be easy for non-programmers to + learn. + +- Cheetah should make code reuse easy by providing an + object-oriented interface to templates that is accessible from + Python code or other Cheetah templates. + +- Python objects, functions, and other data structures should be + fully accessible in Cheetah. + +- 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. + +- It should be easy to **separate** content, graphic design, and + program code, but also easy to **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: + + + - for **programmers** to create reusable components and functions + that are accessible and understandable to designers. + + - for **designers** to mark out placeholders for content and + dynamic components in their templates. + + - for **designers** to soft-code aspects of their design that are + either repeated in several places or are subject to change. + + - for **designers** to reuse and extend existing templates and thus + minimize duplication of effort and code. + + - and, of course, for **content writers** to use the templates that + designers have created. + + + +Why Cheetah doesn't use HTML-style tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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., ``<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. + +Give me an example! +------------------- + +Here's a very simple example that illustrates some of Cheetah's +basic syntax: + +:: + + <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> + +Compare this with PSP: + +:: + + <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> + +Section gettingStarted.tutorial has a more typical example that +shows how to get the plug-in values **into** Cheetah, and section +howWorks.cheetah-compile explains how to turn your template +definition into an object-oriented Python module. + +Give me an example of a Webware servlet! +---------------------------------------- + +This example uses an HTML form to ask the user's name, then invokes +itself again to display a **personalized** friendly greeting. + +:: + + <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> + +To try it out for yourself on a Webware system: + + +#. copy the template definition to a file **test.tmpl** in your + Webware servlet directory. + +#. Run ``cheetah compile test.tmpl``. This produces ``test.py`` (a + .py template module) in the same directory. + +#. In your web browser, go to ``test.py``, using whatever site and + directory is appropriate. + +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. + +How mature is Cheetah? +---------------------- + +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. + + +Where can I get news? +--------------------- + +Cheetah releases can be obtained from the `Cheetah +website <http://cheetahtemplate.org>`_ + +Cheetah discussions take place on the `mailing +list <http://lists.sourceforge.net/lists/listinfo/cheetahtemplate-discuss>`_ + +If you encounter difficulties, or are unsure about how to do +something, please post a detailed message to the list. + +How can I contribute? +--------------------- + +Cheetah is the work of many volunteers. If you use Cheetah please +share your experiences, tricks, customizations, and frustrations. + +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: + + +#. a description of what you were trying to do and what happened + +#. all tracebacks and error output + +#. your version of Cheetah + +#. your version of Python + +#. your operating system + +#. whether you have changed anything in the Cheetah installation + + +Template libraries and function libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We hope to build up a framework of Template libraries (see section +libraries.templates) to distribute with Cheetah and would +appreciate any contributions. + +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." + +Publicity +~~~~~~~~~ + +Help spread the word ... recommend it to others, write articles +about it, etc. + +Acknowledgements +---------------- + +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. |