EasyInterface: A toolkit for rapid development of GUIs for research prototype tools

TL;DR

EasyInterface is an open-source toolkit that enables researchers to quickly create web-based GUIs for their research prototypes without extensive web programming knowledge.

Contribution

It introduces a simple, text-based language and toolkit for rapid development of GUIs for command-line tools, facilitating integration and accessibility.

Findings

Enables GUI creation in minutes for command-line tools

Supports sophisticated GUI features like syntax highlighting and dialogs

Facilitates integration of research prototypes into common environments

Abstract

In this paper we describe EasyInterface, an open-source toolkit for rapid development of web-based graphical user interfaces (GUIs). This toolkit addresses the need of researchers to make their research prototype tools available to the community, and integrating them in a common environment, rapidly and without being familiar with web programming or GUI libraries in general. If a tool can be executed from a command-line and its output goes to the standard output, then in few minutes one can make it accessible via a web-interface or within Eclipse. Moreover, the toolkit defines a text-based language that can be used to get more sophisticated GUIs, e.g., syntax highlighting, dialog boxes, user interactions, etc. EasyInterface was originally developed for building a common frontend for tools developed in the Envisage project.

Full text

1 Introduction

During the lifetime of a research project, research prototype tools are often developed which share many common aspects. For example, in the Envisage [4] project, we developed various tools for processing ABS programs: static analyzers, compilers, simulators, etc. Both as individual researchers and as groups, we often develop several related tools over time to pursue a specific line of research.

Providing the community with easy access to research prototype tools is crucial to promote the research, get feedback, and increase the tools’ lifetime beyond the duration of a specific project. This can be achieved by building GUIs that facilitate trying tools; in particular, tools with web-interfaces can be tried without the overhead of first downloading and installing the tools.

In practice, we typically avoid developing GUIs until tools are fairly stable. Since prototype tools change continuously, in particular during a research project, they will often not be available to the community during early development. Both programming plug-ins for sophisticated frameworks such as Eclipse Scout and building simpler GUIs from scratch are tedious tasks, in particular for web-interfaces. It typically gets low priority when developing a research prototype. Often we opt for copying the GUI of one tool and modifying it to fit the needs of a new related tool. Apart from code duplication, these tools will “live” separately, although we might benefit from having them in a common GUI.

EasyInterface is a toolkit that aims at simplifying the process of building and maintaining GUIs for (but not limited to) research prototype tools. Avoiding complex programming, it provides an easy, declarative way to make existing (command-line) tools available via different environments such as a web-interface, within Eclipse, etc. It also defines a text-based output language that can be used to improve the way results are presented to the user without requiring any particular knowledge of GUI/Web programming; e.g., if the output of a tool is (a structured version of) “highlight line number 10 of file ex.c” and “when the user clicks on line 10, open a dialog box with the text …”, the web-interface will interpret this and convert it to corresponding visual effects. An advantage of using such an output language is that it will be understood by all the frontend environments of EasyInterface, e.g., the web-interface and the Eclipse plug-in (which is still under development). EasyInterface is open source and available at http://github.com/abstools/easyinterface. A more detailed descreption on how to use EasyInterface is availale in Appendix A, and in the user manual [3]. An online demo is available at https://youtu.be/YE7YwR2duzk.

2 General Overview

The overall architecture of EasyInterface is depicted in Fig. 1. Its two main components are

(i) server side: a machine with several tools (the circles Tool1, etc.) executable from the command-line, and with output going to the standard output. These are the tools that we want to make available for the outside world; and

(ii) client side: several clients that communicate with the server to execute a tool. Tools may run on the server machine or on other machines; e.g., the web-interface can be installed as a web-page on the server, and accessed from anywhere with a web browser.

Clients can connect to several servers simultaneously.

The server side addresses the problem of providing a uniform way to remotely execute locally installed tools. This problem is solved by the server, which consists of PHP programs (on top of an HTTP server). The server supports declarative specifications of how local tools can be executed and which parameters they take, using simple configuration files. For example, the following XML snippet is a configuration file for a tool called "myapp".

⬇

<app id="myapp" visible="true">

** **...

** <execinfo method="cmdline"****>**

** **<cmdlineapp>

** /path-to/myapp **** 

_

ei_parameters**

** **</cmdlineapp>

** **</execinfo>

** <parameters prefix = "-" check="false"****>**

** **...

** <selectone name="c"****>**

