API update

Author: ddmitov

README.md

@@ -48,25 +48,17 @@ These are the basic steps for building your first PEB-based application:
 
 * **4.** Connect your Perl scripts using a link to ``name-of-script-configuration-object.settings``.  
 
-Note that PEB is created to work from any folder without installation and all files and directories used by PEB are relational to the directory where the PEB binary is located. All your local HTML files and Perl scripts must be located inside the ``{PEB_binary_directory}/resources/app`` directory.  
+Note that PEB is created to work from any folder without installation and all your local HTML files and Perl scripts should be located inside the ``{PEB_binary_directory}/resources/app`` directory.  
 
 ## Design Objectives
-* **1. Fast and easy graphical user interface for Perl 5 desktop applications:**  
-    use Perl 5, JavaScript, HTML and CSS to create beautiful desktop applications
-
-* **2. Zero installation:**  
-    run from any folder
-
-* **3. Cross-platform availability:**  
-    usable on every platform where Perl 5 and Qt 5 are available
-
-* **4. Secure serverless solution:**  
-    no server of any kind is installed or started
-
+* **1. Fast and easy and beautiful graphical user interface for Perl 5 desktop applications**  
+* **2. Zero installation**  
+* **3. Cross-platform availability**  
+* **4. Secure serverless solution**  
 * **5. Maximal reuse of existing web technologies and standards**
 
 ## Features
