App File

This documentation is outdated

The most complete and up-to-date documentation is the one of Banana Accounting Plus: Try it now

In this article

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() function 
    The function exec() is the function that is called every time a BananaApps is executed.
    It has one argument, the requested input data as a string or a Banana.Document object.
    It return the result as a string.
    The format of the returned string match the format defined by the tag @outputformat. Errors are notified through exceptions (clause throw), or just by returning a string beginning with "@Error:"

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 = Account balance for all days in a month 
// @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);
}

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.

BananaApps file extention '.sbaa'

Since Banana Experimental 8.0.4.170127 the extention for BananaApps is '.sbaa'.

A .sbaa file can be either a text file containing java script code or a packaged qt resource file. The application determine automatically the type of the file. When Banana load a packaged .sbaa file, a file that can contains several apps, it look 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 Apps menu.

Note: for previous versions than 8.0.4.170127 the extentions were .js for single file apps and .rcc for packaged apps.

BananaApps as a single javascript file

The script is all included in a file.

  • BananaApp are saved in in UTF-8 file without BOOM.
  • Prior to run the BananaApp you need to install it through the Manage Apps command or by drag and drop.

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. This is very practical for distributing Apps composed by two or more files, or packages with two or mores BananaApps.

When Banana load a packaged .sbaa file, it look 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.

Files in packages can include other 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);

To create a packaged file edit a .qrc file and open it in Banana via the File Open command or drag and drop. The application will compile the qrc file and create a corresponding single .sbaa file.

It is also possibile to create package files with the 'rcc' tool from the Qt Resource system.

  • Install the Qt Sdk
     
  • Create a .qrc file with the list of the files to be included

    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>
 </qresource>
 </RCC>
  • Compile the .qrc file
rcc -binary ch.banana.script.report.jaml.qrc -o ch.banana.script.report.jaml.rcc

Install BananaApps

Banana App can be installed with the Manage Apps command or by drag and drop in Banana windows.

Embedded BananaApps in documents

In the table Documents you can add script file.
On the BananaApps tutorial you will find different basic examples embedded in a document that you can run and edit.

Best way to distribute the App

  • Single App file (Script file)
    • Easier to edit, 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 update
  • Packaged App file
    • Same as Script file but cannot be easily changed
    • Protected from user modification

 

 

 

 

Share this article: Twitter | Facebook | LinkedIn | Email