** <option value="1"**** **/>

** <option value="2"**** **/>

** **</selectone>

** **</parameters>

</app>

The cmdlineapp tag is a template describing how to execute the tool from the command-line. The template parameter ** 

_

ei_parameters** is replaced by an appropriate value before execution. The server also supports template parameters for, e.g., passing files, temporal working directories, session identifiers, etc. The parameters tag includes a list of parameters accepted by the tool. For example, the parameter ‘‘c’’ above takes one of the values $1$ or $2$.

Once the configuration file is installed on the server, we can access the tool using an HTTP POST request that includes JSON-formatted data like the following one

⬇

{

** **command: "execute",

** **app_id: "myapp",

** parameters: **{

** **c: ["1"],

** **...

** **},

** **...

}

When receiving such a request, the server generates a shell command according to the specification in the configuration file (e.g., ‘‘/path-to/myapp -c 1’’), executes it and redirects the standard output to the client. The server also supports

(i) tools that generate output in the background, we let clients fetch output (partially) when it is ready; and

(ii) tools that generate files, we let clients download them later when needed.

In all cases, the server can* restrict the resources * available to a tool (e.g., the processing time), and guarantees the safety of the generated command; i.e., clients cannot manipulate the server to execute other programs installed on the server. In addition to tools, the server can include example files, so users can easily try the tools.

EasyInterface not only makes the server side execution of a tool easy, it provides client side GUIs that

(1) connect to the server and ask for available tools;

(2) let users select the tool to execute, set its parameters and provide a source program;

(3) generate and send a request to the server; and

(4) display the returned output.

EasyInterface provides three generic clients: a web-interface similar to an IDE; an Eclipse IDE plug-in; and a remote command-line shell. The last two clients are under development, so we focus here on the web-interface.

The web-interface, shown in Fig. 2, is designed like an IDE where users can edit programs, etc. Next to the Run button there is a drop-down menu with all available tools obtained from the associated servers. In the settings window, the user can select values for the different parameters of each tool. These parameters are specified in the corresponding configuration files on the server side, and automatically converted to combo-boxes, etc., by the web-interface. When the user clicks the Run button, the web-interface sends a request to the associated server to execute the selected tool and prints the received output back in the console area of the web-interface.

Since the web-interface and Eclipse plug-in are GUI based clients, EasyInterface allows tools to generate output with some graphical effects, such as opening dialog-boxes, highlighting code lines, adding markers, etc. To use this feature, tools must support the EasyInterface output language, as in the following XML snippet

⬇

<highlightlines dest="/path-to/sum.c">

** <lines> <line from="5"**** to="10"/>**** **</lines>

</highlightlines>

...

<oncodelineclick dest="/path-to/sum.c" outclass="info">

** <lines><line from="17"**** **/></lines>

** **<eicommands>

** <dialogbox boxtitle="Hey!"****>**

** <content format="text"****>some message</content>**

** **</dialogbox>

** **</eicommands>

</oncodelineclick>

The tag highlightlines indicates that Lines 5--10 of file /path-to/sum.c should be highlighted. The tag oncodelineclick indicates that when clicking on Line $17$, a dialog-box with a corresponding message should be opened. Note that a tool is only modified once to produce such output, with similar effect in all EasyInterface clients (including future ones).

3 Concluding Remarks

