Helpers

Helpers are functions intended for usage in templates, to assist with common
HTML and text manipulation, higher level constructs like a HTML
tag builder (that safely escapes variables), and advanced functionality
like Pagination of data sets.

To make individual helpers available for use in templates under :term:`h`, the
appropriate functions need to be imported in :file:`lib/helpers.py`. All the
functions available in this file are then available under :term:`h` just like
any other module reference.

By customizing the :file:`lib/helpers.py` module you can quickly add custom
functions and classes for use in your templates.

Helper functions are organized into modules by theme. All HTML generators are under the webhelpers_html package, except for a few third-party modules which are directly under webhelpers. The webhelpers modules are separately documented, see :mod:`webhelpers`.

Pagination

Note

The paginate module is not compatible to the deprecated pagination
module that was provided with former versions of the Webhelpers package.

Purpose of a paginator

When you display large amounts of data like a result from an SQL query then
usually you cannot display all the results on a single page. It would simply be
too much. So you divide the data into smaller chunks. This is what a paginator
does. It shows one page of chunk of data at a time. Imagine you are providing a
company phonebook through the web and let the user search the entries. Assume
the search result contains 23 entries. You may decide to display no more than 10
entries per page. The first page contains entries 1-10, the second 11-20 and the
third 21-23. And you also show a navigational element like
Page 1 of 3: [1] 2 3 that allows the user to switch between the available
pages.

The Page class

The :mod:`webhelpers` package provides a paginate module that can be used
for this purpose. It can create pages from simple Python lists as well as
SQLAlchemy queries and SQLAlchemy select objects. The module provides a Page
object that represents a single page of items from a larger result set. Such a
Page mainly behaves like a list of items on that page. Let's take the above
example of 23 items spread across 3 pages:

# Create a list of items from 1 to 23
>>> items = range(1,24)
# Import the paginate module
>>> import webhelpers.paginate
# Create a Page object from the 'items' for the second page
>>> page2 = webhelpers.paginate.Page(items, page=2, items_per_page=10)
# The Page object can be printed (__repr__) to show details on the page
>>> page2
Page:
Collection type: <type 'list'>
(Current) page: 2
First item: 11
Last item: 20
First page: 1
Last page: 3
Previous page: 1
Next page: 3
Items per page: 10
Number of items: 23
Number of pages: 3
# Show the items on this page
>>> list(page2)
[11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
# Print the items in a for loop
>>> for i in page2: print "This is entry", i
This is entry 11
This is entry 12
This is entry 13
This is entry 14
This is entry 15
This is entry 16
This is entry 17
This is entry 18
This is entry 19
This is entry 20

Page numbers and item numbers start from 1. If you are accessing the
items on the page by their index please note that the first item is
item[1] instead of item[0].

Switching between pages using a pager

The user needs a way to get to another page. This is usually done with a list
of links like Page 3 of 41 - 1 2 [3] 4 5 .. 41. Such a list can be
created by the Page's :meth:`~webhelpers.paginate.Page.pager` method.
Take the above example again:

Without the HTML tags it looks like 1 [2] 3. The links point to a URL
where the respective page is found. And the current page (2) is highlighted.

The appearance of a pager can be customized. By default the format string
is ~2~ which means it shows adjacent pages from the current page with
a maximal radius of 2. In a larger set this would look like
1 .. 34 35 [36] 37 38 .. 176. The radius of 2 means that two pages before
and after the current page 36 are shown.

Several special variables can be used in the format string. See
:meth:`~webhelpers.paginate.Page.pager` for a complete list. Some examples
for a pager of 20 pages while being on page 10 currently:

The paginate module is smart enough to only query the database for the
objects that are needed on this page. E.g. if a page consists of the items
11-20 then SQLAlchemy will be asked to fetch exactly that 10 rows
through LIMIT and OFFSET in the actual SQL query. So you must not load
the complete result set into memory and pass that. Instead always pass
a query when creating a Page.

Paging over an SQLAlchemy select

SQLAlchemy also allows to run arbitrary SELECTs on database tables.
This is useful for non-ORM queries. paginate can use such select
objects, too. Example:

The only difference to using SQLAlchemy query objects is that you need to
pass an SQLAlchemy session via the sqlalchemy_session parameter.
A bare select does not have a database connection assigned. But the session
has.

The pager() creates links to the previous URL and just sets the
page parameter appropriately. That's why you need to pass the requested page
number (request.params['page']) when you create a Page.

Partial updates with AJAX

Updating a page partially is easy. All it takes is a little Javascript
that - instead of loading the complete page - updates just the part
of the page containing the paginated items. The pager() method accepts an
onclick parameter for that purpose. This value is added as an onclick
parameter to the A-HREF tags. So the href parameter points to a URL
that loads the complete page while the onclick parameter provides Javascript
that loads a partial page. An example (using the jQuery Javascript library for
simplification) may help explain that.

To avoid code duplication in the template the full template includes the partial
template. If a partial page load is requested then just the
list-partial.mako gets rendered. And if a full page load is requested then
the list-full.mako is rendered which in turn includes the
list-partial.mako.

The %s variable in the onclick string gets replaced with a URL pointing
to the respective page with a partial=1 added (the name of the parameter can be customized through the partial_param parameter). Example:

jQuery's syntax to load a URL into a certain DOM object (e.g. a DIV) is simply:

$('#some-id').load('/the/url')

The advantage of this technique is that it degrades gracefully. If the user does
not have Javascript enabled then a full page is loaded. And if Javascript works
then a partial load is done through the onclick action.

Secure Form Tag Helpers

For prevention of Cross-site request forgery (CSRF) attacks.

Generates form tags that include client-specific authorization tokens to be
verified by the destined web app.

Authorization tokens are stored in the client's session. The web app can then
verify the request's submitted authorization token with the value in the
client's session.

This ensures the request came from the originating page. See the wikipedia entry
for Cross-site request forgery for more information.

Pylons provides an authenticate_form decorator that does this verification
on the behalf of controllers.

These helpers depend on Pylons' session object. Most of them can be easily
ported to another framework by changing the API calls.

The helpers are implemented in such a way that it should be easy for developers
to create their own helpers if using helpers for AJAX calls.

:func:`authentication_token` returns the current authentication token, creating one
and storing it in the session if it doesn't already exist.