Using the WidgetBrowser

WidgetBrowser installs a command line script to run an embedded server. To run it:

$ twbrowser

There are various command line options which can be used to control its behavior, twbrowser –help displays them:

Usage: twbrowser [OPTIONS] [widget_url]

 Options:
     -h, --help            show this help message and exit
     -i, --interactive
     -b, --browser
     -d DOCS, --docs=DOCS
     -p PORT, --port=PORT

Options summary

–help/-h

Display the help message and exit

–interactive/-i

Run the server in interfactive mode. When interactive mode is enabled an AJAX python interpreter is available to play with widgets. It is also possible to pass arguments to tw.api.Widget.display() and see how it affects display. If WebError is installed it will be integrated to easily debug any error a widget produces (or the WidgetBrowser itself).

Warning

This options is disabled by default because this mode allows remote code execution which poses a BIG security hole if it is exploited by the bad guys. USE AT YOUR OWN RISK!

–browser/-b

Opens a webbrowser when starting the app

–port/-p

The port where the app should be bound too

–docs/-d

The path to a Sphinx docs directory which should be built and served from / This is very useful to debug docs with the emebedded widegbrowser working.

The Terminal

The WidgetBrowser provides a helpful python interactive prompt when invoked with the -i or --interactive command-line flag. You can import widgets here, build them, instantiate them and display them. When a widget is displayed an overlay will appear with the live widget

Here’s a screen shot:

Using the WidgetBrowser as a widget development tool

The WidgetBrowser is a very useful tool during the development of Tosca widgets since it allows to rapidly view the live widgets whenever they’re rendered instead of the plain html markup you would see in the normal python interpreter you get in a shell. For best results install WebError for interactive debugging of any errors and launch the WidgetBrowser with paster in --reload mode.

Step by step

Prepare the dev environment first by installing the needed packages:

$ easy_install WidgetBrowser WebError PasteScript

Then create a paster.ini file which looks like this:

#
# Sample PasteDeploy ini file to launch the WidgetBrowser.
# 
# This is most useful while developing and debugging widgets since paster can autoreload the WidgetBrowser
# whenever any imported module's source is modified. To enable reloading do:
#
#   $ paster serve --reload paster.ini
#
# The %(here)s variable will be replaced with the parent directory of this file
#

[server:main]
use = egg:Paste#http
# Bind only to the loopback interface since we're starting in intercative mode.
host = 127.0.0.1
port = 8000

[app:main]
use = egg:WidgetBrowser
# Enable interactive mode so WebError (needs to be easy_installed first) and the Terminal are available
interactive = true

Finally, start the WidgetBrowser with paster:

$ paster serve --reload paster.ini

Notice the --reload switch. When enabled, paster will reload the WidgetBrowser whenever an imported module is changed so any modification done during incremental development is seen immediately (you will also need to reload the page in your browser, of course).

Warning

The interactive REPL session in the terminal will be lost whenever the WidgetBrowser is restarted. A future enhancement might provide the ability to save and load interactive sessions.