[[PageOutline]]

= Web interface =
The web based interface has many benefits and implements additional functionality. The main features of the web interface:

* The ability to run semantic queries - both global queries and queries starting with @ are supported
* The query construct assistant
* The query storage and the visualisation of the query result
* Possibility to see running queries and abort them if necessary
* Database operations
* Ability to mark files with error forms
* Dependency examinations


!JavaScript must be enabled in the browser to be able to use the interface!

= Installation =
To be able to use the web based interface we need to have an already working Yaws webserver. Required version is 1.89. Help for the installation: http://yaws.hyber.org/yaws.pdf (Chapter 2).


= Start up =
We can start the interface either with {{{referl}}} script with {{{-nitrogen}}} switch, or from !RefactorErl shell. In both cases we get a default configuration with server name {{{localhost}}}, port {{{8001}}}, and IP {{{127.0.0.1.}}}

== Starting up with referl script ==
Parameters to be configured:

* {{{-yaws path YPATH:}}} The absolute location of your Yaws ebin directory.
* {{{-yaws listen YLISTEN:}}} Valid IP address, which Yaws will listen to.
* {{{-yaws name YNAME:}}} Valid domain name, which Yaws will be bound to.
* {{{-yaws port YPORT:}}} Valid port number, which Yaws will be bound to.
* {{{-browser root BROOT:}}} The web interface allows database operations. The root directory for those operations can be set with this parameter.
* {{{-images dir IDIR:}}} Path of the directory where the generated images (visualisation of dependency examinations) will be written.

Usage of switches is optional, except the {{{-nitrogen}}} switch.


Example:
 {{{
  bin/referl -nitrogen 
             -yaws_path /Users/V/yaws-1.89/ebin 
             -yaws_listen 127.0.0.1
             -yaws_port 8000
             -yaws_name localhost
             -browser_root /Users/V/erlang
             -images_dir /Users/V/graph_images
 }}}

== Starting up from !RefactorErl shell ==
We have 2 functions for starting the interface : {{{ri:start_nitrogen/0}}} and {{{ri:start_nitrogen/1}}}. The 0 arity function starts up the interface with default configuration. The 1 arity function allows the interface to be configured using a prop-list. Available properties are the same as described in the previous section. Usage of switches is optional.
Example:
 {{{
ri:start_nitrogen([
    {yaws_path,"/Users/V/yaws-1.89/ebin"},
    {yaws_listen,"127.0.0.1"},
    {yaws_name, localhost},
    {yaws_port,"8000"},
    {browser_root,"/Users/V/erlang"},
    {images_dir,"/Users/V/graph_images"}]).
}}}


= Shutting down =
It is important to log out before shutting down the interface, because the log out process will delete the dynamicly generated images, which belong to the user. If the interface was started from !RefactorErl shell, then {{{ri:stop_nitrogen().}}} can be called to shut down the interface.


