Extension's Attributes

Documentation •
In this article

At the beginning at the script there should be a part that define the Extension's Attribute (See Extension File Structure).

// @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

  • Start with //
  • Followed by the attribute that start with @
  • Followed 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 nameRequiredValue 1)Description
@apiRequired

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.

See the page API Versions for a list of implemented versions, and the Changelog page for the list of changes in the API.

@contributors List of contributors separated by ';'This attribute contains the list of people that contribute to the developing of the Banana Extensions.
@description[.lang]RequiredThe name or description of the script

This text will be displayed in the dialogs.

This tag is localizable.

@docproperties any text

Define a property the script is written for.
The commands of the extension will the be added to the menu Extensions only if the property mach the one present the file properties keywords.

  • The property can be any text (ex.: "datev", "realestate", ...).
  • Multiple properties can be defined with a ';' as separator (ex.: "datev;skr03").

It works in combination of the @docproperties and @visibility

@doctypeRequirednodocument
*
XXX.*
XXX.YYY
!XXX.YYY
...

Define the type of document the script is written for.
The commands of the extension will the be added to the menu Extensions only if the document is of the specified type.
It works in combination of the @doctype and @visibility

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.* = Double entry accounting
100.100 = Double  entry without VAT and without foreign currencies
100.110 = Double  entry with VAT
100.120 = Double  entry with foreign currencies
100.130 = Double  entry with VAT and foreign currencies


110.* = for Income & Expenses accounting
130.* = for Cash Books

300.* = All productivities App
400.100 = Simple Table
400.100 = Simple Table
400.120 = Addresses and Labels
400.140 = Library and collections
400.150 = Fixed Assets Register
400.300 = Tutorial maker
400.400= Estimates and Invoices files
400.500 = Inventory
400.600 = Timesheet

The sign "!"  before the file type of the file will exclude the indicate type.

The above codes can be combined together 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 files except 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.
@idRequiredAn identification of the scriptIt 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.

The application searches for include files in this order:

  1. In the same directory as the file that contains the @include attribute.
  2. In the directories of the currently opened include files, in the reverse order in which they were opened. 

Each distinct included script is evaluated once, even if it is included more than one time from different scripts.

@inputdatasource One of the following values:
none
openfiledialog
opendirdialog
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), a directory to import (opendirdialog), 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 dataIf 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.
@pubdateRequiredThe publication date in the format YYYY-MM-DDThis publication date is also used for scripts published by Banana.ch to check if newer version exist.
@publisher The publisher of the script 
@taskRequiredOne of following values:
accounting.payment
app.command
create.init
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 purpuse of the script, and determine in which dialog or menu the script is visible.

@testapp Path and name of the test(s) app. The path can be relative or absolute, contains wildcards or be a list of files separated by ';'. 

Default is './test/*.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.

If the path is not in the script's folder, a confirmation dialog is showed to the user before running the tests.

Since Banana 9.0.4
Since Banana 10.1.13: list of paths and wildcards

@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.
@visibility always
never
extensionlinked

Define if the extension will be added to the menu Extensions.
It works in combination of the @docproperties and @doctype

  • always = the commands of the extension will be added to the menu Extensions
  • never = the commands of the extension won't appear in the menu Extensions
  • extensionlinked= the commands of the extension will be added to the menu Extensions only if the script is linked in the file and accounting properties

from version 10.0.7

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