Custom helpers

TAG

Sometimes you need to generate custom XML tags. web2py provides TAG, a universal tag generator.

{{=TAG.name('a', 'b', _c='d')}}

generates the following XML

<name c="d">ab</name>

Arguments “a”, “b”, and “d” are automatically escaped; use the XML helper to suppress this behavior. Using TAG you can generate HTML/XML tags not already provided by the API. TAGs can be nested, and are serialized with str(). An equivalent syntax is:

{{=TAG['name']('a', 'b', c='d')}}

If the TAG object is created with an empty name, it can be used to concatenate multiple strings and HTML helpers together without inserting them into a surrounding tag, but this use is deprecated. Use the CAT helper instead.

Self-closing tags can be generated with the TAG helper. The tag name must end with a “/“.

{{=TAG['link/'](_href='http://web2py.com')}}

generates the following XML:

<link ref="http://web2py.com"/>

Notice that TAG is an object, and TAG.name or TAG['name'] is a function that returns a temporary helper class.

MENU

The MENU helper takes a list of lists or of tuples of the form of response.menu (as described in Chapter 4) and generates a tree-like structure using unordered lists representing the menu. For example:

>>> print MENU([['One', False, 'link1'], ['Two', False, 'link2']])
<ul class="web2py-menu web2py-menu-vertical">
<li><a href="link1">One</a></li>
<li><a href="link2">Two</a></li>
</ul>

The first item in each list/tuple is the text to be displayed for the given menu item.

The second item in each list/tuple is a boolean indicating whether that particular menu item is active (i.e., the currently selected item). When set to True, the MENU helper will add a “web2py-menu-active” class to the <li> for that item (you can change the name of that class via the “li_active” argument to MENU). Another way to specify the active url is by directly passing it to MENU via its “active_url” argument.

The third item in each list/tuple can be an HTML helper (which could include nested helpers), and the MENU helper will simply render that helper rather than creating its own <a> tag.

Each menu item can have a fourth argument that is a nested submenu (and so on recursively):

>>> print MENU([['One', False, 'link1', [['Two', False, 'link2']]]])
<ul class="web2py-menu web2py-menu-vertical">
<li class="web2py-menu-expand">
<a href="link1">One</a>
<ul class="web2py-menu-vertical">
<li><a href="link2">Two</a></li>
</ul>
</li>
</ul>

A menu item can also have an optional 5th element, which is a boolean. When false, the menu item is ignored by the MENU helper.

The MENU helper takes the following optional arguments:

• _class: defaults to “web2py-menu web2py-menu-vertical” and sets the class of the outer UL elements.
• ul_class: defaults to “web2py-menu-vertical” and sets the class of the inner UL elements.
• li_class: defaults to “web2py-menu-expand” and sets the class of the inner LI elements.
• li_first: allows to add a class to the first list element.
• li_last: allows to add a class to the last list element.

MENU takes an optional argument mobile. When set to True instead of building a recursive UL menu structure it returns a SELECT dropdown with all the menu options and a onchange attribute that redirects to the page corresponding to the selected option. This is designed an an alternative menu representation that increases usability on small mobile devices such as phones.

Normally the menu is used in a layout with the following syntax:

{{=MENU(response.menu, mobile=request.user_agent().is_mobile)}}

In this way a mobile device is automatically detected and the menu is rendered accordingly.