Package turbogears :: Package widgets :: Module base :: Class Widget

Class Widget

object --+
         |
        Widget

Known Subclasses:

A TurboGears Widget.

'__init__' and 'update_params' are the only methods you might need to
care extending.

Attributes you should know about:

name:        The name of the widget.
template:    The Genshi or Kid template for the widget.
engine_name: The name of the templating engine to be used for
             rendering the template. You can also specify the engine
             by adding a 'genshi:' or 'kid:' prefix to the template.
             If the engine is not specified, and cannot be derived
             from a xmlns:py attribute in the template source, then
             the global default_engine ('genshi') will be used.
default:     Default value for the widget.
css:         List of CSSLinks and CSSSources for the widget. These
             will be automatically pulled and inserted in the
             page template that displays it.
javascript:  List of JSLinks and JSSources for the widget. Same as css.
is_named:    A property returning True if the widget has overridden its
             default name.
params:      All parameter names listed here will be treated as special
             parameters. This list is updated by the metaclass and
             always contains *all* params from the widget itself and
             all its bases. Can be used as a quick reminder of all
             the params your widget has at its disposal. They all
             behave the same and have the same priorities regarding their
             overridal. Read on...
params_doc:  A dictionary containing 'params' names as keys and their
             docstring as value. For documentation at the widget browser.

All initialization parameters listed at the class attribute "params" can be
defined as class attributes, overridden at __init__ or at display time.
They will be treated as special params for the widget, which means:

1) You can fix default values for them when subclassing Widget.

2) If passed as **params to the constructor, the will be bound automatically
   to the widget instance, taking preference over any class attributes
   previously defined. Mutable attributes (dicts and lists) defined as class
   attributes are safe to modify as care is taken to copy them so the class
   attribute remains unchanged.

3) They can be further overriden by passing them as keyword arguments to the
   display() method. This will only affect that display() method call in a
   thread-safe way.

4) A callable can be passed and it will be called automatically when sending
   variables to the template. This can be handy to pick up parameters which
   change in every request or affect many widgets simultaneously.

Nested Classes
	__metaclass__ The meta class for widgets.

Instance Methods

__init__(self, *args, **kw)
Widget initialization.

source code

adjust_value(self, value, **params)
Adjust the value sent to the template on display.

source code

update_params(self, params)
Update the template parameters.

source code

__call__(self, *args, **params)
Delegate to display.

source code

display(self, value=None, **params)
Display the widget in a Genshi or Kid template.

source code

render(self, value=None, format='html', **params)
Exactly the same as display() but return serialized output instead. source code

retrieve_javascript(self)
Return the needed JavaScript resources.

source code

retrieve_css(self)
Return the needed CSS resources.

source code

__setattr__(self, key, value)
x.__setattr__('name', value) <==> x.name = value

source code

__repr__(self)
repr(x)

source code

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

Class Variables
	name = `'widget'`
	template = `None` hash(x)
	engine_name = `None` hash(x)
	default = `None` hash(x)
	css = `[]`
	javascript = `[]`
	params = `[]`
	params_doc = `{}`

Properties
	is_named Return True if the widget has overridden its default name.
Inherited from `object`: `__class__`

Method Details

init(self, *args, **kw)
(Constructor)

source code

Widget initialization.

All initialization has to take place in this method.
It's not thread-safe to mutate widget's attributes outside this method
or anytime after widget's first display.

*Must* call super(MyWidget, self).__init__(*args, **kw) cooperatively,
unless, of course, you know what you're doing. Preferably this should
be done before any actual work is done in the method.

Parameters:

name:        The widget's name. In input widgets, this will also be the
             name of the variable that the form will send to the
             controller. This is the only param that is safe to pass as a
             positional argument to __init__.
template:    The template that the widget should use to display itself.
             Currently only Genshi and Kid templates are supported. You
             can both initialize with a template string or with the path
             to a file-base template: 'myapp.templates.widget_tmpl'
engine_name: The engine to be used for rendering the template, if not
             specified in the template already.
default:     Default value to display when no value is passed at display
             time.
**params:    Keyword arguments specific to your widget or to any of its
             bases. If listed at class attribute 'params' the will be
             bound automatically to the widget instance.

Note: Do not confuse these parameters with parameters listed at
"params". Some widgets accept parameters at the constructor which are
not listed params, these parameter won't be passed to the template, be
automatically called, etc.

Overrides: object.__init__

update_params(self, params)

source code

Update the template parameters.

This method will have the last chance to update the variables sent to the template for the specific request. All parameters listed at class attribute 'params' will be available at the 'params' dict this method receives.

*Must* call super(MyWidget, self).update_params(params) cooperatively, unless, of course, your know what you're doing. Preferably this should be done before any actual work is done in the method.

call(self, *args, **params)
(Call operator)

source code

Delegate to display. Used as an alias to avoid tiresome typing.

display(self, value=None, **params)

source code

Display the widget in a Genshi or Kid template.

Returns a Genshi Markup stream or an ElementTree node instance,
depending on the template in which the widget shall be displayed.
If you need serialized output in a string, call 'render' instead.

Probably you will not need to override or extend if inheriting from
Widget.

@params:

value   : The value to display in the widget.
**params: Extra parameters specific to the widget. All keyword params
          supplied will pass through the update_params method which
          will have a last chance to modify them before reaching the
          template.

render(self, value=None, format=`'html'`, **params)

source code

Exactly the same as display() but return serialized output instead.

Useful for debugging or to display the widget in a template other than Genshi or Kid, like Cheetah, Mako, Nevow Stan, ...

retrieve_javascript(self)

source code

Return the needed JavaScript resources.

Return a setlike instance containing all the JSLinks and JSSources the widget needs.

retrieve_css(self)

source code

Return the needed CSS resources.

Return a setlike instance with all the CSSLinks and CSSSources the widget needs.

setattr(self, key, value)

source code

x.__setattr__('name', value) <==> x.name = value

Overrides: object.__setattr__: (inherited documentation)

repr(self)
(Representation operator)

source code

repr(x)

Overrides: object.__repr__: (inherited documentation)

Property Details

is_named

Return True if the widget has overridden its default name.

Get Method:: unreachable.is_named(self) - Return True if the widget has overridden its default name.

Class Widget

__init__(self, *args, **kw) (Constructor)

update_params(self, params)

__call__(self, *args, **params) (Call operator)

display(self, value=None, **params)

render(self, value=None, format='html', **params)

retrieve_javascript(self)

retrieve_css(self)

__setattr__(self, key, value)

__repr__(self) (Representation operator)

is_named

init(self, *args, **kw)
(Constructor)

call(self, *args, **params)
(Call operator)

render(self, value=None, format=`'html'`, **params)

setattr(self, key, value)

repr(self)
(Representation operator)