tgMochiKit

Using tgMochiKit as a Stand-alone Widget

This is usually done by letting TurboGears include the tgMochiKit widget on every page, so that other JavaScript code on the page can utilize the functions of the MochiKit library. You do this by setting the following in your application's main configuration:

tg.include_widgets = ['turbogears.mochikit']

Using tgMochiKit as a Resource for Another Widget

If a JavaScript-enabled widget relies on the MochiKit library it should declare the tgMochiKit widget as a resource by adding it to its javascript class attribute.

Here is a small sample widget that uses the MochiKit Logging module:

from turbogears import widgets, mochikit

class LoggingPanelLink(widget.Widget):
    template = """\
<a href="#" onclick="MochiKit.Logging.logger.debuggingBookmarklet();"
    >open logging pane</a>
"""
    javascript = [mochikit]

Using tgMochiKit in TG 1.0

TurboGears 1.0 ships with the released MochiKit version 1.3.1. But as this is pretty dated, the desire to use newer releases often arises.

To do that with tgMochiKit is simple:

1. Use tg.mochikit_suppress = True in your app.cfg to prevent the inclusion of the shipped MK.

2. In e.g. <yourpkg>.__init__.py include the following snippet:

   ### tgMochiKit
   
   import tgmochikit
   from turbogears.widgets import register_static_directory, Widget, JSLink
   
   tgmochikit.init(register_static_directory, version="1.4", xhtml=True)
   
   class TGMochiKit(Widget):
       def retrieve_javascript(self):
           jss = [JSLink("tgmochikit", path)
               for path in tgmochikit.get_paths()]
           return jss
   
   mochikit = TGMochiKit()
   
   ### tgMochiKit

3. in your app.cfg, put <yourpkg>.mochikit into the tg.include_widgets list.

Using tgMochiKit with ToscaWidgets

The mochikit widget provided by TurboGears is a classic TurboGears widget. If you want to use tgMochiKit with ToscaWidgets, you have to roll your own widgets for the MochiKit JavaScript files. Fortunately this is very easy:

1. Use tg.mochikit_suppress = True in your app.cfg to prevent the inclusion of the shipped MK.
2. Set toscawidgets.on = True in your app.cfg to enable ToscaWidgets.

3. In e.g. <yourpkg>.__init__.py include the following snippet:

   import tgmochikit
   from turbogears.widgets import register_static_directory
   from tw.api import JSLink, Widget
   
   tgmochikit.init(register_static_directory, version="1.4", packed=False)
   mochikit = [JSLink(link='/tg_widgets/tgmochikit/%s' % p)
         for p in tgmochikit.get_paths()]

You can then use <yourpkg>.mochikit as a resource for other tw widgets, e.g:

class MyWidget(Widget):
    ...
    javascript = [some_other_resource] + mochikit

Chosing the right version

Now when using tgMochiKit, the problem of which version to chose arises.

If you want 1.3.1, just configure that as version to chose.

If you want a specific version that is shipped, configure that. This is the safe course of action for you application, because by this you ensure that even if you install newer versions of tgMochiKit (which might happen due to TurboGears upgrades), you will end up with code you verified that it works.

The trunk-version is something special. In the shipped tgMochiKit it will always be equal to the latest 1.4 version.

However, if you want the latest from trunk, you can simply

• check out tgMochiKit. This will fetch the latest from trunk into the distribution
• create your own tgMochiKit.egg, and use that for your application.

The version actually used by tgMochiKit based on your configuration is by the way logged on the logger tgmochikit with level INFO with the text:

Version chosen: <version>

Requirements

tgMochiKit relies on the TurboGears widget framework to be useful and is only properly initialised when you use TurboGears 1.1.

To make it work with TurboGears 1.0, see Using tgMochiKit in TG 1.0.