Skip to content

Web interface


Web interface

TF contains a web interface in which you can enter a search template and view the results.

This is realized by a web app based on Flask.

This web app connects to the TF kernel and merges the retrieved data into a set of templates.

See the code in web.

Start up

Start up

TF kernel, web server and browser page are started up by means of a script called text-fabric, which will be installed in an executable directory by the pip installer.

What the script does is the same as:

python3 -m tf.server.start
Process management

During start up the following happens:

Kill previous processes

The system is searched for non-terminated incarnations of the processes it wants to start up. If they are encountered, they will be killed, so that they cannot prevent a successful start up.

TF kernel

A TF kernel is started. This process loads the bulk of the TF data, so it can take a while. When it has loaded the data, it sends out a message that loading is done, which is picked up by the script.

TF web server

A short while after receiving the "data loading done" message, the TF web server is started.

Debug mode

If you have passed -d to the text-fabric script, the Flask web server will be started in debug and reload mode. That means that if you modify or a module it imports, the web server will reload itself automatically. When you refresh the browser you see the changes. If you have changed templates, the css, or the javascript, you should do a "refresh from origin".

Load web page

After a short while, the default web browser will be started with a url and port at which the web server will listen. You see your browser being started up and the TF page being loaded.


The script now waits till the web server is finished. You finish it by pressing Ctrl-C, and if you have used the -d flag, you have to press it twice.

Terminate the TF kernel

At this point, the text-fabric script will terminate the TF kernel.

Clean up

Now all processes that have started up have been killed.

If something went wrong in this sequence, chances are that a process keeps running. It will be terminated next time you call the text-fabric.

You can kill too

If you run

text-fabric -k

all tf-browser-related processes will be killed.

text-fabric -k ddd

will kill all such processes as far as they are for data source ddd.



There are 4 kinds of routes in the web app:

url pattern effect
/server/static/... serves a static file from the server-wide static folder
/data/static/... serves a static file from the app specific static folder
/local/static/... serves a static file from a local directory specified by the app
anything else submits the form with user data and return the processed request



There are two templates in views :

  • index: the normal template for returning responses to user requests;
  • export: the template used for exporting results; it has printer/PDF-friendly formatting: good page breaks. Pretty displays always occur on a page by their own. It has very few user interaction controls. When saved as PDF from the browser, it is a neat record of work done, with DOI links to the corpus and to Text-Fabric.



We format the web pages with CSS, with extensive use of flexbox.

There are several sources of CSS formatting:

  • the CSS loaded from the app dependent extraApi, used for pretty displays;
  • index.css: the formatting of the index web page with which the user interacts;
  • export.css the formatting of the export page;
  • base.css shared formatting between the index and export pages.



We use a modest amount of Javascript on top of JQuery.

For collapsing and expanding elements we use the details element. This is a convenient, Javascript-free way to manage collapsing. Unfortunately it is not supported by the Microsoft browsers, not even Edge.

On Windows?

Windows users should install Chrome of Firefox.