Home       Trees       Indices       Help   
S3
Package s3 :: Module s3navigation :: Class S3NavigationItem
[frames] | no frames]

Class S3NavigationItem

source code

object --+
         |
        S3NavigationItem


Base class and API for navigation items.

Navigation items are GUI elements to navigate the application,
typically represented as hyperlinks. Besides form elements,
navigation items are most common type of GUI controls.

This base class can be used to implement both nagivation items
and navigation item containers (e.g. menus), each as subclasses.

Subclasses should implement the layout() method to render the item as
HTML (ideally using the web2py helpers). There is no default layout,
items will not be rendered at all unless the subclass implements a
layout method or the particular instance receives a renderer as
parameter.

Additionally, subclasses should implement the check_*() methods:

    Method:             Checks whether:

    check_active        this item belongs to the requested page
    check_enabled       this item is enabled
    check_permission    the user is permitted to access this item
    check_selected      the item has been selected to request the page

check_active is the first check run, and the only method that
actually deactivates the item completely, whereas the other
methods just set flags for the renderer. All of these methods
must return True or False for the respective condition.

There are default check_*() methods in this base class which support
a menu-alike behavior of the item - which may though not fit for all
navigation elements.

For more details, see the S3Navigation wiki page:
http://eden.sahanafoundation.org/wiki/S3/S3Navigation
Instance Methods
 
__init__(self, label=None, c=None, f=None, args=None, vars=None, extension=None, a=None, r=None, m=None, p=None, t=None, url=None, tags=None, parent=None, translate=True, layout=None, check=None, restrict=None, link=True, mandatory=False, ltr=False, **attributes)
Constructor		 source code
 
clone(self)
Clone this item and its components		 source code
 
check_active(self, request=None)
Check whether this item belongs to the requested page (request).		 source code
 
check_enabled(self)
Check whether this item is enabled.		 source code
 
check_permission(self)
Check whether the user is permitted to access this item.		 source code
 
