Version 2 (modified by Dominic König, 12 years ago) ( diff )



S3Navigation is an S3 module providing a generic framework for the implementation of navigation elements in the web UI.


S3NavigationItem is a base class for the implementation of navigation items, and provides the common logic for all types of navigation items as well as an API for renderers.

Navigation items are UI elements to navigate the application, and can appear as menus, breadcrumb rows, tab rows, and various other types of links. They all have in common that they are linked to request URLs and usually get activated by clicking them.

Subclassing S3NavigationItem

The S3NavigationItem class is not meant to be used directly for the implementation of navigation items. Instead, it should be subclassed for each type of navigation items the user interface needs. Subclasses of S3NavigationItem are supposed to implement the layout of the respective item type, and are therefore referred to as Layouts.

To implement a Layout, create a new subclass of S3NavigationItem and implement a (static) method layout:

class MyMenuLayout(S3NavigationItem):

    def layout(item):
        # Layout implementation goes here

The layout method takes an instance of the layout class as parameter, and returns an instance of a web2py HTML helper class (DIV or a subclass of it). This HTML instance is what eventually gets written into the view.

The layout method can make use of the renderer API to retrieve the item's attributes and flags.

Defining Navigation Items

Once you have implemented the Layout, you can create instances of it to define the particular navigation elements. The elements can be nested using the call-method:

my_menu = MyMenuLayout("Home")(
             MyMenuLayout("First Item"),
             MyMenuLayout("Second Item"),
                 MyMenuLayout("First SubmenuItem"),
                 MyMenuLayout("Second SubmenuItem")

Each particular item can receive any number of keyword parameters. The following keyword parameters are used by the base-class:

labelstringThe label for the item (if any)always the first parameter, so the keyword can be omitted; labels which are not already T instances (localized strings) will automatically be rendered with T unless you set translate=False
rRequestThe request objectif passed, then the item inherits a, c, and f from this request, i.e. the item will always match this request
astringThe application name in the target URLinherited from parent item
cstringThe controller name in the target URLinherited from parent item
fstringThe function name in the target URLinherited from parent item
argslist of strings, or stringthe arguments in the target URLif passed as single string, the arguments must be separated by slashes
varsdict of stringsthe query variables in the target URL
extensionstringthe URL extension (data format extension) in the target URLdefaults to None
pstringthe permission required to access this itemdefaults to m
mstringthe URL method for the requestdefaults to "", will be appended to args if not the last arg
tstringthe name of the table the permission is required fordefaults to <c>_<f>
tagslist of stringsa list of tags for this itemtags can later be used to address this item in the menu tree, e.g. to update flags
parentthe parent itemset the parent item explicitlyspecial purpose, defaults to None and should be left at that
translatebooleanFalse will prevent automatic localization of the item label
layoutfunctionuse this function to render this item instead of the layout of the class
checkboolean, function or mixed list of these typesconditions to check before renderingfunctions will be called with the item as parameter and are expected to return a boolean
restrictlist of role IDs or UIDsrestrict access to this item to these roles
linkbooleanwhether to link this item to the specified target URL or notdefaults to True = all items get linked
mandatorybooleanoverride active check - item is always activenot implemented yet

All other keyword parameters will be stored in the item instance and passed on to the layout method - keywords starting with an "_" underscore will be stored in item.attributes, all other keywords in item.options (it is up to the layout method to deal with those then).

Rendering Navigation Items

To render a navigation element, just put it into the view like:


This will call the layout method of the element, provided whenever the element is active (i.e. relevant for the current request).

Implementing Layouts

Eden Standard Menus

Customizing Menus

Note: See TracWiki for help on using the wiki.