Changes between Initial Version and Version 1 of S3/S3Navigation

03/05/12 12:22:50 (10 years ago)
Dominic König



  • S3/S3Navigation

    v1 v1  
     2= S3Navigation =
     4S3Navigation is an S3 module providing a generic framework for the implementation of navigation elements in the web UI.
     6== S3NavigationItem ==
     8S3NavigationItem 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.
     10Navigation 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.
     12=== Subclassing S3NavigationItem ===
     14The 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'''.
     16To implement a Layout, create a new subclass of S3NavigationItem and implement a (static) method layout:
     19class MyMenuLayout(S3NavigationItem):
     21    @staticmethod
     22    def layout(item):
     23        # Layout implementation goes here
     26The 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.
     28The layout method can make use of the renderer API to retrieve the item's attributes and flags.
     30=== Defining Navigation Items ===
     32Once 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:
     35my_menu = MyMenuLayout("Home")(
     36             MyMenuLayout("First Item"),
     37             MyMenuLayout("Second Item"),
     38             MyMenuLayout("Submenu")(
     39                 MyMenuLayout("First SubmenuItem"),
     40                 MyMenuLayout("Second SubmenuItem")
     41             )
     42           )
     45Each particular item can receive any number of keyword parameters. The following keyword parameters are used by the base-class:
     48||'''label'''||string||The 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}}}||
     49||'''r'''||Request||The request object||if passed, then the item inherits {{{a}}}, {{{c}}}, and {{{f}}} from this {{{request}}}, i.e. the item will always match this {{{request}}}||
     50||'''a'''||string||The application name in the target URL||inherited from parent item||
     51||'''c'''||string||The controller name in the target URL||inherited from parent item||
     52||'''f'''||string||The function name in the target URL||inherited from parent item||
     53||'''args'''||list of strings, or string||the arguments in the target URL||if passed as single string, the arguments must be separated by slashes||
     54||'''vars'''||dict of strings||the query variables in the target URL||||
     55||'''extension'''||string||the URL extension (data format extension) in the target URL||defaults to {{{None}}}||
     56||'''p'''||string||the permission required to access this item||defaults to m||
     57||'''m'''||string||the URL method for the request||defaults to "", will be appended to {{{args}}} if not the last arg||
     58||'''t'''||string||the name of the table the permission is required for||defaults to {{{<c>_<f>}}}||
     59||'''tags'''||list of strings||a list of tags for this item||tags can later be used to address this item in the menu tree, e.g. to update flags||
     60||'''parent'''||the parent item||set the parent item explicitly||special purpose, defaults to {{{None}}} and should be left at that||
     61||'''translate'''||boolean||False will prevent automatic localization of the item label||||
     62||'''layout'''||function||use this function to render this item instead of the layout of the class||||
     63||'''check'''||boolean, function or mixed list of these types||conditions to check before rendering||functions will be called with the item as parameter and are expected to return a boolean||
     64||'''restrict'''||list of role IDs or UIDs||restrict access to this item to these roles||||
     65||'''link'''||boolean||whether to link this item to the specified target URL or not||defaults to {{{True}}} = all items get linked||
     66||'''mandatory'''||boolean||override active check - item is always active||''not implemented yet''||
     68All 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.
     70=== Rendering Navigation Items ===
     72To render a navigation element, just put it into the view like:
     78This will call the layout method of the element, provided whenever the element is ''active'' (i.e. relevant for the current request).
     80=== Implementing Layouts ===
     82== Eden Standard Menus ==
     84== Customizing Menus ==