Changes between Version 4 and Version 5 of Web2

Timestamp:

Feb 27, 2014, 8:36:41 AM (11 years ago)

Author:

manualwiki

Comment:

--

Web2

@@ -158 +158 @@
 
 You 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 belonging 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.
+
+{{{#!comment
+= New web interface
+
+In addition to the console UIs, we also maintain a browser based (remote, via HTTP) interface to the tool, which provides an even more convenient way for code grokking. The main features of the web interface are:
+
+* Running and exploring semantic queries (both normal and context-sensitive queries)
+* Query construct assistant (auto-complete)
+* Persistent queries
+* Management of (possibly multiple) running queries
+* Database operations
+* Ability to mark files with error forms
+* Dependency examinations
+* Marking expressions as dynamic function references
+
+''Note that !JavaScript must be enabled in the browser to be able to use this interface.''
+
+== Installation
+Actually, this interface is only a limited prototype, thus it has some extra restrictions, which are related to the used web browser. Due to the usage of web sockets, neither Internet Explorer nor Firefox are not supported. We only support Google Chrome and Safari.
+ 
+=== Yaws ===
+The web based UI is built upon the [http://yaws.hyber.org/ Yaws] web server. To be able to start this interface you need a Yaws web server installed. Installation help: http://yaws.hyber.org/yaws.pdf (see Chapter 2).
+
+* Required version: 1.95
+
+If you prefer using a different version of Yaws, please, use [wiki:WebInterface the old web based interface] of the tool.
+
+'''If Erlang/OTP-R16B01 or a newer version is used''', then none of the Yaws versions will be compiled from source. The problem is that every Erlang source of Yaws is compiled with the {{{-Werror}}} flag which causes build error when used with at least Erlang/OTP-R16B01 to compile Yaws.
+
+To fix this error, you should use this modified Makefile. Put [attachment:Makefile:wiki:WebInterface this Makefile] under the {{{src}}} directory of the downloaded sources of Yaws, then  execute {{{make clean}}}. After the execution, the standard build procedure should be followed which is shown in LocalInstallLinux page.
+
+If Windows is used, then other opportunity exists. Use the installer binaries of different Yaws versions (Yaws-1.92 - Yaws-1.96) instead of compiling them from source.
+
+For a step-by-step installation tutorial, which is including the installation guide of Yaws, please see LocalInstallLinux.
+
+== Starting up
+
+We can start the server either with the {{{referl}}} script using the {{{-web2}}} option, or from a running !RefactorErl shell. Both cases provide a default configuration: server name {{{localhost}}}, port {{{8001}}}, and address {{{127.0.0.1.}}}, which can be overridden.
+
+Possible options:
+
+ * {{{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.
+  (This option can be used multiple times if you wish to add more than one directories.)
+
+ * {{{images_dir IDIR}}}
+
+  Path of the directory where the generated images (visualisation of dependency examinations) will be placed.
+
+ * {{{restricted_mode ENABLED}}}
+
+  A boolean value determining whether the web interface will be started in restricted mode.
+
+=== Startup: referl script
+
+You can pass any of the above options via command-line arguments (note that {{{-web2}}} is mandatory).
+Example:
+{{{
+bin/referl -web2
+           -yaws_path /Users/V/yaws-1.95/ebin 
+           -yaws_listen 127.0.0.1
+           -yaws_port 8000
+           -yaws_name localhost
+           -browser_root /Users/V/erlang
+           -browser_root /Users/V/project
+           -images_dir /Users/V/graph_images
+           -restricted_mode true
+}}}
+
+=== Startup: !RefactorErl shell
+
+We have two functions for starting the interface : {{{ri:start_web2/0}}} and {{{ri:start_web2/1}}}. Without passing any parameters the web server starts up with the default configuration. The 1-arity function allows the interface to be configured using an [http://www.erlang.org/doc/man/proplists.html Erlang proplist]. Example:
+{{{
+#!erlang
+
+ri:start_web2([
+    {yaws_path,"/Users/V/yaws-1.95/ebin"},
+    {yaws_listen,"127.0.0.1"},
+    {yaws_name, localhost},
+    {yaws_port,"8000"},
+    {browser_root,"/Users/V/erlang"},
+    {images_dir,"/Users/V/graph_images"},
+    {restricted_mode, true}]).
+}}}
+
+To specify multiple locations as root directories for database operations, you can pass a list of those locations with the {{{browser_root}}} property. Example:
+{{{
+#!erlang
+
+ri:start_web2([
+    {browser_root, ["/Users/V/erlang", "/Users/V/project"]}]).
+}}}
+
+
+== Shutting down
+
+You are advised to always log out before shutting down the web server, because the log-out process deletes temporary, dynamically generated components of web pages. If the server has been started from the !RefactorErl shell, then {{{ri:stop_web2()}}} should be called in order to shut down the service.
+
+
+== Logging in & Restricted mode
+
+In your browser, navigate to the server address defined by the configuration (the default is {{{http://localhost:8001}}}) after the web server has been successfully started. Services are allowed only to authorized people, so first you have to log in with a username. After a succesful login the browser will be redirected to the ''queries'' page.
+
+If the interface has been started with restricted mode enabled standard users can not acces the Database and Errors pages or any database modifying functions. The administrator can still acces these functions but for that you have to set up and use a password.
+
+For setting up the password you have to use a !RefactorErl shell:
+{{{
+#!erlang
+
+referl_ui_web2:set_web2_pass("admin", "*Password*").
+}}}
+
+After the password has been set the administrator can log in with the "admin" username and the set password and access the restricted functions.
+
+== Global notifications
+
+When someone starts/finishes a modification of the database (e.g. adding files), a notification will appear stating what process has been started/finished.
+During any modification process most functions on the web interface will not be available. This restriction is global for the whole system. 
+For further information, see: [wiki:ConfigurableJobServer Configurable Jobserver]
+
+== Stateful pages
+
+The interface has stateful pages meaning one can share any visible states with a teammate by copying the url from the address bar and sending it.
+Also you can easily navigate between previous states of the interface with your browser's back, forward and history functions.
+
+== Database operations
+
+This service is available under the "Database" tab. 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 by clicking the button in the top right corner of the file browser box.
+
+=== Browsing files on the server
+
+The root directory of the browser is an optional configuration parameter. Possible values are:
+
+ * When the {{{browser_root}}} parameter has been set during start up, the given value or values are the root element(s).
+ * When the {{{browser_root}}} parameter has not been set during start up:
+   * If the database had contained files before start up, the root elements are the directories of these files.
+   * If the database had not contained files before start up, then !RefactorErl’s lib directory will be the root.
+
+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 highlighted by a blue background. Database operations are indicated by a progress bar.
+
+Searching is possible in both file system files, and loaded files. 
+
+=== Browsing loaded files
+
+In this mode, directories' and files' contents can be listed, a selected file or directory can be reloaded to the database, dropped from the database, or can be pre-generated for the source code viewer. Status messages are displayed during the reloading/dropping/generating process, and also after the process has finished.
+The file browser displays the last directory that contains all the loaded files. 
+Under the file browser box, there is a separate box for the function quicklist. In this box, the function definitions of the displayed file are listed if the file is added to the database. You can jump to the chosen function in the file by clicking on.
+If file is not displayed correctly, you can try to "repair" it by clicking the Refresh button in the upper right corner of the function quicklist window.
+
+''Dropping a file from the database does not imply removal from the file system.''
+
+== Downloading files from the server
+
+When browsing the database or filesystem contents on the "Queries" or "Database" pages you can right-click on the selected file and download it to your local machine by selecting "Download file" from the appearing context menu.
+
+== Running semantic queries
+
+See [wiki:Web2/RunningSemanticQueries Running semantic queries].
+
+== Errors
+
+This service is available under the "Errors" tab.
+
+If the database contains file(s) with error form(s), the list of errors will be displayed in a table. Each row in the table shows an error. Clicking the file name shows the file and highlights the position of the error.
+
+If the database does not contain any files with error forms, a "No error" message is displayed.
+
+== Dependency examination
+
+See [wiki:Web2/DependencyExaminations Dependency examinations].
+{{{#!comment
+== Code duplicates
+
+See [wiki:WebInterface/CodeDuplicates Code duplicates].
+}}}
+
+== Reporting dynamic function references
+
+While browsing the contents of a file in the database, any expression can be reported as a dynamic function reference candidate by right-clicking and selecting Send "{{{expression}}}" as dynfun from the context menu. See [wiki:DynamicCallAnalysis#User-definedfunctionreferences User-defined function references].
+
+The reported candidates can later be reviewed at the server via a !RefactorErl shell:
+{{{
+#!erlang
+
+referl_ui_web2:show_dynfuns([{out, stdio}, {filter, valid}, {filter, new}, {filter, {file, "name"}}]).
+referl_ui_web2:delete_dynfuns().
+}}}
+
+Possible options for {{{show_dynfuns/1}}}:
+ * ''none'':
+   Returns the reported references as erlang terms.
+ * {{{ {out, stdio} | {out, stdout} }}}:
+   Formats and prints the references to the standard output.
+ * {{{ {out, {file, "name.ext"}} }}}:
+   Prints the output to the given filename.
+ * {{{ {filter, {seen, true}} | {filter, seen} }}}:
+   Only outputs the previously seen references.
+ * {{{ {filter, {seen, false}} | {filter, new} }}}:
+   Only outputs newly reported expressions.
+ * {{{ {filter, valid} }}}:
+   Outputs the references where the database was the same as now at the time of reporting.
+ * {{{ {filter, {file, "regexp"}} }}}:
+   Only gives outputs where "regexp" matches to the file-path of the expression. 
+
+
+== Logging out
+
+You 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 belonging 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.
+
+}}}