Apps Attributes

At the beginning at the script there should be a part that define the Apps Attribute.

// @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
// @inputdatasource = none
// @timeout = -1

The attribute is a commented text line

  • Sart with //
  • Followed by the attribute that start with @
  • Fossowed by the " = " and the value

Tags defines the purpose (import, export, extract, ...), the name displayed in the dialogs, the kind of data it expect to receive, the kind of data it returns, and other information of the script. Tags are inserted at the beginning of the script in comment's lines though the following syntax: "// @tag-name = tag-value".

Attribute list

Attribute name Required

Value 1)

Description
@api Required

The required API version.

Available API versions:
1.0

Define the required API to be executed in the form of MAIN_VERSION.SUB_VERSION

The implemented API in the application have to be equal or newer.

@contributors   List of contributors separated by ';' This attribute contains the list of people that contribute to the developping of the BananaApp.
@description[.lang] Required The name or description of the script

This text will be displayed in the dialogs.

This tag is localisable.

@docproperties   any text Define a property the script is writen for.
With this attribute you can manually select for what document the script is visbile in the menu Add-ons and can be run. The property can be added to the document though the dialog Add-Ons.
The property can be any text (ex.: "datev", "realestate", ...). Mulitple properties can be defined wiht a ';' as separator (ex.: "datev;skr03").
@doctype Required nodocument
*
XXX.*
XXX.YYY
!XXX.YYY
...

Define the type of document the script is writen for.
With this attribute you can define for what type of document the script is visbile in the menu Add-ons and can be run.

nodocument = doesn't require an open document, the add-on is always visible
* = for any type of document, always visible if a document is open
*.*  = for any type of document, always visible if a document is open
100.* = for Double entry accountings
110.* = for Income & Expenses accountings
130.* = for Cash Books
400.* = for Addresses and Labels
100.100 = for accountings without VAT and without foreign currrencies
100.110 = for accountings wiht VAT
100.120 = for accountings with foreing currencies
100.130 = for accountings with VAT and foreign currencies

The sign ! is used to invert the definition.

The above codes can be combined togheter like the following examples:

100.130 = for double entries with VAT and with foreign currencies
100.120;100.130 = for double entry with foreign currencies
100.*;110.*;130.* = for all accounting files
!130.* = for any filesexcept cash books
@exportfilename   A string defining the name of the file where to export the data. If the string contains the text <Date>, it will be replaced by the current date in the format of yyyyMMdd-hhmm.
@exportfiletype  

A string defining the type of data exported

txt
...
This parameter is used for export scripts, it defines the type of exported data and it is used for the extension in the save file dialog.
@id Required An identification of the script It is used when setting and reading the preferences.
In order to avoid duplicate banana.ch use the following scheme.
country.developper.app.domain.name
for example:
ch.banana.app.patriziato.consuntivopersubtotali
@includejs   Relative path to a javascript .js file to load before the execution of the script. Include the javascript file. Every function and object defined in the file are then available to the current script.
@inputdatasource   One of the following values:
none
openfiledialog
fixedfilepath 2)
With this attribute you can specify if you don't need to input data, if you want the user to select a file to import (openfiledialog), or if you want to get a file which path is defined in @inputfilepath. If you set fixedfilepath the program will ask the user the permission to open this file, the user's answer will be saved for the next execution.
@inputencoding  

The encoding of the input data.

One of the following values:
latin1
utf-8
iso 8859-1 to 10
...

The encoding used to read the input file (for import apps).

If the attribute is empty or not defined, the application try to decode the input data with utf-8, if it fails, the application decode the input data with latin1.

For a complete list see QTextCodec

@inputfilefilter[.lang]  

The file filter for the open file dialog

Ex.: Text files (*.txt *.csv);;All files (*.*)

This value describes the file filters you want to show in the input file dialog. If you need multiple filters, separate them with ';;' for instance.

This tag is localizable.

@inputfilepath   The file to read for the input data If the script has the value fixedfilepath as @inputdatasource, you can define here the path of the file to load.
@inputformat   One of the following values:
text
ac2
If "text" the filter receive the selected file in inData as a text. If "ac2" the filter receive the selected file in inData as a Banana.Document object.
@outputencoding  

The encoding of the input data.

One of the following values:
latin1
utf-8
iso 8859-1 to 10

The encoding used to write the output file (for export apps).

For a complete list see QTextCodec

@outputformat   One of the follwing values:
tablewithheaders
transactions.simple
If the script has an import tasks this value define the format of the returned value. The format transaction.simple contains the transaction as income / expenses. For details of the formats see Import data from a txt file.
@pubdate Required The publication date in the format YYYY-MM-DD This publication date is also used for scripts published by Banana.ch to check if newer version exist.
@publisher   The publisher of the script  
@task Required

One of following values:
app.command
export.file
export.rows
export.transactions
import.rows
import.transactions
import.accounts
import.categories
import.exchangerates
import.vatcodes
report.general
report.customer.invoice
report.customer.statement
report.customer.reminder

This value define the purpouse of the script, and determine in which dialog or menu the script is visible.

@testapp   Path and name of the test app. Default is './test/<bananaapp_name>.test.js

This can be used if there is a test app and the path to the test app is different to the default path.

Since Banana 9.0.4

@testappversionmin
@testappversionmax
  Only for test cases. Minimum and mximum application's version to whitch the test is applicable.  
@timeout   The timeout for the script in milliseconds, default is 2000 (2 seconds). If you set -1 the timeout is disabled and the application allow you to abort it though a progress bar. If the script takes longer than this value to finish, it will be aborted and a message showed. If you have a script with a very long run time, you can increase the timeout or set it to -1.

1) Default values are listed in bold.

2) Function not yet available

 

Example:

// @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
// @inputdatasource = none
// @timeout = -1

/**
 * Hello world example for Banana Accounting.
 */
function exec(inData) {
    Banana.Ui.showInformation("", "Hello World");
    
    if (Banana.document) {
       var fileName = Banana.document.info("Base","FileName");
       Banana.Ui.showInformation("Current document", fileName);
    }
}

 

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 | Email