"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/users_guide/webware.rst" between
cheetah3-3.1.0.tar.gz and cheetah3-3.2.0.tar.gz

About: Cheetah3 is a template engine and code generation tool for e.g. for Web development or Java, SQL, LaTeX, form email ... (written in Python).

webware.rst  (cheetah3-3.1.0):webware.rst  (cheetah3-3.2.0)
Using Cheetah with Webware Using Cheetah with Webware
========================== ==========================
(webware)
{ Webware for Python} is a 'Python-Powered Internet Platform' that { Webware for Python} is a 'Python-Powered Internet Platform' that
runs servlets in a manner similar to Java servlets. { WebKit} is runs servlets in a manner similar to Java servlets. { WebKit} is
the name of Webware's application server. For more details, please the name of Webware's application server. For more details, please
visit https://cito.github.io/w4py/. visit https://cito.github.io/w4py/.
All comments below refer to the official version of Webware, the All comments below refer to the official version of Webware, the
DamnSimple! offshoot at ?, and the now-abandoned DamnSimple! offshoot at ?, and the now-abandoned
WebwareExperimental implementation at WebwareExperimental implementation at
http://sourceforge.net/projects/expwebware/, except where noted. http://sourceforge.net/projects/expwebware/, except where noted.
All the implementations are 95% identical to the servlet writer: All the implementations are 95% identical to the servlet writer:
skipping to change at line 27 skipping to change at line 25
files. One difference is that the executable you run to launch files. One difference is that the executable you run to launch
standard Webware is called {AppServer}, whereas in standard Webware is called {AppServer}, whereas in
WebwareExperimental it's called {webkit}. But to servlets they're WebwareExperimental it's called {webkit}. But to servlets they're
both "WebKit, Webware's application server", so it's one half dozen both "WebKit, Webware's application server", so it's one half dozen
to the other. In this document, we generally use the term { WebKit} to the other. In this document, we generally use the term { WebKit}
to refer to the currently-running application server. to refer to the currently-running application server.
Installing Cheetah on a Webware system Installing Cheetah on a Webware system
-------------------------------------- --------------------------------------
(webware.installing)
Install Cheetah after you have installed Webware, following the Install Cheetah after you have installed Webware, following the
instructions in chapter gettingStarted. instructions in chapter gettingStarted.
The standard Cheetah test suite ('cheetah test') does not test The standard Cheetah test suite ('cheetah test') does not test
Webware features. We plan to build a test suite that can run as a Webware features. We plan to build a test suite that can run as a
Webware servlet, containing Webware-specific tests, but that has Webware servlet, containing Webware-specific tests, but that has
not been built yet. In the meantime, you can make a simple template not been built yet. In the meantime, you can make a simple template
containing something like "This is a very small template.", compile containing something like "This is a very small template.", compile
it, put the \*.py template module in a servlet directory, and see it, put the \*.py template module in a servlet directory, and see
if Webware serves it up OK. if Webware serves it up OK.
skipping to change at line 53 skipping to change at line 49
"ImportError: no module named Template". (This applies only to the "ImportError: no module named Template". (This applies only to the
standard Webware; WebwareExperimental does not have contexts.) standard Webware; WebwareExperimental does not have contexts.)
If Webware complains that it cannot find your servlet, make sure If Webware complains that it cannot find your servlet, make sure
'.tmpl' is listed in 'ExtensionsToIgnore' in your '.tmpl' is listed in 'ExtensionsToIgnore' in your
'Application.config' file. 'Application.config' file.
Containment vs Inheritance Containment vs Inheritance
-------------------------- --------------------------
(webware.background)
Because Cheetah's core is flexible, there are many ways to Because Cheetah's core is flexible, there are many ways to
integrate it with Webware servlets. There are two broad strategies: integrate it with Webware servlets. There are two broad strategies:
the { Inheritance approach} and the { Containment approach}. The the { Inheritance approach} and the { Containment approach}. The
difference is that in the Inheritance approach, your template difference is that in the Inheritance approach, your template
object { is} the servlet, whereas in the Containment approach, the object { is} the servlet, whereas in the Containment approach, the
servlet is not a template but merely { uses} template(s) for servlet is not a template but merely { uses} template(s) for
portion(s) of its work. portion(s) of its work.
The Inheritance approach is recommended for new sites because it's The Inheritance approach is recommended for new sites because it's
simpler, and because it scales well for large sites with a simpler, and because it scales well for large sites with a
skipping to change at line 94 skipping to change at line 88
Edmund Liam is preparing a section on a hybrid approach, in which Edmund Liam is preparing a section on a hybrid approach, in which
the servlet is not a template, but still calls template(s) in an the servlet is not a template, but still calls template(s) in an
inheritance chain to produce the output. The advantage of this inheritance chain to produce the output. The advantage of this
approach is that you aren't dealing with {Template} methods and approach is that you aren't dealing with {Template} methods and
Webware methods in the same object. Webware methods in the same object.
The Containment Approach The Containment Approach
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
(webware.containment)
In the Containment approach, your servlet is not a template. In the Containment approach, your servlet is not a template.
Instead, it it makes its own arrangements to create and use Instead, it it makes its own arrangements to create and use
template object(s) for whatever it needs. The servlet must template object(s) for whatever it needs. The servlet must
explicitly call the template objects' {.respond()} (or explicitly call the template objects' {.respond()} (or
{.\_\_str\_\_()}) method each time it needs to fill the template. {.\_\_str\_\_()}) method each time it needs to fill the template.
This does not present the output to the user; it merely gives the This does not present the output to the user; it merely gives the
output to the servlet. The servlet then calls its output to the servlet. The servlet then calls its
{#self.response().write()} method to send the output to the user. {#self.response().write()} method to send the output to the user.
The developer has several choices for managing her templates. She The developer has several choices for managing her templates. She
skipping to change at line 122 skipping to change at line 114
Because template objects are not thread safe, you should not store Because template objects are not thread safe, you should not store
one in a module variable and allow multiple servlets to fill it one in a module variable and allow multiple servlets to fill it
simultaneously. Instead, each servlet should instantiate its own simultaneously. Instead, each servlet should instantiate its own
template object. Template { classes}, however, are thread safe, template object. Template { classes}, however, are thread safe,
since they don't change once created. So it's safe to store a since they don't change once created. So it's safe to store a
template class in a module global variable. template class in a module global variable.
The Inheritance Approach The Inheritance Approach
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
(webware.inheritance)
In the Inheritance approach, your template object doubles as as In the Inheritance approach, your template object doubles as as
Webware servlet, thus these are sometimes called { Webware servlet, thus these are sometimes called {
template-servlets}. { cheetah compile} (section template-servlets}. { cheetah compile} (section
howWorks.cheetah-compile) automatically creates modules containing howWorks.cheetah-compile) automatically creates modules containing
valid Webware servlets. A servlet is a subclass of Webware's valid Webware servlets. A servlet is a subclass of Webware's
{WebKit.HTTPServlet} class, contained in a module with the same {WebKit.HTTPServlet} class, contained in a module with the same
name as the servlet. WebKit uses the request URL to find the name as the servlet. WebKit uses the request URL to find the
module, and then instantiates the servlet/template. The servlet module, and then instantiates the servlet/template. The servlet
must have a {.respond()} method (or {.respondToGet()}, must have a {.respond()} method (or {.respondToGet()},
{.respondToPut()}, etc., but the Cheetah default is {.respond()}). {.respondToPut()}, etc., but the Cheetah default is {.respond()}).
skipping to change at line 177 skipping to change at line 167
Because Webware servlets must be valid Python modules, and Because Webware servlets must be valid Python modules, and
"cheetah compile" can produce only valid module names, if you're "cheetah compile" can produce only valid module names, if you're
converting an existing site that has .html filenames with hyphens converting an existing site that has .html filenames with hyphens
(-), extra dots (.), etc, you'll have to rename them (and possibly (-), extra dots (.), etc, you'll have to rename them (and possibly
use redirects). use redirects).
Site frameworks Site frameworks
--------------- ---------------
(webware.siteFrameworks)
Web sites are normally arranged hierarchically, with certain Web sites are normally arranged hierarchically, with certain
features common to every page on the site, other features common to features common to every page on the site, other features common to
certain sections or subsections, and others unique to each page. certain sections or subsections, and others unique to each page.
You can model this easily with a hierarchy of classes, with You can model this easily with a hierarchy of classes, with
specific servlets inheriting from their more general superclasses. specific servlets inheriting from their more general superclasses.
Again, you can do this two ways, using Cheetah's { Containment} Again, you can do this two ways, using Cheetah's { Containment}
approach or { Inheritance} approach. approach or { Inheritance} approach.
In the Inheritance approach, parents provide {#block}s and children In the Inheritance approach, parents provide {#block}s and children
override them using {#def}. Each child {#extend}s its immediate override them using {#def}. Each child {#extend}s its immediate
skipping to change at line 217 skipping to change at line 205
not designed to intermix with {Cheetah.Templates.SkeletonPage}. not designed to intermix with {Cheetah.Templates.SkeletonPage}.
Choose either one or the other, or expect to do some integration Choose either one or the other, or expect to do some integration
work. work.
If you come up with a different strategy you think is worth noting If you come up with a different strategy you think is worth noting
in this chapter, let us know. in this chapter, let us know.
Directory structure Directory structure
------------------- -------------------
(webware.directoryStructure)
Here's one way to organize your files for Webware+Cheetah. Here's one way to organize your files for Webware+Cheetah.
:: ::
www/ # Web root directory. www/ # Web root directory.
site1.example.com/ # Site subdirectory. site1.example.com/ # Site subdirectory.
apache/ # Web server document root (for non-servlets). apache/ # Web server document root (for non-servlets).
www/ # WebKit document root. www/ # WebKit document root.
index.py # http://site1.example.com/ index.py # http://site1.example.com/
index.tmpl # Source for above. index.tmpl # Source for above.
skipping to change at line 246 skipping to change at line 232
Webware/ # Standard Webware's MakeAppWorkDir directory. Webware/ # Standard Webware's MakeAppWorkDir directory.
AppServer # Startup program (for standard Webware). AppServer # Startup program (for standard Webware).
Configs/ # Configuration directory (for standard Webware ). Configs/ # Configuration directory (for standard Webware ).
Application.config Application.config
# Configuration file (for standard Webware). # Configuration file (for standard Webware).
site2.example.org/ # Another virtual host on this computer.... site2.example.org/ # Another virtual host on this computer....
Initializing your template-servlet with Python code Initializing your template-servlet with Python code
--------------------------------------------------- ---------------------------------------------------
(webware.calculations)
If you need a place to initialize variables or do calculations for If you need a place to initialize variables or do calculations for
your template-servlet, you can put it in an {.awake()} method your template-servlet, you can put it in an {.awake()} method
because WebKit automatically calls that early when processing the because WebKit automatically calls that early when processing the
web transaction. If you do override {.awake()}, be sure to call the web transaction. If you do override {.awake()}, be sure to call the
superclass {.awake} method. You probably want to do that first so superclass {.awake} method. You probably want to do that first so
that you have access to the web transaction data {Servlet.awake} that you have access to the web transaction data {Servlet.awake}
provides. You don't have to worry about whether your parent class provides. You don't have to worry about whether your parent class
has its own {.awake} method, just call it anyway, and somebody up has its own {.awake} method, just call it anyway, and somebody up
the inheritance chain will respond, or at minimum {Servlet.awake} the inheritance chain will respond, or at minimum {Servlet.awake}
will respond. Section tips.callingSuperclassMethods gives examples will respond. Section tips.callingSuperclassMethods gives examples
of how to call a superclass method. of how to call a superclass method.
As an alternative, you can put all your calculations in your own As an alternative, you can put all your calculations in your own
method and call it near the top of your template. ({#silent}, method and call it near the top of your template. ({#silent},
section output.silent). section output.silent).
Form processing Form processing
--------------- ---------------
(webware.form)
There are many ways to display and process HTML forms with Cheetah. There are many ways to display and process HTML forms with Cheetah.
But basically, all form processing involves two steps. But basically, all form processing involves two steps.
#. Display the form. #. Display the form.
#. In the next web request, read the parameters the user submitted, #. In the next web request, read the parameters the user submitted,
check for user errors, perform any side effects (e.g., check for user errors, perform any side effects (e.g.,
reading/writing a database or session data) and present the user an reading/writing a database or session data) and present the user an
HTML response or another form. HTML response or another form.
skipping to change at line 347 skipping to change at line 329
{FunFormKit} is a third-party Webware package that makes it easier {FunFormKit} is a third-party Webware package that makes it easier
to produce forms and handle their logic. It has been successfully to produce forms and handle their logic. It has been successfully
been used with Cheetah. You can download FunFormKit from been used with Cheetah. You can download FunFormKit from
http://colorstudy.net/software/funformkit/ and try it out for http://colorstudy.net/software/funformkit/ and try it out for
yourself. yourself.
Form input, cookies, session variables and web server variables Form input, cookies, session variables and web server variables
--------------------------------------------------------------- ---------------------------------------------------------------
(webware.input)
General variable tips that also apply to servlets are in section General variable tips that also apply to servlets are in section
tips.placeholder. tips.placeholder.
To look up a CGI GET or POST parameter (with POST overriding): To look up a CGI GET or POST parameter (with POST overriding):
:: ::
$request.field('myField') $request.field('myField')
self.request().field('myField') self.request().field('myField')
skipping to change at line 415 skipping to change at line 395
$request.serverURL ## URL of this servlet, without "http://" prefix, $request.serverURL ## URL of this servlet, without "http://" prefix,
## extra path info or query string. ## extra path info or query string.
$request.serverURLDir ## URL of this servlet's directory, without "http:// ". $request.serverURLDir ## URL of this servlet's directory, without "http:// ".
$log("message") ## Put a message in the Webware server log. (If you $log("message") ## Put a message in the Webware server log. (If you
## define your own 'log' variable, it will override ## define your own 'log' variable, it will override
## this; use $self.log("message") in that case. ## this; use $self.log("message") in that case.
.webInput() .webInput()
~~~~~~~~~~~ ~~~~~~~~~~~
(webware.webInput)
From the method docstring: From the method docstring:
:: ::
def webInput(self, names, namesMulti=(), default='', src='f', def webInput(self, names, namesMulti=(), default='', src='f',
defaultInt=0, defaultFloat=0.00, badInt=0, badFloat=0.00, debug=Fals e): defaultInt=0, defaultFloat=0.00, badInt=0, badFloat=0.00, debug=Fals e):
This method places the specified GET/POST fields, cookies or session variabl es This method places the specified GET/POST fields, cookies or session variabl es
into a dictionary, which is both returned and put at the beginning of the into a dictionary, which is both returned and put at the beginning of the
searchList. It handles: searchList. It handles:
skipping to change at line 564 skipping to change at line 542
This mixin class works only in a subclass that also inherits from This mixin class works only in a subclass that also inherits from
Webware's Servlet or HTTPServlet. Otherwise you'll get an AttributeError Webware's Servlet or HTTPServlet. Otherwise you'll get an AttributeError
on 'self.request'. on 'self.request'.
EXCEPTIONS: ValueError if 'source' is not one of the stated characters. EXCEPTIONS: ValueError if 'source' is not one of the stated characters.
TypeError if a conversion suffix is not ":int" or ":float". TypeError if a conversion suffix is not ":int" or ":float".
More examples More examples
------------- -------------
(webware.examples)
Example A - a standalone servlet Example A - a standalone servlet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example B - a servlet under a site framework Example B - a servlet under a site framework
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example C - several servlets with a common template Example C - several servlets with a common template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Other Tips Other Tips
---------- ----------
(webware.otherTips)
If your servlet accesses external files (e.g., via an {#include} If your servlet accesses external files (e.g., via an {#include}
directive), remember that the current directory is not necessarily directive), remember that the current directory is not necessarily
directory the servlet is in. It's probably some other directory directory the servlet is in. It's probably some other directory
WebKit chose. To find a file relative to the servlet's directory, WebKit chose. To find a file relative to the servlet's directory,
prefix the path with whatever {self.serverSidePath()} returns (from prefix the path with whatever {self.serverSidePath()} returns (from
{Servlet.serverSidePath()}. {Servlet.serverSidePath()}.
If you don't understand how {#extends} and {#implements} work, and If you don't understand how {#extends} and {#implements} work, and
about a template's main method, read the chapter on inheritance about a template's main method, read the chapter on inheritance
(sections inheritanceEtc.extends and inheritanceEtc.implements). (sections inheritanceEtc.extends and inheritanceEtc.implements).
 End of changes. 13 change blocks. 
26 lines changed or deleted 0 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)