Multiple File Based Extension

This walk-through explains how to create an extension that uses the JavaScript API to interact with Banana Accounting software. The extension can consist of several JavaScript files and, optionally, CSS files, all stored locally on your computer, without the need to build an .sbaa package.

It provides a middle ground between:

• the Single File Based Extension, which consists of a single .js file;
• the Package Extension, which requires Visual Studio Code, CMake, and compiling an .sbaa package for distribution.

This approach is useful when you are developing an extension that spans multiple files, for example to keep the code organized, reuse shared libraries, or separate CSS styling from the application logic, but you do not yet need to distribute or share it with other users.

As long as the extension remains on your computer, you do not need to create a .sbaa package. You only need to install in Banana the main JavaScript file, the one that contains the exec() function.

When to use this approach

• Use this approach when you are developing a personal or internal extension that will be used only on your computer.
• It is also a good choice when you want to split the code into multiple files to keep it organized, for example by separating the application logic, templates, and styling.
• You can also use it when you do not yet need to distribute or share the extension with other users.

File structure

Unlike a Single File Extension, this approach uses multiple files, all stored in the same folder:

myExtension/
├── myextension.js   	← main file, contains exec()
├── lib/
│   └── utils.js        ← file included with @includejs
└── style/
   └── report.css       ← CSS file included at runtime

Important: all files must remain in the same folder as the main file, or in one of its subfolders. They must not be moved, because the paths used in the include statements are relative to the location of the main file.

1. Create the JavaScript files

Main file

The main file is the one that will be installed in Banana and that contains the exec() function. In its initial attributes the @includejs attribute is used to indicate the other JavaScript files that are needed:

// @id = myextension
// @api = 1.0
// @pubdate = 2026-01-01
// @publisher = My name
// @description = Multiple file extension example
// @task = app.command
// @doctype = *.*
// @timeout = -1
// @includejs = lib/utils.js

function exec() {
   // The greet() function is defined in the included file lib/utils.js
   var message = greet("World");

   var report = Banana.Report.newReport("Report title");
   report.addParagraph(message);

   var stylesheet = Banana.Report.newStyleSheet();
   Banana.Report.preview(report, stylesheet);
}

You can add several @includejs lines, one for each file to be included:

// @includejs = lib/utils.js
// @includejs = lib/helpers.js

Included files

The included file (lib/utils.js) simply contains the functions or classes needed by the main file, with no attributes of its own:

function greet(name) {
   return "Hello " + name + "!";
}

As an alternative to the @includejs attribute (which is evaluated when the script starts), a file can also be included dynamically, at any point in the code, using the Banana.include() method:

Banana.include("lib/utils.js");  //a js file in a subfolder

2. Include a CSS file

Unlike JavaScript files, CSS files are not declared in the attributes; instead, they need to be read and applied at runtime inside the exec() function, using Banana.IO.getLocalFile():

function exec() {
   var report = Banana.Report.newReport("Report title");
   report.addParagraph("Hello World!", "title");

   var stylesheet = Banana.Report.newStyleSheet();

   // Read the CSS file in the "style" subfolder
   var file = Banana.IO.getLocalFile("file:script/style/report.css");
   var cssText = file.read();

   if (!file.errorString) {
      stylesheet.parse(cssText);
   } else {
      Banana.console.log(file.errorString);
   }

   Banana.Report.preview(report, stylesheet);
}

The CSS file contains the styles supported by the Banana.Report.ReportStyle objects:

/* style/report.css */
.title {
   font-weight: bold;
   font-size: 14pt;
}

3. Install the extension

You only install the main file:

• Open an accounting file in Banana Accounting.
• From the menu Extensions select Manage Extensions.
• Click on Add from file... and select the main file (myextension.js).
• Click on Open to install it.

Banana will automatically load, through the @includejs attributes (or the Banana.include() calls), all the linked files found in the same folder.

Important

• All files (main and included) must stay in the same relative location on disk. If you move or rename an included file, the extension will no longer be able to find it.
• If you modify any of the files, Banana will always use the latest saved version the next time the extension is run.

4. Run the extension

As with the Single File Extension, from the menu Extensions select the entry corresponding to the @description of the main file to run it.