Home       Trees       Indices       Help   
TurboGears
Package turbogears :: Package widgets :: Module base :: Class Widget

Class Widget

source code

object --+
         |
        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.
Instance Methods
 
__init__(self, name=None, template=None, default=None, **params)
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 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 ressources.		 source code
 
retrieve_css(self)
Return the needed CSS ressources.		 source code
 
is_named(self)
Return True if the widget has overridden its default name.		 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
  __metaclass__ = MetaWidget
  name = "widget"
  template = None
hash(x)
  default = None
hash(x)
  css = []
  javascript = []
  params = []
  params_doc = {}
Properties

Inherited from object: __class__

Method Details

__init__(self, name=None, template=None, default=None, **params)
(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__

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 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_javascript(self)

source code 

Return the needed JavaScript ressources.

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

retrieve_css(self)

source code 

Return the needed CSS ressources.

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)

   Home       Trees       Indices       Help   
TurboGears
Generated by Epydoc 3.0.1 on Fri Jul 19 17:17:56 2019 http://epydoc.sourceforge.net