Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Changes between Version 4 and Version 5 of WidgetPackages


Ignore:
Timestamp:
03/08/08 10:36:32 (11 years ago)
Author:
Chris Arndt
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WidgetPackages

    v4 v5  
    1 This information mostly comes from KevinDangoor's devcast at http://www.turbogears.org/docs/devcasts.html. 
     1{{{ 
    22 
    3 Most widgets use resources to control various aspects of themselves. For example, in Turbogears widget library (the files in source:/trunk/turbogears/widgets) there is a widget named CalendarDatePicker that display a Javascript calendar. The widget uses the following resource files: 
     3#!rst 
    44 
    5  * The CSS file source:/trunk/turbogears/widgets/static/calendar/calendar-system.css 
    6  * The Javascript file source:/trunk/turbogears/widgets/static/calendar/calendar.js 
    7  * The Javascript file source:/trunk/turbogears/widgets/static/calendar/calendar-setup.js 
    8  * Plus some more locale-specific Javascript files located in source:/trunk/turbogears/widgets/static/calendar/lang 
    9   
    10 The DataGrid widget uses: 
    11  
    12  * The CSS file source:/trunk/turbogears/widgets/static/grid.css 
    13  * The KID template source:/trunk/turbogears/widgets/templates/datagrid.kid 
    14  
    15 When you build your own widgets it is likely that you will also need to use resource files. You specify which resource files your widget require by using the attributes `css`, `javascript` and `template` in your widget class. 
    16  
    17 {{{ 
    18 #!python 
    19  
    20 from turbogears.widgets import \ 
    21     CSSLink, JSLink, Widget 
    22  
    23 class ComboBox(Widget): 
    24     css = CSSLink("package.name", "combo.css") 
    25     javascript = [mochikit, JSLink("package.name", "combo.js")] 
    26     template = "package.name.templates.combo" 
     5.. note:: This page has been migrated to http://docs.turbogears.org/1.0/WidgetPackages 
    276}}} 
    287 
    29 Note that you do not retrieve resource files using a normal file path, instead you use TurboGears packaging system, which is an abstraction on top of a regular file system. Its usefulness comes from being able to specify an url by using   a package name plus a filename and not have to bother with where exactly the file is mounted on your web server. It can also be confusing because the file has three "locations" - the path on your disk, the mounted path on your web server and the name of the package it belongs to. 
    30  
    31 In this example, the ComboBox widget requests the three files `combo.css`, `combo.js` and `combo.kid`. `package.name` is the name of the package where you have put your resource files. You must first create a package by registering it. Say that you have a normal directory tree for your project looking like this: 
    32  
    33  * projname/ 
    34    * static/ 
    35      * css/ 
    36      * images/ 
    37      * javascript/ 
    38    * templates/ 
    39    * test/ 
    40  * projname.egg-info 
    41       
    42 Lets also say that you want to package the stuff inside the static directory. One way to do it would be to make three packages: `foobar.css` for the stylesheets, `foobar.javascript` for the javascripts and `foobar.images` for the images. You accomplish that by first obtaining a filename for a resource and then registering it as a directory. Write this in your `controllers.py` file: 
    43  
    44 {{{ 
    45 #!python 
    46 import os.path 
    47 import pkg_resources 
    48  
    49 pkg_path = pkg_resources.resource_filename(__name__, os.path.join("static", "javascript")) 
    50 register_static_directory("foobar.javascript", pkg_path) 
    51 pkg_path = pkg_resources.resource_filename(__name__, os.path.join("static", "css")) 
    52 register_static_directory("foobar.css", pkg_path) 
    53 pkg_path = pkg_resources.resource_filename(__name__, os.path.join("static", "images")) 
    54 register_static_directory("foobar.images", pkg_path) 
    55 }}} 
    56  
    57 (see http://peak.telecommunity.com/DevCenter/PkgResources for information on pkg_resources work) Now you can fetch resource files using your packages. 
    58  
    59 {{{ 
    60 #!python 
    61  
    62 l = CSSLink("foobar.css", "combo.css") 
    63 js = JSLink("foobar.javascript", "foobar.js") 
    64  
    65 }}} 
    66  
    67 You can also browse your package by going to the url localhost:8080/tg_widgets/foobar.javascript/.  
    68  
    69 ''pkg_resources probably also contain heaps more useful functionality and it would be good if someone who knows about can write it down here.''