This chapter is a tutorial about creating effective and maintainable web pages. The following subjects are covered:
For details on the different subjects, you must read the other chapters in this manual. This chapter is a summary to get you started quickly.
This text is not yet finished, it will be more detailed in a future version
To avoid repeating parts of your page code over and over again in each page you should
define the general layout and common parts of your pages in one or more template pages.
All your other Ypages can then just contain the template declaration, and only the page content
that is different in each page. The template page could define a common header, menu, body layout,
footer and script/css links, and the rest of the pages only define the body content.
If you want to change the layout of the site you only have to update the template and all your
pages will use the new layout.
You can define a template page in every Ypage or define one global template for all pages
using the webapp's defaultPageTemplate config variable.
As a template page is just an Ypage, you can do all sorts of dynamic page creation code inside it. It is even possible to pass page-specific variables from every templated ypage into the template page, so that you may use that in the template (example: to give every page a page-specific title, where the title is defined in the templated page). These template args can be simple and static, or dynamically created using a special page method.
Another possibility is to put parts of a page that are used over and over again inside a separate Ypage that is not accessed directly. Rather, you include it inside other Ypages that want to use it. For instance: if you find that you are building a complicated table structure on several different pages, you can put the table code in a separate Ypage file and include it in the other pages. If you want to change the table, you only have to make changes in one file, and the table is changed on all pages.
A more advanced way is to use inheritance to let your Ypage inherit from
another Ypage or even from a custom Python class. You can put common code in the base Ypage or
class and let multiple pages inherit from it, so that they will share the code.
It is possible to let the base Ypage handle the page creation (and refer to the inherited page)
by using the pagemethod declaration.
Ypages and Snakelets are essentially just Python classes so you an import and use other modules and classes just like you would otherwise do to structure your Python program. Put common code and/or code that is not related to the actual page content in a different module, and import that in your Ypage/Snakelet, so that the rest of the code can stay concise and clean. Use subdirectories to divide and group related pages (just as you would use packages in regular Python code).
Some characters are invalid inside HTML (such as <, >, & and "). If you
generate HTML, you have to make sure that you escape (also called quote)
those special characters. You should use the self.escape(text) method for this.
Escaping is only needed at the place where you actually want to output the text on the page.
The same counts for URLs. There are a few other characters that cannot occur in an URL because
they have a special meaning (/, +, ? and = for instance). If you need to put those in an URL
where they do not have that special meaning (for instance, where they are part of
the URL query params in case of a GET request with params), you have to escape them.
You should use the self.urlescape(path) method for this.
Note that the URL-escaped string may be a valid URL, but it may still contain characters
that are invalid in HTML! So if you want to place it inside your page text, you usually
have to run it trough the HTML escape function before outputting it on the page.
Generating correct URL links on your page is not a trivial task, if you want
your page code to be independent of the server name, port, webapp name, prefix and whatnot.
URLs have the form: http://server:port/serverprefix/webapp/... (serverprefix is optional).
If you only use relative urls (such as <a href="sub/page.y">....)
you don't have to worry about the url base part because the browser fills it in.
But usually it is better to use an absolute url (in a menu, to avoid nesting issues) or
even an url that includes the http: part, and the servername and port.
You can hardcode these values in your pages but then they cease to work when you move to a different
server or rename the webapp...
| Relevant functions | |
|---|---|
| for Ypages | for Ypages and Snakelets |
|
These are shortcuts to functions defined
elsewhere (see the column to the right) to make it easier to use inside an Ypage: self.URLprefix self.Assetprefix url(path) asset(path) |
Defined on the Snakelet/Ypage class:
self.getFullURL() self.getURL() self.urlescape(str) # see above, at 'escaping'Defined on the Webapp: wa.getURLprefix() wa.getAssetprefix() wa.mkUrl(path) wa.mkAssetUrl(path)Defined on the Request object: req.getRequestURL() req.getRequestURLplain() req.getBaseURL()And perhaps some more (see relevant chapters) |
...explanation not yet written...
With other web servers, the correct handling of non-ASCII characters or symbols often is a pain.
Not with Snakelets. You only have to set the output encoding of your page to the desired
encoding (such as UTF-8), and optionally set the input encoding too (if your source file is
written in a special character encoding), and Snakelets takes care of all the rest.
Don't encode stuff yourself, just write those unicode strings to the page output!
If you are careful about the way you add FORMs to your pages (see below), the input
of special characters is painless too. Snakelets handles everything and you get to deal
with Python strings (or unicode objects) only. All symbols are supported. The suggested
character encoding is UTF-8 (it can contain all symbols, is widely supported, and
works efficiently for most western languages).
You can define a character encoding in every page or define one global setting for all pages
using the webapp's defaultOutputEncoding config variable.
Usually the default content type text/html is fine. But for special snakelets
or Ypages you are not returning HTML, but a different file type (when you have created
an image downloading snakelet, for instance). You have to specify the correct content type
yourself in these cases.
....write how to do this... defaultContentType....
...not yet written...
Snakelets manual - Back to index