documentation update

Author: ddmitov

README.md

@@ -1,7 +1,8 @@
 Perl Executing Browser  
 ----------------------------------------------------------------------------------------
 
-Perl Executing Browser (PEB) is a C++ [Qt 5] (https://www.qt.io/) WebKit implementation of a minimalistic HTML framework for local [Perl 5] (https://www.perl.org/) scripts executed without server as desktop data-driven applications. Perl 5 scripts can be fed from HTML forms using GET and POST methods or from AJAX requests. HTML interface for interaction with the built-in Perl debugger is also available.
+Perl Executing Browser (PEB) is a C++ [Qt 5] (https://www.qt.io/) WebKit implementation of a minimalistic HTML framework for local [Perl 5] (https://www.perl.org/) scripts executed without server as desktop data-driven applications. Perl 5 scripts can be fed directly from HTML forms using GET and POST methods or using AJAX requests. HTML interface for interaction with the built-in Perl debugger is also available.  
+Inspired by [NW.js] (http://nwjs.io/) and [Electron] (http://electron.atom.io/), PEB is another reuse of web technologies for the development of desktop applications, but with Perl doing the heavy lifting.
 
 ## Design Objectives
 
@@ -23,18 +24,18 @@ Perl Executing Browser (PEB) is a C++ [Qt 5] (https://www.qt.io/) WebKit impleme
 ## Features
 
 **Usability:**
-* Perl 5 scripts can be fed from HTML forms using GET or POST methods or from AJAX requests.
-* Single file or multiple files, new filename, existing or new directory can be selected by user and supplied with their full paths to local Perl scripts.
-* Basic security restrictions are imposed on every Perl script.
+* Perl 5 scripts can be fed directly from HTML forms using GET or POST methods or using AJAX requests.
 * Any version of Perl 5 can be used.
+* Basic security restrictions are imposed on every Perl script.
 * PEB can be started from any folder.
-* Cross-site scripting is disabled for all web pages.
+* PEB is usefull for both single-page or multi-page applications.
+* Single file or multiple files, new filename, existing or new directory can be selected by user.
+  Their full paths are displayed in the calling local page and they can be supplied to local Perl scripts.
 * Browser functions are accessible from special URLs.
 * Any icon can be displayed on windows and message boxes.
-* Every aspect of the graphical user interface can be customized using HTML & JavaScript.
-* Usefull for both single-page or multi-page applications.
 * Optional JavaScript translation of context menu and dialog boxes.
 * Optional warning for unsaved data in HTML forms before closing a window to prevent accidental data loss.
+* Cross-site scripting is disabled for all web pages.
 
 **Development goodies:**
 * PEB can interact with the Perl 5 debugger in graphical mode - see section *HTML Interface for the Perl Debugger*  
@@ -46,7 +47,7 @@ Perl Executing Browser (PEB) is a C++ [Qt 5] (https://www.qt.io/) WebKit impleme
 GCC compiler and Qt 5.1 - Qt 5.5 headers (including ```QtWebKit``` headers).  
 Later versions of Qt are unusable due to the deprecation of ```QtWebKit```.  
 
-The most important Qt dependency of PEB is actually not ```QtWebkit```, but ```QNetworkAccessManager``` class, which is subclassed to implement CGI-like POST and AJAX GET and POST requests to local Perl scripts. The removal of this class from the ecosystem of ```QtWebEngine```, the new Blink-based web engine of Qt, means that transition to ```QtWebEngine``` remains problematic.  
+The most important Qt dependency of PEB is actually not ```QtWebkit```, but ```QNetworkAccessManager``` class, which is subclassed to implement non-AJAX POST and AJAX GET and POST requests to local Perl scripts. The removal of this class from the ecosystem of ```QtWebEngine```, the new Blink-based web engine of Qt, means that transition to ```QtWebEngine``` remains problematic.  
 
 Compiled and tested successfully using:
 * [Qt Creator 2.8.1 and Qt 5.1.1] (http://download.qt.io/official_releases/qt/5.1/5.1.1/) on 32-bit Debian Linux,
@@ -65,6 +66,49 @@ Compiled and tested successfully using:
 * Perl 5 distribution - any Linux, Mac or Windows Perl distribution.  
   [Strawberry Perl] (http://strawberryperl.com/) PortableZIP edition is successfully used with all Windows builds of PEB.
 
+## How to Call Local Perl Scripts from a Local Page?
+  PEB recognizes two types of local Perl scripts: non-AJAX scripts and AJAX scripts.
+* **Non-AJAX Perl scripts:**  
+    Non-AJAX Perl scripts are expected to produce a complete HTML page that will replace the calling page when script output becomes available. Note that there could be multiple chunks of script output from non-AJAX scripts - PEB accumulates them and displays everything it has when a new piece of script output comes out.  
+  
+    There is no timeout for all Perl scripts executed by PEB (non-AJAX and AJAX), but slow scripts should be optimized to avoid degradation of the user experinece.  
+  
+    There is no special naming convention for non-AJAX scripts and they are called from hyperlinks or HTML forms just like any Perl CGI script was called in the olden days of Perl CGI scripting:
+
+```html
+  <form action="perl/test.pl" method="post">
+      <input type="text" id="value1" name="value1" placeholder="Value 1" title="Value 1">
+      <input type="text" id="value2" name="value2" placeholder="Value 2" title="Value 2">
+  
+      <input type="reset" value="Reset">
+      <input type="submit" value="Submit">
+  </form>
+```
+
+* **AJAX Perl scripts:**  
+    AJAX scripts don't have to produce a complete HTML page, but they have two differences compared to non-AJAX scripts.  
+  
+    PEB returns all output from AJAX scripts in one piece after the script has finished with no timeout.
+  
+    AJAX scripts must have the keyword ```ajax``` somewhere in their pathname so that PEB is able to distinguish between AJAX and non-AJAX scripts. So an AJAX script could be named ```ajax-test.pl``` or all AJAX scripts could be placed in a folder called ```ajax-scripts``` somewhere inside the application directory - see section *Settings*.
+  
+    The following example illustrates how to call a local AJAX Perl script from a local page:  
+
+```javascript
+  $(document).ready(function() {
+      $('#ajax-button').click(function() {
+          $.ajax({
+              url: 'http://perl-executing-browser-pseudodomain/perl/ajax-test.pl',
+              method: 'GET',
+              dataType: 'text',
+              success: function(data) {
+                  $('#ajax-results').html(data);
+              }
+          });
+      });
+  });
+```
+
 ## Settings
 
 **Settings based on the existence of certain files and folders:**  
@@ -75,12 +119,14 @@ PEB is designed to run from any directory without setting anything beforehand an
     Application directory must be ```{PEB_binary_directory}/resources/app```. All files used by PEB, with the exception of data files, must be located within this folder. Application directory is hardcoded in C++ code for compatibility with the [Electron] (http://electron.atom.io/) framework. [Epigraphista] (https://github.com/ddmitov/epigraphista) provides an example of a PEB-based application, that is also compatible with [Electron] (http://electron.atom.io/) and [NW.js] (http://nwjs.io/).
 * **Data directory:**  
     Data directory is not hardcoded in C++ code, but a separation of data files from code is generally a good practice. Data directory should contain any SQLite database(s) or other files, that a PEB-based application is going to use or produce. The recommended path for data directory is inside the ```{PEB_binary_directory}/resources``` directory. ```data``` is a good directory name, although not mandatory. Perl scripts can access this folder using the following code:
+
 ```perl
     use Cwd;
 
     my $current_working_directory = cwd();
     my $data_directory = "$current_working_directory/resources/data";
 ```
+
 * **Perl interpreter:**  
     PEB expects to find Perl interpreter in ```{PEB_binary_directory}/perl/bin``` folder. The interpreter must be named ```perl``` on Linux and Mac machines and ```perl.exe``` on Windows machines. If Perl interpreter is not found in the above location, PEB will try to find the first Perl interpreter on PATH. If no Perl interpreter is found, an error message is displayed instead of the start page. No Perl interpreter is a showstopper for PEB.
 * **Start page:**  
@@ -280,7 +326,7 @@ JavaScript-based settings are created to facilitate the development of fully tra
 
 **Security features based on Perl code:**
 * Perl scripts are executed in an ```eval``` function after banning potentially unsafe core functions. This feature is implemented in a special script named ```censor.pl```, which is compiled into the resources of the browser binary and is executed from memory when Perl script is started. All core functions from the :dangerous group - ```syscall```, ```dump``` and ```chroot```, as well as ```fork``` are banned.
-* The environment of all Perl scripts is once again filtered in the ```BEGIN``` block of ```censor.pl``` to ensure no unwanted environment variables are inserted from the operating system.
+* The environment of all Perl scripts is once again filtered in the ```BEGIN``` block of ```censor.pl``` to ensure no unwanted environment variables are inserted by the operating system.
 
 **Perl Debugger Interaction:**
 * Any Perl script can be selected for debugging, which is also a security risk. So if Perl debugger interaction is not needed, it can be turned off by a compile-time variable. Just change ```PERL_DEBUGGER_INTERACTION = 1``` to ```PERL_DEBUGGER_INTERACTION = 0``` in the project file of the browser (peb.pro) and compile the binary.  
@@ -296,7 +342,7 @@ JavaScript-based settings are created to facilitate the development of fully tra
 
 * PEB is not a general purpose web browser and does not have all traditional features of general purpose web browsers.
 * Unlike JavaScript in general purpose web browsers, Perl scripts executed by PEB have no access to the HTML DOM tree of any page.
-* PEB is not an implementation of the CGI protocol. It uses only three environment variables (see below) together with the GET and POST methods from the CGI protocol in a purely local context without any attempt to communicate with the outside world.
+* PEB is not an implementation of the CGI protocol. It uses only three environment variables together with the GET and POST methods from the CGI protocol in a purely local context without any attempt to communicate with the outside world.
 * PEB does not embed any Perl interpreter in itself and rellies on an external Perl distribution, which could be easily changed or upgraded independently.
 * PEB has no sandbox for Perl scripts - they are treated like and executed as ordinary desktop applications with normal user privileges.
 

src/peb.cpp

@@ -634,7 +634,7 @@ QPage::QPage()
                      this,
                      SLOT(qStartScriptSlot(QUrl, QByteArray)));
 
-    // Connect signals and slots for all local CGI-like Perl scripts:
+    // Connect signals and slots for all local non-AJAX Perl scripts:
     QObject::connect(&scriptHandler, SIGNAL(readyReadStandardOutput()),
                      this, SLOT(qScriptOutputSlot()));
     QObject::connect(&scriptHandler, SIGNAL(readyReadStandardError()),

src/peb.h

@@ -440,7 +440,7 @@ class QAccessManager : public QNetworkAccessManager
         }
 
         // GET requests to the browser pseudodomain -
-        // local files and CGI-like scripts:
+        // local files and non-AJAX scripts:
         if (operation == GetOperation and
                 request.url().authority() == PSEUDO_DOMAIN and
                 (!request.url().path().contains("ajax"))) {
@@ -536,7 +536,7 @@ class QAccessManager : public QNetworkAccessManager
             }
         }
 
-        // POST requests to the browser pseudodomain - CGI-like scripts:
+        // POST requests to the browser pseudodomain - non-AJAX scripts:
         if (operation == PostOperation and
                 request.url().authority() == PSEUDO_DOMAIN and
                 (!request.url().path().contains("ajax"))) {