In dit artikel
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 :
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.
- Valid categories are:
- 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.