[[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 =

See [wiki:WebInterface/DependencyExaminations Dependency examinations].


= 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.