.. _browser:

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 :meth:`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:

.. image:: ./terminal.png

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:

.. literalinclude:: ../paster.ini

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.