Fiddling with the Bundled Examples¶
The previous tutorials have shown how to develop various types of Tangelo applications, but you might also want to simply fiddle around with the example applications that come bundled with Tangelo. Since the bundled examples are treated in a somewhat special manner by Tangelo, this tutorial explains how you can make a copy of the example applications, set them up with a Tangelo configuration file, and then experiment and see the results yourself.
The examples can be viewed at http://localhost:8080 by launching Tangelo in example mode:
tangelo --examples
The index page contains links to different examples, each of which is served as the web content of one plugin or another. For example, http://localhost:8080/plugin/vis/examples/barchart/ serves an example of the barchart that is part of the vis plugin.
The Example Web Applications¶
The example web applications are bundled in the Tangelo Python package with the following directory structure:
tangelo.ico
web/
...
plugin/
...
The file tangelo.ico
is served by Tangelo statically as the default favicon,
while the web
directory contains the example site’s front page (including
the Tangelo Sunrise, and the menu of links to the individual examples). The
examples themselves are contained within the plugin
directory. As an
example, the directory for the Bokeh plugin looks like this:
plugin/
bokeh/
requirements.txt
python/
__init__.py
web/
bokeh.js
examples/
iris/
index.html
iris.py
This plugin contains a Python component and a clientside component, as well as
the Iris example application, which demonstrates how the pieces fit together
(for information about how plugins work, see Tangelo Plugins). The web
application content in the iris
directory would be a good place to play
around to discover for yourself how this plugin works.
Therefore, we will want to make a private copy of the web
and plugin
directories in order to experiment with the contents of the example web
applications.
Making a Copy¶
To actually play with the examples, we’d like to set up our own sandbox, copy these materials into it, configure Tangelo to run with the appropriate plugins, and finally serve our own version of the example applications.
Step 1: Create a Sandbox¶
The examples are bundled as package data with the Tangelo Python package,
meaning they will be found within the tangelo/pkgdata
subdirectory of the
site-packages
directory of the Python installation that contains Tangelo.
On a typical Linux Python installation, this directory might be
/usr/lib/python2.7/site-packages/tangelo/pkgdata
. Because different Python
setups may behave differently with respect to where such files are kept, Tangelo
includes a program tangelo-pkgdata
that simply reports the full path to the
pkgdata
directory. Using this program, the following sequence of shell
commands will create an area where we can safely modify and otherwise experiment
with the examples:
$ cd ~
$ mkdir tangelo-examples
$ cd tangelo-examples
$ cp -r `tangelo-pkgdata` .
(Enclosing a command in backticks causes the shell to run the enclosed program
and substitute its output in the original command. You can also run
tangelo-pkgdata
manually, inspect the output, and copy it into your own
manual shell command as well.)
Step 2: Configure the Plugins¶
We will want to have Tangelo serve the web
directory, while loading the
appropriate plugins from the plugin
directory. For the latter, we will need
a configuration file to declare the plugins:
This very simple configuration simply names the plugins we need, together with
relative paths stating where the plugins can be found. Create a file
config.yaml
(in the tangelo-examples
directory) and copy the
configuration into it.
Step 3: Launch Tangelo¶
Now that we have web materials, plugins, and a configuration, we just need to start Tangelo:
$ tangelo --root web --config config.yaml
Tangelo should begin serving the example site at http://localhost:8080 (if you
get an error about port 8080 not being free, try again with the --port
option to select a different port).
Step 4: Fiddle!¶
Now you can go into the various web
subdirectories of the plugin paths, make
changes, and observe them live. If you find things don’t update as expected,
you can try restarting the server (certain features of plugins can only be
instantiated when Tangelo first starts up).
Try changing the data values in the mapping plugin examples, or changing how some of the web services retrieve, process, or format their output data. With a safe, hands-on approach, you can learn a lot about how Tangelo operates.