-* [Perl script output is seamlessly inserted into the calling local page.](#perl-scripts-api)
+* [Perl script output is seamlessly inserted in any local page.](#perl-scripts-api)
 * [Perl scripts with STDIN event loops can be repeatedly fed with data.](#interactive-perl-scripts)
 * [Any version of Perl 5 can be used.](#runtime-requirements)
 * PEB can be started from any folder.
@@ -78,6 +70,7 @@ Note that PEB is created to work from any folder without installation and all fi
 
 ## Security
 * PEB does not need administrative privileges, but does not refuse to use them if needed.
+* PEB does not install or start any kind of server.
 * PEB executes with no sandbox only local Perl 5 scripts and
   users have full access to their local files.
 * Cross-origin requests and cross-site scripting are disabled.
@@ -142,26 +135,32 @@ Sometimes it is important to minimize the size of the relocatable (or portable)
 ``compactor.pl`` relies on ``Module::ScanDeps`` and ``File::Copy::Recursive`` CPAN modules, which are located in the ``{PEB_binary_directory}/sdk/lib`` folder.  
 
 ## Perl Scripts API
-Every Perl script run by PEB is called by clicking a link or submitting a form to a pseudo filename composed from the name of the JavaScript object with the settings of the Perl script and a ``.settings`` extension. Perl data output is seamlessly inserted into the HTML DOM of the local page using JavaScript.  
+Every Perl script run by PEB is called by clicking a link or submitting a form to a pseudo filename composed from the name of the JavaScript object with the settings of the Perl script and a ``.settings`` extension.  
+
+A minimal example of a Perl script settings object and a starting link:  
 
-A minimal example of a Perl script settings object:  
+```html
+<a href="perl_test.settings">Start Perl script</a>
+```
 
 ```javascript
-var perlScriptObject = {};
-perlScriptObject.path = '{app}/perl/test.pl';
-perlScriptObject.stdout = function (stdout) {
+var perl_test = {};
+perl_test.scriptFullPath = '{app}/perl/test.pl';
+perl_test.stdoutFunction = function (stdout) {
   var container = document.getElementById('tests');
   container.innerHTML = stdout;
 }
 ```
 
-* ``path``  
+* ``scriptFullPath``  
   This is the path of the Perl script that is going to be executed.  
   The keyword ``{app}`` will be replaced by the the full path of the application directory.  
+  PEB does not check the file name extension or the shebang line of the supplied Perl script.  
+  Scripts without a file name extension can also be used.  
   *This object property is mandatory.*  
 
-* ``stdout``  
-  The ``stdout`` object property must be a JavaScript function. Every piece of script output is passed to this function as its only argument.  
+* ``stdoutFunction``  
+  The ``stdoutFunction`` object property must be a JavaScript function. Every piece of script output is passed to this function as its only argument.  
   *This object property is mandatory.*  
 
 * ``requestMethod``  
@@ -191,16 +190,16 @@ perlScriptObject.stdout = function (stdout) {
   }
   ```
 
-* ``close_command``  
-  The ``close_command`` object property designates the command used to gracefully shut down an interactive script when the containing PEB window is going to be closed. Upon receiving it, the interactive script must start its shutdown procedure.
+* ``scriptExitCommand``  
+  The ``scriptExitCommand`` object property designates the command used to gracefully shut down an interactive script when PEB is going to be closed. Upon receiving it, the interactive script must start its shutdown procedure.
 
-* ``close_confirmation``  
-  Just before exiting an interactive script must print on STDOUT its ``close_confirmation`` to signal PEB that it completed its shutdown. All interactive scripts must exit in 3 seconds after ``close_command`` is given or any unresponsive scripts will be killed and PEB will exit.
+* ``scriptExitConfirmation``  
+  Just before exiting an interactive script must print on STDOUT its ``scriptExitConfirmation`` to signal PEB that it completed its shutdown. All interactive scripts must exit in 3 seconds after ``scriptExitCommand`` is given or any unresponsive scripts will be killed and PEB will exit.
 
 Perl scripts running for a long time should have ``$|=1;`` among their first lines to disable the built-in buffering of the Perl interpreter. Some builds of Perl may not give any output until the script is finished when buffering is enabled.
 
 ## Interactive Perl Scripts
-Each PEB interactive Perl script must have its own event loop waiting constantly for new data on STDIN for a bidirectional connection with PEB. Many interactive scripts can be started simultaneously in one browser window. One script may be started in many instances provided that it has an unique JavaScript settings object with and unique ``stdout`` object property. Interactive scripts should also have the ``close_command`` and ``close_confirmation`` object properties.  
+Each PEB interactive Perl script must have its own event loop waiting constantly for new data on STDIN for a bidirectional connection with PEB. Many interactive scripts can be started simultaneously in one browser window. One script may be started in many instances provided that it has an unique JavaScript settings object with and unique ``stdoutFunction`` object property. Interactive scripts should also have the ``scriptExitCommand`` and ``scriptExitConfirmation`` object properties.  
 
 The following code shows how to start an interactive Perl script right after a local page is loaded:
 
@@ -217,14 +216,17 @@ The following code shows how to start an interactive Perl script right after a l
       pebSettings.autoStartScripts = ['interactive_script'];
 
       var interactive_script = {};
-      interactive_script.path = '{app}/perl/interactive.pl';
-      interactive_script.stdout = 'interactive-script-output';
+      interactive_script.scriptFullPath = '{app}/perl/interactive.pl';
       interactive_script.requestMethod = 'POST';
       interactive_script.inputDataHarvester = function() {
         return document.getElementById('interactive-script-input').value;
       }
-      interactive_script.closeCommand = '_close_';
-      interactive_script.closeConfirmation = '_closed_';
+      interactive_script.stdoutFunction = function (stdout) {
+        var container = document.getElementById('interactive-script-output');
+        container.innerHTML = stdout;
+      }
+      interactive_script.scriptExitCommand = '_close_';
+      interactive_script.scriptExitConfirmation = '_closed_';
     </script>
   </head>
 
@@ -242,7 +244,7 @@ The following code shows how to start an interactive Perl script right after a l
 The ``index.htm`` file of the demo package demonstrates how to start one script in two instances immediately after a page is loaded.
 
 ## Selecting Files and Folders
-Selecting files or folders with their full paths is performed by clicking a link to a pseudo filename composed from the name of the JavaScript object with the settings of the wanted dialog and a ``.dialog`` extension. Selected files or folders are seamlessly inserted in any local page using the ``target`` object property. ``target`` must be a JavaScript function which receives all selected files or folders as its only argument.  
+Selecting files or folders with their full paths is performed by clicking a link to a pseudo filename composed from the name of the JavaScript object with the settings of the wanted dialog and a ``.dialog`` extension. Selected files or folders are seamlessly inserted in any local page by the ``receiverFunction`` taking all selected files or folders as its only argument.  
 
 ```html
 <a href="select_file.dialog">Select existing file</a>
@@ -253,9 +255,9 @@ var select_file = {};
 // Type of the dialog, one of the following:
 // 'single-file', 'multiple-files', 'new-file-name' or 'directory'.
 select_file.type = 'single-file';
-select_file.target = function (stdout) {
-  var container = document.getElementById('tests');
-  container.innerHTML = stdout;
+select_file.receiverFunction = function (file) {
+  var container = document.getElementById('single-file-test');
+  container.innerHTML = file;
 }
 ```
 
@@ -298,7 +300,7 @@ my $data_directory = "$current_working_directory/resources/data";
 ```
 
 ## Log Files
-If log files are needed for debugging of PEB or a PEB-based application, they can easily be turned on by manually creating ``{PEB_binary_directory}/logs``. If this directory is found during application startup, the browser assumes that logging is required and a separate log file is created for every browser session following the naming convention: ``{application_name}-started-at-{four_digit_year}-{month}-{day}--{hour}-{minute}-{second}.log``. PEB will not create ``{PEB_binary_directory}/logs`` on its own and if this directory is missing and no logs will be written. Please note that log files can grow rapidly and if disc space is an issue, writing log files can be turned off by simply removing or renaming ``{PEB_binary_directory}/logs``.
+If log files are needed for debugging of PEB or a PEB-based application, they can easily be turned on by manually creating ``{PEB_binary_directory}/logs``. If this directory is found during application startup, the browser assumes that logging is required and a separate log file is created for every browser session following the naming convention: ``{application_name}-started-at-{four_digit_year}-{month}-{day}--{hour}-{minute}-{second}.log``. PEB will not create ``{PEB_binary_directory}/logs`` on its own and if this directory is missing no logs will be written.
 
 ## Page Settings
 
@@ -322,7 +324,7 @@ pebSettings.closeConfirmation =
   These are Perl scripts that are started immediately after a local page is loaded.  
 
 * ``closeConfirmation``  
-  This is the text displayed when user has pressed the close button, but unsaved data in local HTML forms is detected. If no warning text is found, PEB assumes that no warning has to be displayed and exits immediately.
+  This text is displayed when the close button is pressed, but unsaved data in local HTML forms is detected. If no warning text is found, PEB exits immediately.
 
 ## Functional Pseudo Filenames
 * **About PEB dialog:** ``about-browser.function``

resources/app/index.html

@@ -25,74 +25,67 @@
 
       // Settings objects for the Perl scripts:
       var interactive_one = {};
-      interactive_one.path = '{app}/perl/interactive.pl';
-      interactive_one.stdout = function (stdout) {
-        var target = document.getElementById('instance-one-output');
-        target.innerHTML = stdout;
-      }
+      interactive_one.scriptFullPath = '{app}/perl/interactive.pl';
       interactive_one.requestMethod = 'POST';
-      interactive_one.closeCommand = '_close_';
-      interactive_one.closeConfirmation = '_closed_';
       interactive_one.inputDataHarvester = function() {
         var data = $('#form-one').serialize();
         $('#form-one').trigger('reset');
         return data;
       }
-
-      var interactive_two = {};
-      interactive_two.path = '{app}/perl/interactive.pl';
-      interactive_two.stdout = function (stdout) {
-        var target = document.getElementById('instance-two-output');
+      interactive_one.stdoutFunction = function (stdout) {
+        var target = document.getElementById('instance-one-output');
         target.innerHTML = stdout;
       }
+      interactive_one.scriptExitCommand = '_close_';
+      interactive_one.scriptExitConfirmation = '_closed_';
+
+      var interactive_two = {};
+      interactive_two.scriptFullPath = '{app}/perl/interactive.pl';
       interactive_two.requestMethod = 'POST';
-      interactive_two.closeCommand = '_close_';
-      interactive_two.closeConfirmation = '_closed_';
       interactive_two.inputDataHarvester = function() {
         var data = $('#form-two').serialize();
         $('#form-two').trigger('reset');
         return data;
       }
+      interactive_two.stdoutFunction = function (stdout) {
+        var target = document.getElementById('instance-two-output');
+        target.innerHTML = stdout;
+      }
+      interactive_two.scriptExitCommand = '_close_';
+      interactive_two.scriptExitConfirmation = '_closed_';
 
       var get_test = {};
-      get_test.path = '{app}/perl/get-post-test.pl';
-      get_test.stdout = 'tests';
-      get_test.stdout = function (stdout) {
+      get_test.scriptFullPath = '{app}/perl/get-post-test.pl';
+      get_test.stdoutFunction = function (stdout) {
         displayTestResult(stdout);
       }
       get_test.requestMethod = 'GET';
       get_test.inputData = 'name=Mickey&species=mouse';
 
       var post_test = {};
-      post_test.path = '{app}/perl/get-post-test.pl';
-      post_test.stdout = function (stdout) {
+      post_test.scriptFullPath = '{app}/perl/get-post-test.pl';
+      post_test.stdoutFunction = function (stdout) {
         displayTestResult(stdout);
       }
       post_test.requestMethod = 'POST';
       post_test.inputData = 'name=Geoffrey&species=giraffe';
 
       var perl_info = {};
-      perl_info.path = '{app}/perl/perl-info.pl';
-      perl_info.stdout = function (stdout) {
-        displayTestResult(stdout);
-      }
-
-      var extensionless = {};
-      extensionless.path = '{app}/perl/extensionless';
-      extensionless.stdout = function (stdout) {
+      perl_info.scriptFullPath = '{app}/perl/perl-info.pl';
+      perl_info.stdoutFunction = function (stdout) {
         displayTestResult(stdout);
       }
 
       var sqlite = {};
-      sqlite.path = '{app}/perl/sqlite.pl';
-      sqlite.stdout = function (stdout) {
+      sqlite.scriptFullPath = '{app}/perl/sqlite.pl';
+      sqlite.stdoutFunction = function (stdout) {
         displayTestResult(stdout);
       }
 
       // Filesystem dilog boxes configuration objects:
       var select_file = {};
       select_file.type = 'single-file';
-      select_file.target = function (fileName) {
+      select_file.receiverFunction = function (fileName) {
         clearTargetElement();
         var pre = document.createElement("pre");
         pre.innerHTML = 'Selected existing file: ' + fileName;
@@ -101,7 +94,7 @@
 
       var new_file_name = {};
       new_file_name.type = 'new-file-name';
-      new_file_name.target = function (fileName) {
+      new_file_name.receiverFunction = function (fileName) {
         clearTargetElement();
         var pre = document.createElement("pre");
         pre.innerHTML = 'Selected new file name: ' + fileName;
@@ -110,7 +103,7 @@
 
       var select_files = {};
       select_files.type = 'multiple-files';
-      select_files.target = function (fileNames) {
+      select_files.receiverFunction = function (fileNames) {
         clearTargetElement();
         var pre = document.createElement("pre");
         fileNames = fileNames.replace(/;/g, "<br>");
@@ -120,7 +113,7 @@
 
       var select_directory = {};
       select_directory.type = 'directory';
-      select_directory.target = function (directoryName) {
+      select_directory.receiverFunction = function (directoryName) {
         clearTargetElement();
         var pre = document.createElement("pre");
         pre.innerHTML = 'Selected directory: ' + directoryName;
@@ -230,10 +223,6 @@
               <a href="perl_info.settings">Perl Basic information</a>
             </li>
 
-            <li>
-              <a href="extensionless.settings">Extensionless Script</a>
-            </li>
-
             <li>
               <a href="sqlite.settings">SQLite Test</a>
             </li>

resources/app/perl/extensionless

@@ -26,15 +26,15 @@
 QScriptHandler::QScriptHandler(QJsonObject scriptJsonObject)
     : QObject(0)
 {
-    if (scriptJsonObject.length() == 0) {
-        qDebug() << "Script settings are empty!";
+    if (scriptJsonObject.length() == 1) {
+        qDebug() << "No script settings!";
         return;
     }
 
     scriptId = scriptJsonObject["id"].toString();
 
-    if (scriptJsonObject["path"].toString().length() > 0) {
-        scriptFullFilePath = scriptJsonObject["path"].toString();
+    if (scriptJsonObject["scriptFullPath"].toString().length() > 0) {
+        scriptFullFilePath = scriptJsonObject["scriptFullPath"].toString();
         scriptFullFilePath.replace("{app}",
                                    qApp->property("application").toString());
         scriptFullFilePath = QDir::toNativeSeparators(scriptFullFilePath);
@@ -56,13 +56,13 @@ QScriptHandler::QScriptHandler(QJsonObject scriptJsonObject)
         inputData = scriptJsonObject["inputData"].toString();
     }
 
-    if (scriptJsonObject["closeCommand"].toString().length() > 0) {
-        scriptCloseCommand = scriptJsonObject["closeCommand"].toString();
+    if (scriptJsonObject["scriptExitCommand"].toString().length() > 0) {
+        scriptExitCommand = scriptJsonObject["scriptExitCommand"].toString();
     }
 
-    if (scriptJsonObject["closeConfirmation"].toString().length() > 0) {
-        scriptCloseConfirmation =
-                scriptJsonObject["closeConfirmation"].toString();
+    if (scriptJsonObject["scriptExitConfirmation"].toString().length() > 0) {
+        scriptExitConfirmation =
+                scriptJsonObject["scriptExitConfirmation"].toString();
     }
 
     // Signals and slots for local long running Perl scripts:

src/script-handler.cpp

@@ -42,7 +42,7 @@ public slots:
         QString output = scriptProcess.readAllStandardOutput();
         scriptAccumulatedOutput.append(output);
 
-        if (output == scriptCloseConfirmation) {
+        if (output == scriptExitConfirmation) {
             qDebug() << "Interactive script is exiting normally:"
                      << scriptFullFilePath;
         } else {
@@ -76,8 +76,8 @@ public slots:
     QString scriptStdout;
     QString scriptAccumulatedOutput;
     QString scriptAccumulatedErrors;
-    QString scriptCloseCommand;
-    QString scriptCloseConfirmation;
+    QString scriptExitCommand;
+    QString scriptExitConfirmation;
 };
 
 #endif // SCRIPTHANDLER_H