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

Class Widget


 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

[hide private]

__metaclass__

Instance Methods

[hide private]

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

source code

__init__(self, *args, **kw)
All initialization has to take place in this method.

source code

__repr__(self)
repr(x)

source code

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

source code

_get_is_named(self)
Return True if the widget has overrided it's default name, else False.

source code

adjust_value(self, value, **params)
Adjusts 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 a setlike instance with all the CSSLinks and CSSSources the widget needs.

source code

retrieve_javascript(self)
Return a setlike instance with all the JSLinks and JSSources the widget needs.

source code

update_data(self, params)
This method will have the last chance to update the variables sent to the template for the specific request.

source code

update_params(self, params)
This method will have the last chance to update the variables sent to the template for the specific request.

source code

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

Class Variables

[hide private]

_locked = False

css = []

default = None

javascript = []

name = 'widget'

params = []

params_doc = {}

template = None

template_vars = []

Properties

[hide private]

is_named

Inherited from object: __class__

Method Details

[hide private]

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


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 inhertitting 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, ...

update_data(self, params)

source code

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.

update_params(self, params)

source code

*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

[hide private]

is_named

Get Method:: _get_is_named(self) - Return True if the widget has overrided it's default name, else False.

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)

update_data(self, params)

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)