Extensions as packaged file and project

This page gives a brief introduction of what CMake is and its implications with the Banana Plus software, beyond that it is explained how the project must be structured and how the files must be configured.

The chapters are:

• Extension Package Definition file (qrc file).
• Extension distribution package .sbaa.
• The reference of: How to generate the package file.
• The reference of:  Installing and running the extension.
• Extension Project structure.
• Multiple extensions in the same package.
• The reference of: Unpack the package file.

Extension Package Definition file (qrc file)

The Definition file is a qrc file with a syntax of the Resource Collection Files (QRC) from the Qt Resource system. 
The qrc file is an xml that list the content of the packaged file.

The rcc compiler will then read the qrc and compress and package the content in a sbaa file. 

Example: ch.banana.script.report.jaml.qrc

<!DOCTYPE RCC><RCC version="1.0">
<qresource>
     <file>manifest.json</file>
     <file>ch.banana.script.report.jaml.js</file>
     <file>lib/jaml-all.js</file>
</qresource>
</RCC>

Minimum content of the qrc file

The Banana Extension Package should contains: 

• A manifest file (see below).
  The manifest contains metadata relative to the package, like name, publisher. 
• A valid javascript extension file. 

Other content of qrc file

• Other javascript files (.js) used by the extension.
• Other javascript extension file. 
  A single package can contains several extensions, also of different type.
  The package could contains one or more report extensions, import extensions and a general extensions.
• stylesheets files (.css).
• image files (.png, or .jpg).
• qml files
• any other files you need for your extensions.

Alias keyword

If you want to name the manifest file in another way you can use the alias keyword, so that the program will find a manifest.json file. 
The alias is necessary when you create multiple packages and the files are in the same folder, so you need to have different manifest.json.  

<!DOCTYPE RCC><RCC version="1.0">
<qresource>
    <file alias="manifest.json">ch.banana.script.report.vat-ch.manifest.json</file>
    <file>ch.banana.script.report.vat-ch.js</file>
</qresource>
</RCC>

Extension distribution package .sbaa

In order to distribute the extension you need to compile the qrc extension file to a .sbaa file.

• To compile the qrc file the rcc utility is used.
• The rcc compiler is a utility provided within by the QT framework.
  Banana Accounting include a copy of the rcc compiler.
• The .sbaa file will contains all the files specified in the qrc, in a compressed form. 

Installing the extension package:

• The .sbaa Extension needs to be installed through the Manage Extensions command.
• Once the Extension is installed, it appears in the menu Extensions.
• The Extension can be run from the menu Extensions.

How to generate the package file

When you generate a package .sbaa you can :

• Create with Banana Accounting;
• Define a Cmake file and use cmake.
  • Build with Visual Studio Code without translation.
  • Build with Visual Studio Code with translation.
  • With Qt Creator.

Installing and running the extension

Prior to run the extension you need to install it.

See: Installation & Execute Extensions

Manifest file

If you create a .sbaa file, also include a manifest file. The manifest.json file is a JSON-formatted file, which you can include in the .sbaa file through the .qrc file.
Using manifest.json, you specify basic metadata about your package such as the title, description and version.
The file name must end with the extension 'manifest.json'

Example: ch.banana.script.report.vat-ch.manifest.json

{
    "category": "import",
    "country":"switzerland",
    "countryCode":"ch",
    "description": "Postfinance Schweiz (Bewegungen importieren): ISO20022 und CSV Format",
    "description.en": "Swiss Postfinance (Import transactions): ISO20022 and CSV File Format",
    "language":"de",
    "publisher": "Banana.ch",
    "title": "Postfinance Schweiz (Bewegungen importieren)",
    "title.en": "Swiss Postfinance (Import transactions)",
    "version": "1.0"
}

Options for the files.

• All tags are optional.
• Categories
  • Valid categories are:
    export, import, invoice, invoice reminder, invoice statement, productivity. 
  • The category is used to displayed information on the Manage extension Dialog. 
    You need to choose a categorization type even if the package contains multiple extensions of different type. 
    In case of doubt use productivity. 
  • If you don't specify the category ("category": ""), the program will take the category from the first app included in the package. 
• description
• title
  Is used in the Menu Extensions to run the extensions.
  • If you have multiple extensions it becomes the title of the submenu that will contains all other extensions. 
  • The extensions will be listed in alphabetic order. 
    If you want a specific order precede the description of the extension with a number.