= Logging in =
To log in one must open a browser (recommended: Mozilla Firefox, Google Chrome) and enter the URL defined by the configuration (the default is {{{http://localhost:8001/}}}) after the web server had been started. Usage of services are allowed only to authorized people. First, you have to log in with a username (passwords are not supported yet). The browser will be redirected to the {{{queries}}} page.


= Database operations and environmental nodes =
This service is available under the ”Files” menu. The service only works correctly if the process has the appropriate rights for files and directories. The file browser panel is located at the left side of the page. You can either browse files which are located on the server (”Browse server”), or which had been loaded into the database (”Browse loaded files”). You can switch between these two options from the drop-down located at the top of the browser.

== Browsing files on the server ==
The root directory of the browser is an optional configuration parameter. Possible values are:

* If the {{{browser_root}}} parameter is set during start up, the given value is the root directory.
* If the {{{browser_root}}} parameter is not set during start up, but the database had contained files before start up, the root elements are the directories of these files.
* If the {{{browser_root}}} parameter is not set during start up, and the database had not contained files before start up, then !RefactorErl’s lib directory will be the root directory.

In this mode, directories can be listed, the contents of files can be shown, and a selected directory or file can be added to the database. The selected directory or file is shown by a blue background. Status messages are displayed during an addition to the database, and also after the process has finished.

== Browsing loaded files ==
In this mode directories can be listed, contents files can be shown, a selected file or directory can be reloaded to the database, dropped from the database, or can be pre-generated for the sourcecode-viewer. Status messages are displayed during the reloading/dropping/generating process, and also after the process has finished.

Dropping a file does not delete it from the filesystem.

== Environmental nodes ==
’Appbase’ environmental nodes can be listed, deleted or set here.

= Running semantic queries =

See [wiki:WebInterface/RunningSemanticQueries Running semantic queries].

= Errors =
This service is available under the ”Errors” menu. 

If database contains file(s) with error form(s), the list of errors will be displayed in a table. Each row in the table is equivalent to one error. File name and an error message are shown in the table. Clicking the filename shows the file and highlights the position the error is in.

If the database does not contain any files with error forms, a ”No error” message is displayed.


= Dependency examinations =

To learn more about dependency analysises see the [wiki:Dependency Dependency Analysis page].

An application called Graphviz, is needed to generate results in .svg format.

All images generated during examinations are placed in the directory which has been set during startup by the 'images_dir' switch. If this parameter has not been set, all images are placed in the current working the directory.

== Analyse in function or in module level ==
Dependency examinations can be performed on a module or function level, using the whole graph or the cyclic sub-graph. A self-defined module or function can also be set as the starting node of an examination. This service is available in the ”Dependency graph” menu under the ”Function or Module level” tab.

Possible configurations for an examination are:

* Configuring the level of the examination: setting {{{module}}} or {{{function}}} from the ”Level” drop-down.

* Configuring the type of the examination:
 * {{{None}}}: In this case, the type of examination is not given, this mode is used when the user wants to set the starting node of the examination.
 * {{{Whole graph}}}: Dependency examinations are performed on the whole graph.
 * {{{Cyclic sub-graph}}}: Dependency examinations are performed only on the set of cyclic sub-graphs.

* Configuring the starting node of the examination:
 * {{{module}}}: can be set in the text-field located under ”Starting node (module)”. The interface offers possible endings while typing a module name, based on modules that are loaded into the database. An offered module name can be chosen from a drop-down list.
 * {{{function}}}: can be set in the text-field located under ”Starting node (function)”. The function should be given in the following form: {{{module name:function name/arity}}}. The interface offers possible endings here as well.

Modules or functions which you don't want to see in the graph, should be added to the Excluded list with the provided button, or directly in the text area separated by newlines.
Modules or functions which leaves you don't want to see in the graph, should be added to the No leaves list the same way.
You can also exclude all OTP modules/functions by checking the Exclude OTP checkbox.

After configurating an examination, click the ”Generate graph” button to start it. The result is available in two different graphic formats. By clicking ”Generated graph in .dot” the result is sent to the browser in .dot format. By clicking ”See generated graph in .svg” the result is displayed in a new window in the browser.

== Analyse in functionblock level ==
Dependency analysis can also be done in functionblock level. This service is available in the ”Dependency graphs” menu under the ’Functionblock’ tab.

Predefined functionblocks are the loaded directories, but a functionblock can also be defined by the user, by typing the needed Perl-like regular expression into the textfield, and pressing the ’Add’ button.

The available functionblocks are placed in the ’Functionblock’ list. From there the subjects of the analysis can be drag and dropped into the ’Subjects’ list. After this you can generate a graph as usual.


= Logging out =
If the interface is no longer needed, the user can log out by clicking the ”Log out {{{username}}}” button. During the logout process the interface clears the users session, deletes the dynamically generated images, which belong to the user, and redirects the browser to the login page. The interface does not delete the queries executed by the user, nor their results, and also keeps the state of the database.