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  : Kid template for the widget.
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 overrided it's
            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 it's bases. Can be used as a quick reminder of all
            the params your widget has at it's 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, overriden 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 sublcassing 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 overrided by passing them as keyword args to
   display(). This will only affect that display() 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

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

source code

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

source code

__repr__(self)
repr(x)

source code

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

source code

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

source code

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

source code

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

retrieve_css(self)
Return the needed CSS ressources.

source code

retrieve_javascript(self)
Return the needed JavaScript ressources.

source code

update_params(self, params)
Update the template parameters.

source code

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

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

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

Method Details

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

source code

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

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, your 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 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"
default  : Default value to display when no value is passed at display
           time.
**params : Keyword arguments specific to your widget or to any of it's
           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__

repr(self)
(Representation operator)

source code

repr(x)

Overrides: object.__repr__: (inherited documentation)

setattr(self, key, value)

source code

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

Overrides: object.__setattr__: (inherited documentation)

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

source code

Display the widget in a Kid template.

Returns an elementtree node instance. 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 non-Kid template like Cheetah, STAN, ...

retrieve_css(self)

source code

Return the needed CSS ressources.

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

retrieve_javascript(self)

source code

Return the needed JavaScript ressources.

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

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.

Property Details

is_named

Return True if the widget has overridden its default name.

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

Class Widget

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

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

__repr__(self) (Representation operator)

__setattr__(self, key, value)

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

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

retrieve_css(self)

retrieve_javascript(self)

update_params(self, params)

is_named

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

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

repr(self)
(Representation operator)

setattr(self, key, value)

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