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

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);
    }
}

You can create extensions that use external files. In this page we explain how to use an external css file in order to print the report. With this you can avoid to use javascript to set the style attributes.

As with Javascript, CSS is also limited to the attributes listed on the page Banana.Report.ReportStyle.

What do you need:

• The extension script (file .js).
• The CSS stylesheet (file .css).
• Create a package (file .sbaa)

Extension script (file .js)

In your extension javascript file:

• Take the external CSS stylesheet file with getLocalFile(path).
• Read and take the content with read().
• Parse the content in order to load the styles with parse(text).

var textCSS = "";
var file = Banana.IO.getLocalFile("file:script/yourFile.css");
var fileContent = file.read();
if (!file.errorString) {
  Banana.IO.openPath(fileContent);
  textCSS = fileContent;
} else {
  Banana.console.log(file.errorString);
}

// New stylesheet
var stylesheet = Banana.Report.newStyleSheet();

// Parse the CSS text
stylesheet.parse(textCSS);

CSS stylesheet (file .css)

In your css stylesheet file:

• Insert the text following the CSS specification.

@page {
  margin-top: 10mm;
  margin-bottom: 10mm;
  margin-left: 20mm;
  margin-right: 10mm;
}
body {
  font-family: Helvetica;
  font-size: 10pt;
}
table {
  font-size: 8px;
  width: 100%;
}
table.table td {
  border-top-style: solid;
  border-top-color: black;
  border-top-width: thin;
  border-bottom-style: solid;
  border-bottom-color: black;
  border-bottom-width: thin;
  border-left-style: solid;
  border-left-color: black;
  border-left-width: thin;
  border-right-style: solid;
  border-right-color: black;
  border-right-width: thin;
}
.column1 {
  width: 73%;
}
.column2 {
  width: 13%;
}
.column3 {
  width: 13%;
}
.table-header {
  color: #ffffff;
  background-color: #337ab7;
  font-weight: bold;
  text-align: right;
}
.amount-totals {
  background-color: #F0F8FF;
  text-align: right;
  font-weight: bold;
}

Extension package (file .sbaa)

Now generate the Extension Package file (.sbaa) containing:

• The javascript file.
• The CSS file.

To do that:

• Create the manifest file (.json) in the same directory of the javascript and css files.

  {
      "category": "productivity",
      "country":"switzerland",
      "countryCode":"ch",
      "description": "Extension with css",
      "description.en": "Extension with css",
      "language":"en",
      "publisher": "Banana.ch",
      "title": "Extension with css",
      "title.en": "Extension with css",
      "version": "1.0"
  }

• Create the Qrc resource file (.qrc) in the same directory of the javascript and css files.
   

  <!DOCTYPE RCC><RCC version="1.0">
  <qresource>
       <file>yourJavascriptFile.js</file>
       <file>yourCssFile.css</file>
       <file>manifest.json</file>
  </qresource>
  </RCC>

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

Define CSS file in Documents table

You can write the CSS code directly in the documents table and access the data via javascript as shown in the example

/**
 * CSS file defined in Documents table.
 */
if (userParam.embedded_css_filename) {
  var cssFiles = [];
  var documentsTable = Banana.document.table("Documents");
  if (documentsTable) {
    for (var i = 0; i < documentsTable.rowCount; i++) {
      var tRow = documentsTable.row(i);
      var id = tRow.value("RowId");
      if (id === userParam.embedded_css_filename) {
        // The CSS file name entered by user exists on Documents table so it can be used as CSS
        textCSS += documentsTable.findRowByValue("RowId",userParam.embedded_css_filename).value("Attachments");       
      }
    }
    // Parse the CSS text
    repStyleObj.parse(textCSS);
  }
}

In this example:

• userParam
  An object containing different parameters user can define with the Dialog PropertyEditor.
• embedded_css_filename
  A the parameter where user enter the file name of the embedded css file saved in the Documents table. The file name is the content of the column Id (e.g. "myStyle.css").

Extensions settings allow to customize the Extension, for example:

• Setting for the printing.
• Header of a report that are set once only.

Function settingsDialog() 

If you provide customization you should add a function settingDialog(). 
This function will called:

• When the user click on the Set Parameters on the Manage Extensions dialog.
• For Import extension in the Dialog Import > Button Settings.
• For Report extensions in the Printing Dialog > Button Settings.

Take care that: 

• The extension is responsible to manage to load and save the settings.
• Return  value.
  • null if the user ha clicked on cancel button.
  • any other value if the user has changed the settings.

A simple and powerful way to let the user customize the setting is by using the:

• Extensions Dialog PropertyEditor

Saving the settings

The function settingDialog() should:

1. Read the existing setting with the Banana.document.getScriptSettings();
2. Request user to enter the information
3. Set the modified values with the function Banana.document.setScriptSettings(paramToString);
   The JSon text will be saved within the accounting file.
    

