=======================
Using the web interface
=======================

The web interface is built using the Django_ web framework, and requires that
Django be installed (see :doc:`installation`).

Starting the web interface
==========================

Before using the web interface, you must have created a Sumatra project using
``smt init``.

To launch the web interface, in your project directory run::

    $ smtweb &

This will launch a simple web server that listens on port 8000, and will
automatically open a new tab in your browser at http://127.0.0.1:8000/. You can
specify the ``-n`` option which will disable automatic opening of the new tab::

    $ smtweb -n

If port 8000 is already in use, you can specify a different port with the ``-p``
option to ``smtweb``, e.g.::

    $ smtweb -p 8001

If you are using a single record store for multiple projects, you can run
:command:`smtweb` from anywhere and specify the location of the record store
on the command line, e.g.::

    $ smtweb ~/sumatra.db


List of projects
================

When you first start :command:`smtweb`, the first page you see is a list of
your projects.

.. figure:: /images/project_list.png
   :width: 100%
   :align: center

Click on the project name to see the records of your simulations/analyses in
that project.


List of records
===============

The list of records page contains a table with the following columns:

	- version control repository
	- label
	- tags
	- reason
	- outcome
	- duration
	- number of processes
	- date
	- time
	- executable name
	- executable version
	- main file
	- version
	- command line arguments

You can change which columns to display by clicking on **Settings**.

.. figure:: /images/settings_dialog.png  
 :width: 80%
 :align: center


Selecting records
-----------------

Each record is represented as one row in the table. The rows can be selected
by dragging the mouse over them. As soon as you start doing that, the header
of the table will be changed to contain actions you can perform with selected
records. Actions you can perform are:

	- set tags for the selected records
	- delete records
	- compare records

.. figure:: /images/selecting_rows.png  
 :width: 100%
 :align: center


Deleting records
----------------

When deleting records, you have the option of also deleting any data generated by
that simulation or analysis.

.. figure:: /images/delete_records.png  
 :width: 100%
 :align: center

Editing tags
------------

For the selected records you can specify additional tags, edit or remove them.


.. figure:: /images/set_tags.png  
 :width: 100%
 :align: center

Comparing records
-----------------

From the set of selected records you can choose any two to compare them.

.. figure:: /images/compare_records.png  
 :width: 100%
 :align: center

Reviewing your code
-------------------

You can see the contents of your main script file by clicking the corresponding
link in the table. It will be shown in the modal window which can be dragged
around.

**Important**: for now this works only for Git and Mercurial repositories.

.. figure:: /images/view_main_file.png  
 :width: 100%
 :align: center


Filtering the records
---------------------

You can filter the records by clicking on the 'tag' button or by using
the search form. This form contains the following items:

	- label
	- tags
	- reason
	- executable
	- repository
	- main file
	- date
	- interval of dates

.. figure:: /images/search_form.png  
 :width: 100%
 :align: center

Search by **variable name** allows filtering the records using the name of parameter. If for each new simulation you have different parameter set, this feature can be useful for narrowing the set of possible records.   


Accessing record details
========================

You can access the record detail by clicking the corresponding label name in the
main table. The record detail page contains the following sections:

	- general info
	- input files
	- output files
	- parameters
	- dependencies
	- platform information
	- stdout & stderr
	
.. figure:: /images/detail_view.png  
 :width: 100%
 :align: center
 

Finishing up
============

Don't forget to kill the webserver process (e.g. with ``fg``, ``Ctrl-C``) when you are
finished with it.


Launching computations from the web interface
=============================================

It is possible to run simulations/analyses from within the web interface.
Clicking on the "New record" button will bring up the following dialog:

.. figure:: /images/launch_computation1.png  
 :width: 20%
 :align: center

You can specify **label**, **reason**, **tag**, **main file**, **arguments**,
and **executable** there. **Main file** and **arguments**
are drop-down lists with the names of the files from the folder of the Sumatra
project. As soon as the file is picked from the list, you can see its
content. Moreover, the **argument** file is editable and any changes you
made can be saved from this web page. You can hide and open the content of the
files by clicking the corresponding links below the drop-down list.

.. figure:: /images/launch_computation2.png  
 :width: 100%
 :align: center

On clicking run, the computation is launched and a progress bar appears. On
succesful completion, a new record is added to the **list of records** page.

Customizing the web interface
-----------------------------

You can customize the web interface on a per-project basis by placing your own
`Django templates`_ in a "templates" subdirectory of the Sumatra ".smt" directory.
The templates you can customize are called "base.html", "record_list.html",
"show_file.html", "project_detail.html", "show_csv.html", "show_image.html",
"record_detail.html", "show_diff.html", "tag_list.html". The best way to proceed
is to copy the default template from "/path/to/sumatra/web/templates"
to "/path/to/myproject/.smt/templates" and then modify it.

.. _Django: https://www.djangoproject.com/
.. _`Django templates`: https://docs.djangoproject.com/en/1.4/topics/templates/