Dans cet article
Extensions are javascript compliant script files (ECMA-262). People knowing javascript can easily write an Extension.
Javascript and Banana API
You can use any of the supported javascript functions, objects and properties see: Qt ECMAScript Reference.
Banana Accounting also make available the Banana API that you can use to retrieve data or create report objects or else.
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 file structure
Extension files have two parts:
- Extension Attributes
Apps Attributes are special formatted JavaScript comment lines, at the beginning of the file. The apps attributes have a left part (name of the attribute) and right part, with the value. Attributes give information about the script, like its purpose, description and so on.- Required attributes are:
- / @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
- Include attribute
The script can include other files with the attribute- // @includejs = other.js
- Required attributes are:
- JavaScript code
The code must be included within functions. Functions are divided in startup functions, settings functions and normal functions.- Startup functions
Are called by Banana software when the script is executed.
The name of the function called depend on the type of the App.- exec() for following types:
- app.command
- export.file
- export.rows
- export.transactions
- import.transactions
- import.rows
- import.accounts
- import.categories
- import.exchangerates
- import.vatcodes
- report.general
- printDocument() for the following types:
- report.customer.invoice
- report.customer.statement
- report.customer.reminder
- exec() for following types:
- settingsDialog() function
It is called by the Banana Software when the user click on the Setting button, relative to the specific app.
The setting data is saved within the Accounting file.
See: Extension's Settings. - Other JavaScript functions
You can write any functions that is necessary.
- Startup functions
Extension id file
The name of this extension must be unique and follow the next rules:
- The @id attribute is used to identify the script;
It is also used by the help system, that open the help page in the browser. - In order to avoid duplicates banana.ch use the following scheme: developer.country.type.name
Value | Description | Example |
developer | The developer of the app. | ch.banana |
country | The country for which the app is designed. If the app is not designed for a specific country, use uni as universal. | ch, it, de, ... uni |
type | The type of the app. | app, import, invoice, reminder, statement |
name(*) | The name of the app. | vatreport, voucher,... |
For Invoices as 'name' we use the following scheme: country + number (numbers between 1 and 499):
- Example for Switzerland: ch01, ch02, ch03,...
- Example for all countries: uni01, uni02, uni03,...
For Reminders as 'name' we use the following scheme: country + number (numbers between 500 and 599):
- Example for Switzerland: ch500, ch501, ch502,...
- Example for all countries: uni500, uni501, uni502,...
For Statements as 'name' we use the following scheme: country + number (numbers starting from 600):
- Example for Switzerland: ch600, ch601, ch602,...
- Example for all countries: uni600, uni601, uni602,...
Examples:
- @id = ch.banana.ch.invoice.ch01
- @id = ch.banana.uni.reminder.uni500
- @id = ch.banana.uni.invoice.companyxx
- @id = ch.banana.ch.app.vatreport2018
Example:
ch.banana.ch.extensionexample.js
Extensions types, startup functions and how to run them
The Extension type is defined within the attribute @task.
For each type there is a specific startup function.
See: Exension's types.
The app.command is used for General extensions.
// @task = app.command
Include directive in JavaScript files
JavaScript extension files can use the directive @includejs to include other JavaScript files or use the command .
This included file need to be included in the package. Make sure that all included .js file are also specified in the qrc package description.
// Include a script via @includejs attribute // @includejs = somescript.js" // Include a script via Banana.include() method Banana.include(somescript.js);
Startup function exec([inData, options])
The functio exec() is required by most extensions and in particularly for the General Extensions.
The exec() funciton can have the following 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 settings and doesn't show a setting's dialog;
Return value
The exec() function will return a null value or a string.
For import script the format is defined by the attribute @outputformat.
For Productivity extensions it is a JSon document or an Error.
- tablewithheaders
A tab separated text (csv) containing different columns.
The first row is the table header. - transactions.simple
A tab separated text (csv) containing the movement of a account in the form of income and expenses. - Empty type
JSon document that contains documentchange data, that allow to add, modify and delete data within the tables.
See: - @Error:
It an error occurs the function can return a string that begins with "@Error:", for example "@Error:Invalid file format".
The error text is then displayed to the user.
Extension package
The extension package file is used to easily distribute and pack one or more extensions and file together.
Once the extension are packaged they behave the same as one you access locally.
Embedded Extension
An embedded extension is a normal General extension file (app.command) that is saved in the Document table.
Install extensions
Extensions are usually installed manually in Menu Extension > Manage extensions.
Install the extension as a local extension.
In the Menu File > File Properties > Other you can specify extension to be installed automatically when the file is opened.
Extension's help and visibility
For marketplace application the Id of the extension is also used to provide context help to the documentation.
Visibility in menu extension
General Extensions are usually visible in the Menu Extension, but the developer can limit the visibility by adding specific properties.
- The attribute @doctype of the file open should match the File that is open.
- // @doctype = 100.110
- The command would be visible only if the accounting file is of type "Double entry with VAT".
- The File Properties > Other > Properties contains a property text that is defined in the property.
By setting the @docproperties in the attribute, an extension can restrict the visibility to only a file that suitable. - The @visibility attribute further allow to limit the visibility.
General Extensions that are part of a package will be visible and started within a Sub-Menu relative to the package.
This way all extensions relative to the package will be grouped together.
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.
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
}