You are here

App File

Javascript compliant script

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

A BananaApp file contains the following two sections:

  • Apps'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 a BananaApps 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.

BananaApps 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.

BananaApp "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 BananaApps 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);
}

BananaApp with a setting's dialog example

Here an example that use a dialog to input a text. Other examples are found in the BananaApps 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
}

BananaApps have a strong Security model

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

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

To accesso 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 BananaApp

  • 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.

BananaApps as a single javascript file

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

This is how it works:

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

Embedded BananaApps in documents

Banana allows to have BananaApps 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 BananaApps you can add script files in the table Documents.

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

BananaApps 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 BananaApp file (see documentation below).

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

This is how it works:

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

BananaApps 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

 

 

Share this article: Twitter | Facebook | Email


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.