• Country 
  • If you don't specify country or language, the app will be shown for any country or language;
• Language
  You can specify more than one language.
• Translations
  You can add translation by using the "description" followed by a dot and the language code. 

Extension Project structure

We advise to create a separate folder for each extension that you create. The folder will contains all the file needed by the project:

• The qrc file.
• The manifest file.
• The file necessary to build a package.
• CMakeLists.txt if you build the package with the CMake. 
• Other files needed for the development
• File needed for Tests
• The level of repository test is the same of the level of extesion_id.js
• Other file needed for the documentation purpose. 

Folder structure

Create this folder structure, and add source files, images or folder as needed. 
We recommend to use as a file name the same as the extension's id. The extension's id is the unique identification of the script and is specified within the extension's attributes, and it is important that you avoid having duplicates.
Therefore replace <extension_id> with the desired extension's id. 

You can start by using a  Simple project template. 

Or you can create the folder structure manually.

  CMakeList.txt                              CMake project file
  <extension_id>.js                          Extension's code
  <extension_id>.manifest.json               Metadata such title, description and version
  <extension_id>.qrc                         List of files included in the package
  <extension_id>.sbaa                        Builded package (created after the building project)
  changelog.md                               Change history
  /test                                      Test code
     /testcases                                 Test data (ac2 files, csv files, ...)
     /testexpected                              Expected test results
     /testresults                               Results of last runned test
     <extension_id>.test.js                     Test code
  LICENCE                                    Extension licence 
  README.md                                  Repository main documentation page

Multiple extensions of the same project

When you have multiple extension and you want create a single package that content all your extension, you can structure as example below.

CMakeLists.txt                              CMake project file
/Extension1                                 Repository Extension 1
    extension_id_1.js                             Extension's code
    extension_id_1.manifest.json                  Metadata such title, description
/Extension2                                 Repository Extension 2
    extension_id_2.js                             Extension's code
    extension_id_2.manifest.json                  Metadata such title, description
extension_id.qrc                            List of files included in the package
extension_id.sbaa                           Builded package (created after the building project)
changelog.md                                Change history
/test                                       Test code
    /testcases                                     Test data (ac2 files, csv files,...)
    /testexpected                                  Expected test results
    /testresults                                   Results of last runned test
    extension_id_1.test.js                         Test code of Extension 1
    extension_id_2.test.js                         Test code of Extension 2
LICENCE                                     Extension licence
README.md                                   Repository main documentation page

Be careful that the repository test level is the same as the Extensions repositories, because if you don't define it in the same level you have problems running tests on the single extension. In the repository test you can create your test code of the specific extension.

The file .qrc must contain all the path file of extension's, for example: 

<!DOCTYPE RCC><RCC version="1.0">
   <qresource prefix="/">
      <file>./Extension1/<extension_id_1>.js</file>
      <file>./Extension1/<extension_id_1>.manifest.json</file>
      <file>./Extension2/<extension_id_2>.js</file>
      <file>./Extension2/<extension_id_2>.manifest.json</file>
   </qresource>
 </RCC>

You need to rename the <extension_id>.js parameter to the name of the extension id.

You can use alias in this context for the purpose of including files without writing the relative path of the file.

An example:

QRC File:

<!DOCTYPE RCC><RCC version="1.0">
   <qresource prefix="/">
      <file alias="extension1">./Extension1/<extension_id_1>.js</file>
      <file alias="extension2">./Extension2/<extension_id_2>.js</file>
  </qresource>
 </RCC>

Now for including the function and properties of the extension1, you write in the file of the project (extension_id_2.js):

//@includejs = extension1;

Before this configuration in the QRC file you use the relative path: 

//includejs = ./Extension2/<extension_id_2>.js

LICENSE

A project's LICENSE file in CMake is a document that specifies the legal terms for using, modifying, and distributing the project's source code and binaries. The LICENSE file should contain the name of the license you choose, a brief description of its terms, and a full copy of the license text.

Readme.md

This file contain the explanation of the functionalities and the other detail about about your extension. Is the main file that contain the documentation of your extension.

Multiple extensions in the same package

The package file can contains multiple extensions. An extension is a Javascript file that has the extension attribute with the extension Id.

Depending on the extension @type and @visibility option the extension will be than available on the Extension's menu or in the specific dialog (for example import, invoice printing, etc.).

Unpack the package file

A project's that will unpack the package.