EasyInterface is a toolkit for the rapid development of GUIs for command-line research prototype tools. The toolkit has been successfully used in the Envisage project to integrate the tools from the different partners in a common web-based environment, including parsers, type-checkers, compilers, simulators, deadlock and worst-case cost analyzers, and a systematic testing framework (see http://abs-models.org). Our experience suggests that the methodology implied by EasyInterface for building GUIs is adequate for research prototype tools; as such tools change continuously, the corresponding GUIs can be modified immediately and with negligible effort. Future work includes plans to develop more clients, and libraries for different programming languages to facilitate generation of the output commands/actions instead of printing these directly.

Appendix A Using EasyInterface

In this appendix we describe the methodology that EasyInterface implies for its users by explaining the basics of its different parts and the way they are supposed to be used. In Sec. A.1 we describe the different options that are provided by the EasyInterface server, in Sec. A.2 we review the different features of the web-interface, and in Sec. A.3 we discuss the EasyInterface output language. Note that the installation of EasyInterface is practically immediate: It only consists in cloning the github repository and making its root directory accessible via an HTTP server. Thus, we omit the installation details here and refer the reader to the installation guide that is available in the github repository for further information.

A.1 Adding Tools and Examples to the Server

As described in Sec. 2, adding a tool to the server is simply done by providing a configuration file such as the one in Sec. 2. This file includes two main components: (1) the command-line template that describes how to execute the corresponding tool; and (2) the parameter section that describes which command-line parameters the tool will take.

EasyInterface supports several types of parameters such as a parameter with a single value, a parameter with multiple values, a Boolean parameter, etc. Each parameter has a name, a set of valid values, and a set of default values. When receiving a request to execute a tool (such as the JSON-formatted data in Sec. 2), the server generates a sequence of command-line parameters from those specified in the request and replaces the template parameter ** 

_

ei_parameters** by this list. For example, if there is a parameter named ‘‘c’’ and its provided value is ‘‘1’’, then what is passed to the tool is ‘‘-c 1’’. The prefix ‘‘-’’ that is attached to the parameter name can be specified using the prefix attribute in the parameters section. In addition, the check attribute indicates if the server should reject requests with invalid parameter values. Apart from ** 

_

ei_parameters** the command-line template might include other template parameters, all are first replaced by corresponding values and then the resulting shell command is executed and its output is redirected back to the client. Next we describe some of the available template parameters:

\defaultleftmargin

1em

• •

** 

_

ei_files**: tools typically receive input files (e.g., programs or models) to process. The execution request (i.e., the JSON-formatted data of Sec. 2) can include such files, and, in order to pass them to the corresponding tool, the server first saves them locally in a temporary directory and replaces ** 

_

ei_files** by a list of corresponding local paths.

• •

** 

_

ei_outline**: since EasyInterface was first developed for tools that process programs (e.g., program analysis tools), the execution request can include so-called outline entities. These are elements of the input programs such as method names, class names, etc., and they are used to, e.g., indicate from where the tool should start the analysis. The server replaces ** 

_

ei_outline** by the list of the provided outline entities.

• •

** 

_

ei_execid**: this corresponds to a unique execution identifier that is assigned (by the server) to the current execution request, which can be used for future references to this execution as discussed below.

• •

** 

_

ei_stream**: there are tools that do not generate output immediately, such as simulators. In this case we would like to keep the tools running in the background and fetch their output periodically without maintaining the current connection to the server. The template parameter ** 

_

ei_stream** corresponds to a temporary directory where the tool can write its output and where clients can fetch this output by corresponding requests to the server. These requests should include the corresponding execution identifier. For example, the tool could output the following command (in the EasyInterface output language) and terminate, while keeping a process running in the background (complying with the server’s permissions) writing its output chunks to the ** 

_

ei_stream** directory:

⬇

<content format="text" execid="EI65231" time="60sec">>

** The program is running in the background,**

** the output goes here **...

</content>

This command indicates that the output, in text format, should be fetched every 60 seconds using the execution identifier specified in execid. Note that it is the responsibility of the client (e.g., the web-interface) to fetch the output once it receives the above command.

• •

** 

_

ei_download**: some tools generate output in the form of large files, e.g., compiled code. Instead of redirecting this output directly to the client it can be more convenient to return download links. This template parameter corresponds to a temporary directory where such files can be stored and later fetched by sending a special request to the server with the file name and the corresponding execution identifier, similar to the stream mode above. The EasyInterface output language includes a special command for downloading such files:

⬇

**<download execid="EI65231" filename="file.zip" **/>

Once the client (e.g., the web-interface) receives this command, it sends a request to download the file file.zip that is associated with the execution identifier ‘‘EI65231’’. The command can also be assigned to an ‘‘on click’’ action instead of downloading it immediately (see Sec. A.3).

• •

** 

_

ei_sessionid**: this corresponds to a unique session identifier that is assigned to the user, and can be used to track the user’s activity among several requests. It is implemented using PHP sessions.

• •

** 

_

ei_clientid**: this corresponds to the client identifier, e.g., webclient, eclipse, etc. It can be used to generate client directed output which uses the EasyInterface output language for the selected clients and plain text for others.

The server configuration files also include options for controlling security issues, timeout for tools, etc.

In addition to the tools, one can install example sets on the server side, which are meant to be used by clients (e.g., the web-interface) to provide users with some examples on which they can apply the available tools. Adding example sets is done via configuration files such as the following:

⬇

<examples>

** <exset id="iter"****>**

** <folder name="Examples_1"****>**

** <folder name="iterative"****>**

** <file name="sum.c"**** url="https://.../sum.c" **/>

** **...

** **</folder>

** **...

** **</folder>

** **</exset>

** <exset id="set2"****>**

** <folder name="Examples_2"****>**

** <github owner="username"**** repo="examples" branch="master" path="benchmarks"/>**

** **</folder>

</exset>

</examples>

This defines two sets of examples. The first uses a directory structure, while the second refers to a github repository. Note that in the first case the example files are not necessarily installed on the server; a link must be provided for each file.

A.2 Using the Web-Interface Client

The web-interface client of EasyInterface is a JavaScript program that runs in a web browser, a screenshot is depicted in Fig. 2. It uses JQuery [5] as well as some other libraries like JSTree [6] and CodeMirror [1]. It is designed like an IDE, this is because EasyInterface was first developed for integrating the tools of the Envisage [4] project (static analyzers, simulators, etc.) in a common GUI. It includes the following components:

(1) the code editor, where users can edit programs;

(2) the file-manager that contains a list of predefined examples and user files;

(3) the outline view that includes an outline (e.g., methods and classes) of one or more files;

(4) the console where the results of executing a tool is printed by default; and

(5) the tool bar that includes several buttons to execute a tool, etc.

Next we describe the workflow, and give more details on these components.

The Workflow. The workflow within the web-interface is as follows:

(a) write a new program or open an existing one from the file-manager;

(b) click on the Refresh Outline button to generate the outline of the currently open program, and select some entities from this outline;

(c) select a tool from the tools menu; and

(d) click on the Settings button to set the values of the different parameters;

(e) click on the Run button to execute the selected tool.

At this point the web-interface sends a request to the corresponding server to execute the selected tool (passing the currently opened file, parameter values, selected outline entities, etc. to the tool), and the output is returned and printed in the console area of the web-interface. If the tool’s output is in the EasyInterface output language, then it passes through an interpreter that converts it to some corresponding graphical output. The user can apply a tool (and generate an outline) on several files by selecting the corresponding option from the context menu in the file-manager (opened with a right click on an entry in the file-manager).

Code Editor. The code editor is based on CodeMirror [1], it can be easily configured to use syntax-highlighting for different languages.

Tools Menu. The tools menu includes a list of tools that can be executed by the user. This list can be set in the web-interface configuration file, simply by providing the URLs of the corresponding EasyInterface servers and, for each, indicating if all available tools should be included or only some selected ones. The default configuration of the web-interfaces fetches all tools that are installed on the server running on the machine where the web-interface is installed.

Settings. When clicking the Settings button, a settings window is opened where the user can choose values for the different parameters of the different tools (see the top part of Fig. 2). This is automatically generated using the parameters defined in the server configuration file (the web-interface fetches this information from the corresponding server).

File-Manager. The predefined examples included in the file-manager can be set in the web-interface configuration file by providing the URLs of the corresponding EasyInterface servers and identifiers for the example sets to be included. As we have seen in Sec. 2, such a set can simply be given as a reference to a github repository. The file-manager can also allow users to create their own files, upload files from local storage, and clone public and private github repositories.

Outline. The Outline area is supposed to include an outline of some of the program files (available in the file-manager), and thus depends on the structure of those programs. For example, in the case of the Envisage [4] project it includes elements (methods, classes, etc.) of ABS programs. Using it for Java programs, for example, would require changing the way the outline is generated. EasyInterface already provides an easy way to change the outline generator. All we have to do is

(1) to provide a tool (installed on an EasyInterface server, like any other tool) that takes a set of files and generates an XML structure that represents an outline, the web-interface will convert this XML to a tree-view; and

(2) to modify the web-interface configuration file in order to use this tool for generating the outline.

A.3 Using The Output Language

The EasyInterface output language is a text-based language that allows tools to generate more sophisticated output. It is supported in both the web-interface and Eclipse clients. In this section we will explain the basics of this language by example. An output in the EasyInterface output language is an XML of the following form:

⬇

<eiout>

** **<eicommands>

** [EICOMMAND]***

** **</eicommands>

** **<eiactions>

** [EIACTION]***

** **</eiactions>

</eiout>

where [EICOMMAND]* is a list of commands to be executed; and [EIACTION]* is a list of actions to be declared. An [EICOMMAND] is an instruction like: print a text on the console, highlight lines 5-10, etc. An [EIACTION] is an instruction like: when the user clicks on line 13, highlight lines 20-25, etc. In the rest of this section we consider some representative commands and actions.

Printing in the Console. Recall that when the EasyInterface output language is used, the web-interface does not redirect the output to the console area and thus we need a command to print in the console area. The following is an example of a command that prints ‘‘Hello World’’ in the console area:

⬇

<printonconsole consoleid="1" consoletitle="Welcome">

** <content format="text"****>Hello World</content>**

</printonconsole>

The value of the consoleid attribute is the console identifier in which the given text should be printed (e.g., in the web-interface the console area has several tabs, so the identifier refers to one of those tabs). If a console with the provided identifier does not exist yet, a new one is created, with a title as specified in consoletitle. If consoleid is not given the output goes to the default console. Inside printonconsole we can have several content tags which include the content to be printed. The attribute format indicates the format of the content. In the above example it is plain text, other formats are supported as well, e.g., html, svg, and graphs. The graphs option refers to diagrams that are drawn using DyGraphs [2], where the data is provided inside the content tag using a JSON based format.

Adding Markers. The following is an example of a command that adds a marker next to a code line in the editor area:

⬇

<addmarker dest="path" outclass="info">

** <lines> <line from="4"**** /> **</lines>

** <content format=’text’> some associated text **</content>

</addmarker>

The attribute dest indicates the full path of the file in which the marker should be added. The attribute outclass indicates the nature of the marker, which can be info, error, or warning. This value typically affects the type/color of the icon to be used for the marker. The tag lines includes the lines in which markers should be added, each line is given using the tag line where the from attribute is the line number (line can be used to define a region in other commands, this is why the attribute is called from). The text inside the content tag is associated to the marker (as a tooltip, a dialog box, etc., depending on the client).

Highlighting Code Lines. The following command can be used to highlight code lines:

⬇

**<highlightlines dest="path" outclass="info" **>

** <lines> <line from="5"**** to="10"/>**** **</lines>

</highlightlines>

Attributes dest and outclass are as in the addmarker command. Each line tag defines a region to be highlighted. In the example above, lines 5--10 get highlighted. We can also use the attributes fromch and toch to indicate the columns in which the highlight starts and ends respectively.

Opening a Dialog Box. The following command can be used to open a dialog box with some content:

⬇

<dialogbox outclass="info" boxtitle="Some Title!" boxwidth="100" boxheight="100">

** <content format="html"> some associated text **</content>

</dialogbox>

The dialog box will be titled as specified in boxtitle and it will include the content as specified in the content environments.

CodeLine Actions. A CodeLine action defines a list of commands to be executed when the user clicks on a line of code (more precisely, on a marker placed next to the line). The commands can be any of those seen above. The following is an example of such an action:

⬇

**<oncodelineclick dest="path" outclass="info" **>

** <lines> <line from="17"**** /> **</lines>

** **<eicommands>

** **<highlightlines>

** <lines> <line from="17"**** to="19"/>**** **</lines>

** **</highlightlines>

** <dialogbox boxtitle="Hey!"****>**

** <content format="html"> some text **</content>

** **</dialogbox>

** **</eicommands>

</oncodelineclick>

First note that the XML description above should be placed inside the eiactions tag. When the above action is executed, e.g., by the web-interface client, a marker will be shown next to line 17 of the file specified in the attribute dest. If the user clicks on this marker the commands inside the eicommands tag will be executed, and if the user clicks again the effect of these commands is undone. In the case above, a click highlights lines 17--19 and opens a dialog box, and another click removes the highlights and closes the dialog box.

OnClick Actions. OnClick actions are similar to CodeLine actions. The difference is that instead of being assigned to a line of code, they are assigned to an HTML tag that we have previously generated. Let us suppose that the tool has already generated the following content in the console area:

⬇

<content format="html"/>

** <span style="color: red;"**** id="err1">10**** errors</span>**** were found in sum.**c

</content>

Note that the text ‘‘10 errors’’ is wrapped by a span tag with an identifier err1. The OnClick action can assign a list of commands to a click on this text as follows:

⬇

<onclick>

** <elements> <selector value="#err1"/> **</elements>

** **<eicommands>

** <dialogbox boxtitle="Errors"****>**

** <content format="html"> some text **</content>

** **</dialogbox>

** **</eicommands>

</onclick>

The selectors used in the tag selector are as in JQuery [5].