Extension File

In this article

Javascript compliant script

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

Am Extension file contains the following two sections:

  • Extension's attributes
    The apps's 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 Apps.
    • Can be used by different accounting file.
  • Embedded apps
    • Not available in the menu Apps.
    • 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 Apps.
    • 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 Apps command.
  • Once the Extension is installed, it appears in the menu Apps.
  • The Extension can be run from the menu Apps.

Embedded Extension in documents

Banana allows to have Extensions that are embedded within a Banana File. Embedded apps 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 apps composed by one or more files (.js, .qml and other files) in one single .sbaa Extensions file (see documentation below).

It's very practical for distributing Apps composed by two or more files, or packages with two or more Extensions.

This is how it works:

  • The .sbaa Extension needs to be installed through the Manage Apps command.
  • Once the Extensions is installed, it appears in the menu Apps.
  • The Extension can be run from the menu Apps.

Extensions file extention '.sbaa'

A .sbaa file can be either a text file containing javascript code (.js files) or a packaged qt resource file (.sbaa). The application determine automatically the type of the file. 

When Banana loads a packaged .sbaa file, it looks for all .js files contained in the package that have an attribute section. Those files are readen and a corresponding entry is inserted in the menu Apps.

Javascript files in packages can include other javascript files in the same package using the directive @includejs or the method  Banana.include(fileName). It is not possibile to include files outside the package.

// Include a script via @includejs attribute
// @includejs = somescript.js"  

// Include a script via Banana.include() method
Banana.include(somescript.js);

Here  is how to create a packaged .sbaa file:

  • Create a manifest.json file with the information regarding the package
  • Create a .qrc file with the list of the files to be included.
  • It is also possibile to create package files with the 'rcc' tool from the QT (see below)
  • Open Banana Accounting
  • Drag the .qrc file in Banana Accounting.
  • It will ask you if you want to compile the file and will generate a .sbaa file.

Qrc resource file (.qrc)

For more information see the Qt Resource system.

Example: ch.banana.script.report.jaml.qrc

<!DOCTYPE RCC><RCC version="1.0">
<qresource>
     <file>ch.banana.script.report.jaml.js</file>
     <file>lib/jaml-all.js</file>
     <file>manifest.json</file>
</qresource>
</RCC>

Qrc file file can also be compiled with the QT

rcc -binary ch.banana.script.report.jaml.qrc -o ch.banana.script.report.jaml.rcc

Manifest file

If you create a .sbaa file, also include a manifest file. The manifest.json file is a JSON-formatted file, which you can include in the .sbaa file through the .qrc file.
Using manifest.json, you specify basic metadata about your package such as the title, description and version.
The file name must end with the extension 'manifest.json'

Example: ch.banana.script.report.vat-ch.qrc

<!DOCTYPE RCC><RCC version="1.0">
<qresource>
     <file alias="manifest.json">ch.banana.script.report.vat-ch.manifest.json</file>
     <file>ch.banana.script.report.vat-ch.js</file>
</qresource>
</RCC>

Example: ch.banana.script.report.vat-ch.manifest.json

{
    "category": "productivity",
    "country":"switzerland",
    "countryCode":"ch",
    "description": "Postfinance Schweiz (Bewegungen importieren): ISO20022 und CSV Format",
    "description.en": "Swiss Postfinance (Import transactions): ISO20022 and CSV File Format",
    "language":"de",
    "publisher": "Banana.ch",
    "title": "Postfinance Schweiz (Bewegungen importieren)",
    "title.en": "Swiss Postfinance (Import transactions)",
    "version": "1.0"
}
  • Available categories: export, import, invoice, invoice reminder, invoice statement, productivity. 
    If you don't specify the category ("category": ""), the program will take the category from the first app included in the package. If you don't specify country or language, the app will be shown for any country or language.
  • All tags are optional

 

 

Help us improve the documentation

We welcome feedback on how to improve this page.

Tell us what theme needs a better explanation or how to clarify a topic.

Share this article: Twitter | Facebook | LinkedIn | Email