From: Ben Darnell Date: Sun, 12 Jun 2011 04:57:53 +0000 (-0700) Subject: Update overview for new 2.0 features X-Git-Tag: v2.0.0~16 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=31e7b78d041fc57803eb8252aaa76bef2f5bfa36;p=thirdparty%2Ftornado.git Update overview for new 2.0 features --- diff --git a/website/templates/overview.html b/website/templates/overview.html index bcaa022aa..aae2718bc 100644 --- a/website/templates/overview.html +++ b/website/templates/overview.html @@ -5,5 +5,5 @@ {% block headertitle %}

overview

{% end %} {% block body %} - {{ markdown("overview.txt", toc=True) }} + {% raw markdown("overview.txt", toc=True) %} {% end %} diff --git a/website/templates/overview.txt b/website/templates/overview.txt index d39248d94..6e206c57b 100644 --- a/website/templates/overview.txt +++ b/website/templates/overview.txt @@ -324,6 +324,14 @@ the flexibility that other, stricter templating systems prevent. Consequently, if you write random stuff inside of your template expressions, you will get random Python errors when you execute the template. +All template output is escaped by default, using the +`tornado.escape.xhtml_escape` function. This behavior can be changed globally +by passing `autoescape=None` to the `Application` or `TemplateLoader` +constructors, for a template file with the `{% autoescape None %}` +directive, or for a single expression by replacing `{{ ... }}` with +`{% raw ...%}`. Additionally, in each of these places the name of an +alternative escaping function may be used instead of `None`. + ### Cookies and secure cookies @@ -708,13 +716,13 @@ Within `home.html`, you reference the `Entry` module rather than printing the HTML directly: {% for entry in entries %} - {{ modules.Entry(entry) }} + {% module Entry(entry) %} {% end %} Within `entry.html`, you reference the `Entry` module with the `show_comments` argument to show the expanded form of the entry: - {{ modules.Entry(entry, show_comments=True) }} + {% module Entry(entry, show_comments=True) %} Modules can include custom CSS and JavaScript functions by overriding the `embedded_css`, `embedded_javascript`, `javascript_files`, or @@ -733,6 +741,23 @@ a module is used on a page. CSS is always included in the `` of the page, and JavaScript is always included just before the `` tag at the end of the page. +When additional Python code is not required, a template file itself may +be used as a module. For example, the preceding example could be +rewritten to put the following in `module-entry.html`: + + {{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }} + + +This revised template module would be invoked with + + {% module Template("module-entry.html", show_comments=True) %} + +The `set_resources` function is only available in templates invoked via +`{% module Template(...) %}`. Unlike the `{% include ... %}` directive, +template modules have a distinct namespace from their containing template - +they can only see the global template namespace and their own keyword +arguments. + ### Non-blocking, asynchronous requests @@ -780,6 +805,26 @@ up after the client closes the connection (but see that method's docstring for caveats). +### Asynchronous HTTP clients + +Tornado includes two non-blocking HTTP client implementations: +`SimpleAsyncHTTPClient` and `CurlAsyncHTTPClient`. The simple client +has no external dependencies because it is implemented directly on top +of Tornado's `IOLoop`. The Curl client requires that `libcurl` and +`pycurl` be installed (and a recent version of each is highly +recommended to avoid bugs in older version's asynchronous interfaces), +but is more likely to be compatible with sites that exercise +little-used parts of the HTTP specification. + +Each of these clients is available in its own module +(`tornado.simple_httpclient` and `tornado.curl_httpclient`), as well as +via a configurable alias in `tornado.httpclient`. `SimpleAsyncHTTPClient` +is the default, but to use a different implementation call the +`AsyncHTTPClient.configure` method at startup: + + AsyncHTTPClient.configure('tornado.curl_httpclient.CurlAsyncHTTPClient') + + ### Third party authentication Tornado's `auth` module implements the authentication and authorization