function settingsDialog() {
   var param = initParam();
   var savedParam = Banana.document.getScriptSettings();
   if (savedParam.length > 0) {
      param = JSON.parse(savedParam);
   }   
   param = verifyParam(param);
   
   param.isr_bank_name = Banana.Ui.getText('Settings', texts.param_isr_bank_name, param.isr_bank_name);
   if (param.isr_bank_name === undefined)
      return;
   var paramToString = JSON.stringify(param);
   Banana.document.setScriptSettings(paramToString);
}

Reading the settings

the function Exec() or any other function should then read the settings using the Banana.document.getScriptSettings().

Before using the setting you should check that they are valid and possibly provide a function that verify and eventually update the settings. 

function printDocument(jsonInvoice, repDocObj, repStyleObj) {
  var param = initParam();
  var savedParam = Banana.document.getScriptSettings();
  if (savedParam.length > 0) {
    param = JSON.parse(savedParam);
    param = verifyParam(param);
  }
  printInvoice(jsonInvoice, repDocObj, repStyleObj, param);
}

Sharing the setting with other extensions

The function Banana.document.setScriptSettings(paramToString); will save the setting in the accounting file under the Id of the extension.

If you need to share the settings with other extensions, like in case of a series of packaged extensions you should use the Banana.document.setScriptSettings((id, value). 

And to read the setting use Banana.document.getScriptSettings((id).

For more information siee Banana.document.

Example:

// Save script settings
var paramString = JSON.stringify(param);
var value = Banana.document.setScriptSettings('ch.banana.vat', paramString);

With BananaPlus you can provide translations to your extensions in a very simple and straightforward way. After you make the extension ready to be translated, adding a new language is as simple as adding a file to the package, without the need to change the source code.

Make an extension translatable

To make an extension translatable you need to:

1. Install CMake, Visual Studio code and setup your development environment
2. Mark strings for translation with the functions qsTr() or QT_TRANSLATE_NOOP() in *.js and *.qml files;
3. Add a CMakeLists.txt file to your project and modify it;
4. Translate strings with QtLinguist;
5. Add the translations files *.qm in the resource file *.qrc;
6. Build and deploy the extension's package;

You find a working complete example with the code described in this page on our GitHub Repository at:  Sample extension for string translations

Limitations:

• JS and QML files can not contains a dot '.' in the file name: for example my.extention.js is no valid, but my_extension.js is valid;
• JS and QML files can not be renamed via the property Alias in resource files (*.qrc), for example from my.extention.js to my_extention.js or main.js;
• Translations files (*.qm) have to be found under the subfolder /translations;

Setup development environment

Follow the steps on the page setup your development environment.

Mark strings for translation

Strings to be translated have to be marked in .js or .qml files using the function qsTr() or QT_TRANSLATE_NOOP().

Strings marked for translations are extracted from .js and .qml files and inserted in translation's files *.ts. Translations files are created and compiled with Qt Creator and the translations done with Qt Linguist.

 Function qsTR()

With the function qsTr() you mark strings to be translated in the application's language. Those  are usually texts showed in the user interface (dialogs, messages, ...).

Example:

var translatedText = qsTr("Account card"); 
// The variabile translatedText contains the translated string "Account card" 
// in the application's language

 Function QT_TRANSLATE_NOOP()

With the function QT_TRANSLATE_NOOP() you mark strings to be translated in the document language. Those are usually texts printed in reports or invoices.

Those translation are retrieved through the API Banana.Translations.

Example:

// Exemple for function QT_TRANSLATE_NOOP
var myReportTexts = {};
myReportTexts.account_card = QT_TRANSLATE_NOOP("MyReport", "Account card"); // Mark text for translation
// NB: The variable myReportTexts.account_card contains the source code string "Account card"
// You need a Banana.Translator object to translate it in the desired language
// Get translator for the document's language
var documentLanguage = "en";  //default
if (Banana.document) {
    documentLanguage = Banana.document.locale.substring(0,2);
}
var docTranslator = Banana.Translations.getTranslator(documentLanguage, "MyReport");
// Translate to the document's language
var myReportTranslatedText = docTranslator.tr(myReportTexts.account_card);

Add a CMake project file

A CMakeLists.txt project file is needed to extract all strings marked for translation from .js and .qml files and build the .sbaa extension's package.

Below is a template of a project file for translating an extension, you can copy it and modify it:

• copy the example and save it as CMakeLists.txt in your project folder;
• rename the project name translations_project to your desired name;
• renane the extension id ch.banana.translations to your desired id; 
• add the desired languages under the variable translations_files;
• add source files as needed to the main target; 

cmake_minimum_required(VERSION 3.16)
project(translations_project)                      # <!-- CHANGE THE PROJECT'S NAME
set(EXTENSION_ID "ch.banana.translations")         # <!-- CHANGE THE EXTENSION'S ID
# CMake options
# Create a file .vscode/settings.json with the following content to set the options, 
# adapt the path to your environment
# {
#     "cmake.configureSettings": {
#         "BAN_QT_RCC": "C:\users\user_name\AppData\Local\Programs\BananaPlusDev\rcc.exe",
#         "BAN_EXE_PATH": "C:\users\user_name\AppData\Local\Programs\BananaPlusDev\BananaPlusDev.exe",
#         "BAN_QT_LUPDATE": "C:\Qt\6.5.2\macos\bin\lupdate",
#         "BAN_QT_LRELEASE": "C:\Qt\6.5.2\macos\bin\lrelease"
#     }
# }
set(BAN_QT_RCC $ENV{BAN_QT_RCC} CACHE FILEPATH "Path to Qt rcc executable")
set(BAN_EXE_PATH $ENV{BAN_EXE_PATH} CACHE FILEPATH "Path to BananaPlus executable, used to run tests")
set(BAN_QT_LUPDATE $ENV{BAN_QT_LUPDATE} CACHE FILEPATH "Path to Qt lupdate executable")
set(BAN_QT_LRELEASE $ENV{BAN_QT_LRELEASE} CACHE FILEPATH "Path to Qt lrelease executable")
# This target is used to build the extension to a sbaa package
add_custom_target(translations_project ALL         # <!-- CHANGE THE PROJECT'S NAME
   COMMAND ${BAN_QT_RCC} -o ${EXTENSION_ID}.sbaa --binary ${EXTENSION_ID}.qrc
   WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
   SOURCES ${EXTENSION_ID}.qrc
)
add_dependencies(${PROJECT_NAME} lrelease) #build .qm files when building the sbaa package
# The variable translations_files contains the list of translations files
set(translations_files
   translations/translations_de.ts
   translations/translations_it.ts
   translations/translations_fr.ts
   #translations/translations_xx.ts               # <!-- ADD LANGUAGES AS NEEDED
)
# The target lupdate is used to update *.ts translations files
set(lupdate_commands)
foreach(tr_file ${translations_files})
 list(APPEND lupdate_commands
   COMMAND ${BAN_QT_LUPDATE} ${EXTENSION_ID}.qrc -ts ${tr_file})
endforeach()
add_custom_target(lupdate
   ${lupdate_commands}
   WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)
# The target lrelease is used to compile *.ts files to *.qm files
set(lrelease_commands)
set(lrelease_files)
string(REPLACE ".ts" "" lrelease_files "${translations_files}") #remove file extension
foreach(tr_file ${lrelease_files})
 list(APPEND lrelease_commands
     COMMAND ${BAN_QT_LRELEASE} ${tr_file}.ts -qm ${tr_file}.qm)
endforeach()
add_custom_target(lrelease
   ${lrelease_commands}
   WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)

Set Cmake options

Create the file .vscode/settings.json and set the following options:

• BAN_QT_RCC: path to the Qt rcc tool. The rcc Tool is used to compile the extension to a sbaa package.
• BAN_EXE_ PATH: path to the BananaPlus executable. The BananaPlus executable is used to run the tests defined in the project.
• BAN_QT_LUPDATE: path to the Qt lupdate tool. The lupdate tool is used to update the translations, it will search for text to translate in the code and update the content of *.ts files. If you don't have translations, this options is not necessary.
• BAN_QT_RELEASE: path to the Qt lrealease tool. The lrelease tool is used to compile the translations, the compiled translation are integrated in the package.If you don't have translations, this options is not necessary.

{
   "cmake.configureSettings": {
       "BAN_QT_RCC": "C:\Programms\BananaPlusDev\rcc.exe",
       "BAN_EXE_PATH": "C:\Programms\BananaPlusDev\BananaPlusDev.exe",
       "BAN_QT_LUPDATE": "C:\Qt\6.5.2\macos\bin\lupdate",
       "BAN_QT_LRELEASE": "C:\Qt\6.5.2\macos\bin\lrelease"
   }
}

Translate strings

1. Create a folder /translations in your repository;
2. Open the CMakeLists.txt project file with QtCreator;
3. Build in QtCreator the target lupdate (figure 1);
4. Open the generated translations/*.ts files with QtLinguist and enter the translations (figure 2)

Keep the generated translations/*.ts files in the repository, as they are needed for updating the translations after one or more strings are changed or modified in the code.

Add translations to resource file

Add the *.qm files to the resource *.qrc file.

<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/">
<file>manifest.json</file>
<file>translations/translations_de.qm</file>
<file>translations/translations_fr.qm</file>
<file>translations/translations_it.qm</file>
</qresource>
</RCC>

Build and deploy

1. Build the extension;
2. The translations files *.qm are automatically released and included in the package;
3. Copy the generated *.sbaa file to the destination folder;
4. Add the extension in Banana AccountingPlus (see installing an'extension);
5. Test it;

Implementation details

Loading of translation's files

Translations are automatically loaded by the application.

Translations are provided as *.qm binary files located in the extension's subfolder /translations.

sample_extention.js          // extension
translations/
   translations_de.qm.       // translation's files
   translations_it_CH.qm
   translations_it.qm
   ...

Translations files have the following naming convention:

   translations_lang[_country].qm

Before the execution of the extension the application loads the translation corresponding to the application's language and country. For example if the application has the locale fr_FR the application looks for the following files, the first file found is taken.

   translations_fr_FR.qm
   translations_fr.qm​​​