Extension file Javascript

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

Javascript and Banana API

You can use any of the supported javascript functions, objects and properties see: Qt ECMAScript Reference.

Banana Accounting also make available the Banana API  that you can use to retrieve data or create report objects or else.

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 file structure

Extension files have two parts:

• Extension Attributes
  Apps Attributes are special formatted JavaScript comment lines, at the beginning of the file. The apps attributes have a left part (name of the attribute) and right part, with the value. Attributes give information about the script, like its purpose, description and so on. 
  • Required attributes are:
    • / @api = 1.0
    • // @id = ch.banana.apps.example.docfilepath
    • // @description = Hello world
    • // @task = app.command
    • // @doctype = nodocument
    • // @publisher = Banana.ch SA
    • // @pubdate = 2015-05-12
  • Include attribute
    The script can include other files with the attribute 
    • // @includejs = other.js
• JavaScript code
  The code must be included within functions. Functions are divided in startup functions, settings functions and normal functions.
  • Startup functions
    Are called by Banana software when the script is executed.
    The name of the function called depend on the type of the App.
    • exec() for following types:
      • app.command
      • export.file
      • export.rows
      • export.transactions
      • import.transactions
      • import.rows
      • import.accounts
      • import.categories
      • import.exchangerates
      • import.vatcodes
      • report.general
    • printDocument() for the following types:
      • report.customer.invoice
      • report.customer.statement
      • report.customer.reminder
  • settingsDialog() function 
    It is called by the Banana Software when the user click on the Setting button, relative to the specific app.
    The setting data is saved within the Accounting file.
    See: Extension's Settings.
  • Other JavaScript functions
    You can write any functions that is necessary.

Extension id file

The name of this extension must be unique and follow the next rules:

• The @id attribute is used to identify the script;
  It is also used by the help system, that open the help page in the browser.
• In order to avoid duplicates banana.ch use the following scheme: developer.country.type.name

For Invoices as 'name' we use the following scheme: country + number (numbers between 1 and 499):

• Example for Switzerland: ch01, ch02, ch03,...
• Example for all countries: uni01, uni02, uni03,...  

For Reminders as 'name' we use the following scheme: country + number (numbers between 500 and 599):

• Example for Switzerland: ch500, ch501, ch502,...
• Example for all countries: uni500, uni501, uni502,...  

For Statements as 'name' we use the following scheme: country + number (numbers starting from 600):

• Example for Switzerland: ch600, ch601, ch602,...
• Example for all countries: uni600, uni601, uni602,...  

Examples:

• @id = ch.banana.ch.invoice.ch01
• @id = ch.banana.uni.reminder.uni500
• @id = ch.banana.uni.invoice.companyxx
• @id = ch.banana.ch.app.vatreport2018

Example:

ch.banana.ch.extensionexample.js

Extensions types, startup functions and how to run them

The Extension type is defined within the attribute @task.
For each type there is a specific startup function. 

See: Exension's types.

The app.command is used for General extensions.

// @task = app.command

Include directive in JavaScript files 

JavaScript extension files can use the directive @includejs to include other JavaScript files or use the command . 
This included file need to be included in the package. Make sure that all included .js file are also specified in the qrc package description.

// Include a script via @includejs attribute
// @includejs = somescript.js"  
// Include a script via Banana.include() method
Banana.include(somescript.js);

Startup function exec([inData, options])

The functio exec() is required by most extensions and in particularly for the General Extensions.

The exec() funciton can have the following 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 settings and doesn't show a setting's dialog;
   

Return value 

The exec() function will return a null value or a string. 
For import script the format is defined by the attribute @outputformat.
For Productivity extensions it is a JSon document or an Error.

• tablewithheaders
  A tab separated text (csv) containing different columns.
  The first row is the table header.
• transactions.simple
  A tab separated text (csv) containing the movement of a account in the form of income and expenses.
• Empty type
  JSon document that contains documentchange data, that allow to add, modify and delete data within the tables.
  See:
  • Document Change API.
• @Error:
  It an error occurs the function can return a string that begins with "@Error:", for example "@Error:Invalid file format".
  The error text is then displayed to the user.

Extension package

The extension package file is used to easily distribute and pack one or more extensions and file together.

Once the extension are packaged they behave the same as one you access locally.

Embedded Extension

An embedded extension is a normal General extension file (app.command) that is saved in the Document table.

Install extensions

Extensions are usually installed manually in Menu Extension > Manage extensions.

Install the extension as a local extension.

In the Menu File > File Properties > Other you can specify extension to be installed automatically when the file is opened.

Extension's help and visibility

For marketplace application the Id of the extension is also used to provide context help to the documentation. 

Visibility in menu extension

General Extensions are usually visible in the Menu Extension, but the developer can limit the visibility by adding specific properties.

• The attribute @doctype of the file open should match the File that is open.
  • // @doctype = 100.110
  • The command would be visible only if the accounting file is of type "Double  entry with VAT".
• The File Properties > Other > Properties contains a property text that is defined in the property.
  By setting the @docproperties  in the attribute, an extension can restrict the visibility to only a file that  suitable.
• The @visibility attribute further allow to limit the visibility.

General Extensions that are part of a package will be visible and started within a Sub-Menu relative to the package. 
This way all extensions relative to the package will be grouped together.

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.

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
}