Extension File

Javascript compliant script

Extensions are essentially javascript compliant script files (ECMA-262). People knowing javascript can easily write an Extension.

An Extension file contains the following two sections:

• Extension's attributes
  The extensions' attributes give information about the script, like it purpose, description and so on.
  They are inserted at the beginning of the file through tags in comment's lines.
• The exec([inData, options]) function 
  The function exec() is the function that is called every time an Extension is executed.
  It has some optional arguments:
     -  inData: the requested input data as a string or a Banana.Document object;
        This parameters is only used for import scripts, for all other tasks this parameter is just null;
     -  options: options as an object that can contains those parameters;
     -  useLastSettings: if true the script executes with the last used setttings and doesn't show a setting's dialog;
  The script return a string formatted according the tag @outputformat.
  Errors are notified through exceptions (clause throw), or just by returning a string beginning with "@Error:"
   
• [Optional] The settingsDialog() function 
  If the script has a dialog for settings some parameters it is advised to put the code for the dialog in this function. In this way the application can call this function just for showing or editing the parameters without executing the whole script.
  This method should return null if the user click on cancel button, or a value different of null if the user click on ok button.

For a list of supported javascript functions, objects and properties see: Qt ECMAScript Reference.

Extensions interact with Banana Accounting through some global objects made available by Banana Accounting, like for example 'Banana.document'. Those objects are described under the Banana Script API.

Extension "Hello World" example

Here an example that open a print preview windows, and show a document with the text "Hello world!!!". Other examples are found in the  Extensions tutorial.

// @id = ch.banana.report.helloworld
// @version = 1.0 
// @doctype = nodocument 
// @publisher = Banana.ch SA 
// @description = Hello world 
// @task = app.command 
// @timeout = -1
function exec() { 
   //Create the report
   var report = Banana.Report.newReport('Report title');
   //Add a paragraph with some text
   report.addParagraph('Hello World!!!');
   //Preview the report
   var stylesheet = Banana.Report.newStyleSheet();
   Banana.Report.preview(report, stylesheet);
}

Extension with a setting's dialog example

Here an example that use a dialog to input a text. Other examples are found in the Extensions tutorial.

// @id = ch.banana.report.settingsdialog
// @version = 1.0
// @doctype = *
// @publisher = Banana.ch SA
// @description = Example for settings dialog
// @task = app.command
// @timeout = -1
function exec(inData, options) {
   // Show dialog if options.useLastSettings is not set or is false
   if (!options || !options.useLastSettings) {
      if (!settingsDialog())
         return; // return if user pressed cancel
   }

   // Get the settings
   var text = Banana.document.getScriptSettings();

   //Create the report
   var report = Banana.Report.newReport('Report title');
   report.addParagraph('You entered: "' + text + '"');
   report.addParagraph(new Date().toString());

   //Stylesheet
   var stylesheet = Banana.Report.newStyleSheet();

   //Preview the report
   Banana.Report.preview(report, stylesheet);
}

function settingsDialog() {
   // Ask the user to enter a text that will be printed in the report
   var text = Banana.document.getScriptSettings();
   text = Banana.Ui.getText("Enter a text", "The text will be printed in the report", text);
   if (typeof(text) === 'string') {
      Banana.document.setScriptSettings(text);
      return true;
   }
   return false; // cancel pressed
}

Extensions have a strong Security model

Extensions are secure for the fact that are confined within Banana.
Extensions are NOT ALLOWED to directly write or read file, web resource, change computer setting or execute programs.

Extensions , contrary to Excel Macro, can be run with the confidence, they will not change any data and modify any file or computer settings.

To access or write to file you need to use the Banana Api that display a dialog box to the user.

• To write file you need to use the export functionality, that display a dialog where the user indicate the file name where to save.
• To import file you need to use the import functionality that display a dialog where the user specify the file name.

Best way to distribute the Extensions

• Single App file (javascript file)
  • Easier to edit (external text editors), move and update.
  • Can be included in the menu Extensions.
  • Can be used by different accounting file.
• Embedded extensions
  • Not available in the menu Extensions.
  • Only relative to the file where it is included.
  • More difficult to edit and update.
• Packaged App file
  • Cannot be easily changed.
  • Can be included in the menu Extensions.
  • Can be used by different accounting file.
  • Protected from user modification.

Extensions as a single javascript file

A single javascript (.js) file that includes all the code of the app.

This is how it works:

• Extensions are saved in UTF-8 file without BOOM.
• The Extension needs to be installed through the Manage Extensions command.
• Once the Extension is installed, it appears in the menu Extensions.
• The Extension can be run from the menu Extensions.

Embedded Extension in documents

Banana allows to have Extensions that are embedded within a Banana File. Embedded extensions run only for the specific file, but don't need to be installed.

To create embedded Extensions you can add script files in the table Documents.

On the Embedded Extensions  JavaScript Tutorial you will find the documentation and different basic examples embedded in a document that you can run and edit.

Extensions as packaged file

It is possible to package one or more extensions composed by one or more files (.js, .css, .qml and other files) in one single .sbaa Extensions file. See the Extensions Package documentation for more information.