check_selected(self, request=None)
Check whether this item is in the selected path (i.e.		 source code
 
check_hook(self)
Run hooked-in checks		 source code
 
__contains__(self, tag)
Check whether a tag is present in any item of the subtree		 source code
 
findall(self, tag)
Find all items within the tree with the specified tag		 source code
 
enable(self, tag=None)
Enable items		 source code
 
disable(self, tag=None)
Disable items		 source code
 
select(self, tag=None)
Select an item.		 source code
 
deselect_all(self)
De-select this item and all its descendants		 source code
 
set_layout(self, layout, recursive=False, tag=None)
Alter the renderer for a tagged subset of items in the subtree.		 source code
 
get(self, name, default=None)
Get a Python-attribute of this item instance, falls back to the same attribute in the parent item if not set in this instance, used to inherit attributes to components		 source code
 
match(self, request=None)
Match this item against request (uses GET vars)		 source code
 
branch(self, request=None)
Get the matching branch item for request		 source code
 
__repr__(self)
String representation of this item		 source code
 
url(self, extension=None, **kwargs)
Return the target URL for this item, doesn't check permissions		 source code
 
accessible_url(self, extension=None, **kwargs)
Return the target URL for this item if accessible by the current user, otherwise False		 source code
 
render(self, request=None)
Perform the checks and render this item.		 source code
 
render_components(self)
Render the components of this item and return the results as list		 source code
 
xml(self)
Invokes the renderer and serializes the output for the web2py template parser, returns a string to be written to the response body, uses the xml() method of the renderer output, if present.		 source code
 
set_parent(self, p=None, i=None)
Set a parent for this item, base method for tree construction		 source code
 
append(self, item=None)
Append a component		 source code
 
insert(self, i, item=None)
Insert a component item at position i		 source code
 
extend(self, items)
Extend this item with a list of components		 source code
 
__call__(self, *components)
Convenience shortcut for extend		 source code
 
__add__(self, items)
Append component items to this item		 source code
 
__getitem__(self, i)
Get the component item at position i		 source code
 
__setitem__(self, i, item)
Overwrite the component item at position i with item		 source code
 
pop(self, i=-1)
Return the component at index i and remove it from the list		 source code
 
get_root(self)
Get the top level item of this navigation tree		 source code
 
path(self, sub=None)
Get the full path to this item (=a list of items from the root item down to this item).		 source code
 
get_all(self, **flags)
Get all components with these flags		 source code
 
get_first(self, **flags)
Get the first component item with these flags		 source code
 
get_last(self, **flags)
Get the first component item with these flags		 source code
 
__len__(self)
The total number of components of this item		 source code
 
__nonzero__(self)
To be used instead of __len__ to determine the boolean value if this item, should always return True for instances		 source code
 
index(self, item)
Get the index of a component item within the component list		 source code
 
pos(self)
Get the position of this item within the parent's component list, reverse method for index()		 source code
 
is_first(self, **flags)
Check whether this is the first item within the parent's components list with these flags		 source code
 
is_last(self, **flags)
Check whether this is the last item within the parent's components list with these flags		 source code
 
preceding(self)
Get the preceding siblings within the parent's component list		 source code
 
following(self)
Get the following siblings within the parent's component list		 source code
 
get_prev(self, **flags)
Get the previous item in the parent's component list with these flags		 source code
 
get_next(self, **flags)
Get the next item in the parent's component list with these flags		 source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Static Methods
 
get_layout(name)
Check whether the current theme has a custom layout for this class, and if so, store it in current.layouts		 source code
Properties

Inherited from object: __class__

Method Details

__init__(self, label=None, c=None, f=None, args=None, vars=None, extension=None, a=None, r=None, m=None, p=None, t=None, url=None, tags=None, parent=None, translate=True, layout=None, check=None, restrict=None, link=True, mandatory=False, ltr=False, **attributes)
(Constructor)

source code 

Constructor

Parameters:
  • label - the label
  • c - the controller
  • f - the function
  • args - the arguments list
  • vars - the variables Storage
  • extension - the request extension
  • a - the application (defaults to current.request.application)
  • r - the request to default to
  • m - the URL method (will be appended to args)
  • p - the method to check authorization for (will not be appended to args)
  • t - the table concerned by this request (overrides c_f for auth)
  • url - a URL to use instead of building one manually
    • e.g. for external websites or mailto: links
  • tags - list of tags for this item
  • parent - the parent item
  • translate - translate the label
  • layout - the layout
  • check - a condition or list of conditions to automatically enable/disable this item
  • restrict - restrict to roles (role UID or list of role UIDs)
  • link - item has its own URL
  • mandatory - item is always active
  • ltr - item is always rendered LTR
  • attributes - attributes to use in layout
Overrides: object.__init__

get_layout(name)
Static Method

source code 

Check whether the current theme has a custom layout for this class, and if so, store it in current.layouts

Returns:
the layout or None if not present

clone(self)

source code 

Clone this item and its components

check_active(self, request=None)

source code 

Check whether this item belongs to the requested page (request).

If this check returns False, then the item will be deactivated entirely, i.e. no further checks will be run and the renderer will never be called.

Parameters:
  • request - the request object (defaults to current.request)

check_enabled(self)

source code 

Check whether this item is enabled.

This check does not directly disable the item, but rather sets the enabled-flag in the item which can then be used by the renderer.

This function is called as the very last action immediately before rendering the item. If it returns True, then the enabled-flag of the item remains unchanged, otherwise it gets set to False (False-override).

check_permission(self)

source code 

Check whether the user is permitted to access this item.

This check does not directly disable the item, but rather sets the authorized-flag in the item which can then be used by the renderer.

check_selected(self, request=None)

source code 

Check whether this item is in the selected path (i.e. whether it is or contains the item used to trigger the request).

This check doesn't change the processing of the item, but rather sets the selected-flag which can then be used by the renderer

If this is a top-level item, then this check sets the selected-flags for the whole selected path down to the leaf item that has triggered the request.

Note that this doesn't currently reset selected-flags, so this check can be performed only once per subtree and request. If it would be really neccessary to perform this check more than once, then it should be easy to implement a reset_flags method.

Parameters:
  • request - the request object, defaults to current.request

check_hook(self)

source code 

Run hooked-in checks

__contains__(self, tag)
(In operator)

source code 

Check whether a tag is present in any item of the subtree

findall(self, tag)

source code 

Find all items within the tree with the specified tag

Parameters:
  • tag - the tag

enable(self, tag=None)

source code 

Enable items

Parameters:
  • tag - enable all items in the subtree with this tag (no tag enables only this item)

disable(self, tag=None)

source code 

Disable items

Parameters:
  • tag - disable all items in the subtree with this tag (no tag disables only this item)

select(self, tag=None)

source code 

Select an item. If given a tag, this selects the first matching descendant (depth-first search), otherwise selects this item.

Propagates the selection up the path to the root item (including the root item)

Parameters:
  • tag - a string

deselect_all(self)

source code 

De-select this item and all its descendants

set_layout(self, layout, recursive=False, tag=None)

source code 

Alter the renderer for a tagged subset of items in the subtree.

Parameters:
  • layout - the layout (renderer)
  • recursive - set this layout recursively for the subtree
  • tag - set this layout only for items with this tag

get(self, name, default=None)

source code 

Get a Python-attribute of this item instance, falls back to the same attribute in the parent item if not set in this instance, used to inherit attributes to components

Parameters:
  • name - the attribute name

match(self, request=None)

source code 

Match this item against request (uses GET vars)

Parameters:
  • request - the request object (defaults to current.request)
Returns:
the match level (integer): 0=no match 1=controller 2=controller+function 3=controller+function+args 4=controller+function+args+vars

Note: currently ignores numerical arguments in the request, which is though subject to change (in order to support numerical arguments in the item)

branch(self, request=None)

source code 

Get the matching branch item for request

Parameters:
  • request - the request object (defaults to current.request)

__repr__(self)
(Representation operator)

source code 

String representation of this item

Overrides: object.__repr__

url(self, extension=None, **kwargs)

source code 

Return the target URL for this item, doesn't check permissions

Parameters:
  • extension - override the format extension
  • kwargs - override URL query vars

accessible_url(self, extension=None, **kwargs)

source code 

Return the target URL for this item if accessible by the current user, otherwise False

Parameters:
  • extension - override the format extension
  • kwargs - override URL query vars

render(self, request=None)

source code 

Perform the checks and render this item.

Parameters:
  • request - the request object (defaults to current.request)

render_components(self)

source code 

Render the components of this item and return the results as list

xml(self)

source code 

Invokes the renderer and serializes the output for the web2py template parser, returns a string to be written to the response body, uses the xml() method of the renderer output, if present.

set_parent(self, p=None, i=None)

source code 

Set a parent for this item, base method for tree construction

Parameters:
  • p - the parent
  • i - the list index where to insert the item

append(self, item=None)

source code 

Append a component

Parameters:
  • item - the component

insert(self, i, item=None)

source code 

Insert a component item at position i

Parameters:
  • i - the index position
  • item - the component item

extend(self, items)

source code 

Extend this item with a list of components

Parameters:
  • items - list of component items

__call__(self, *components)
(Call operator)

source code 

Convenience shortcut for extend

Parameters:
  • components - list of components

__add__(self, items)
(Addition operator)

source code 

Append component items to this item

Parameters:
  • items - the items to append

__getitem__(self, i)
(Indexing operator)

source code 

Get the component item at position i

Parameters:
  • i - the index of the component item

__setitem__(self, i, item)
(Index assignment operator)

source code 

Overwrite the component item at position i with item

Parameters:
  • i - the index within the component list
  • item - the item

pop(self, i=-1)

source code 

Return the component at index i and remove it from the list

Parameters:
  • i - the component index

get_root(self)

source code 

Get the top level item of this navigation tree

path(self, sub=None)

source code 

Get the full path to this item (=a list of items from the root item down to this item).

get_all(self, **flags)

source code 

Get all components with these flags

Parameters:
  • flags - dictionary of flags

get_first(self, **flags)

source code 

Get the first component item with these flags

Parameters:
  • flags - dictionary of flags

get_last(self, **flags)

source code 

Get the first component item with these flags

Parameters:
  • flags - dictionary of flags

__len__(self)
(Length operator)

source code 

The total number of components of this item

__nonzero__(self)
(Boolean test operator)

source code 

To be used instead of __len__ to determine the boolean value if this item, should always return True for instances

index(self, item)

source code 

Get the index of a component item within the component list

Parameters:
  • item - the item

pos(self)

source code 

Get the position of this item within the parent's component list, reverse method for index()

is_first(self, **flags)

source code 

Check whether this is the first item within the parent's components list with these flags

Parameters:
  • flags - dictionary of flags

is_last(self, **flags)

source code 

Check whether this is the last item within the parent's components list with these flags

Parameters:
  • flags - dictionary of flags

preceding(self)

source code 

Get the preceding siblings within the parent's component list

following(self)

source code 

Get the following siblings within the parent's component list

get_prev(self, **flags)

source code 

Get the previous item in the parent's component list with these flags

Parameters:
  • flags - dictionary of flags

get_next(self, **flags)

source code 

Get the next item in the parent's component list with these flags

Parameters:
  • flags - dictionary of flags

   Home       Trees       Indices       Help   
S3
Generated by Epydoc 3.0.1 on Fri Mar 15 08:51:50 2019 http://epydoc.sourceforge.net