List of API Version made available by Banana Accounting.

Banana Accounting Version	API Version
7.0.6	1.0
8.0.4 or more recent	1.0

 

Banana is the namespace (object) through which all Banana script's methods, class and objects are accessible.

Banana.application

The object Banana.application represent the running application.

Banana.console

The object Banana.console is used to sent message to the debug the script.

Banana.Converter

The class Banana.Converter contains methods useful to convert data from and to various formats.

Banana.document

The object Banana.document represent the current document opened in the application. It contains base properties and methods, see Banana.Document (Base), and if the document represent an accounting document it contains additional accounting's properties and methods, see Banana.Document (Accounting). If any document is opened this object is of type Undefined.

Banana.IO

The class Banana.IO is used to read and write files.

Banana.Report

The class Banana.Report enable you to create reports, preview and print them in Banana Accounting.

Banana.script

The object Banana.script is used to get informations about the running script.

Banana.SDecimal

The class Banana.SDecimal contains methods useful to do decimal math calculation.

Banana.Ui

The class Banana.Ui contains predefined dialogs to interact with the user, and methods to load dialogs from .ui or .qml files.

Banana.Xml

The class Banana.Xml contains methods to parse and access Xml data.

Banana Methods

Banana.compareVersion(v1, v2)

Compare two version strings. Versions string are in the form of "x.y.w.z". Returns 0 if v1 and v2 are equal, -1 if v2 is later and 1 if v1 is later.

Since: Banana Accounting 8.0.5

var requiredVersion = "8.0.5";
if (Banana.compareVersion && Banana.compareVersion(Banana.application.version, requiredVersion) >= 0)
   Banana.Ui.showInformation("Message", "More recent or equal than version " + requiredVersion);
else
   Banana.Ui.showInformation("Message", "Older than version " + requiredVersion);

Banana.include(path)

The method Banana.include(path) include a javascript file evaluating it.
If an error occour, i.e. the file is not found or is not valid, the method throws an exception.

The path is relative to the current script being executed, if no protocol is specified. Otherwise depending on the protocol it can be relative to the main script's folder, the document's folder or the name of a document attacched to the current file.
- <relative_path_to_current_script>/<file_name>
- file:script/<relative_path_to_main_script>/<file_name>
- file:document/<relative_path_to_file>/<file_name>
- documents:<attachment_name>

Scripst included though the method Banana.include(path) can include other scripts trhough the method Banana.include(path), but not via the script's attibute @includejs. The method Banana.include(path) garantees that each distinct script is evaluated once, even if it is included more than one time from differents scripts. Path can contain ".." (parent folder), in the case the destination path is outside the main script's folder, the method will throw a security exception.

Since: Banana Accounting 8.0.5

Banana.include("cashflowlib.js");
Banana.include("folder/cashflowlib.js");

 

Banana.Application represent the interface to the program and can be accessed through Banana.application.

Properties

isBeta

Return true if the application is a beta version.

var isBeta = Banana.application.isBeta;

Since Banana 8.0.7

isExperimental

Return true if the application is a beta version.

var isExperimental = Banana.application.isExperimental;

Since Banana 8.0.7

serial

Return the serial of the application in the form of "80006-170428".

var serial = Banana.application.serial;

Since Banana 8.0.7

version

Return the version of the application in the form of "8.0.4".

var version = Banana.application.version;

locale

Return the locale of the application in the form of "language_country", where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two- or three-letter ISO 3166 country code.

var locale = Banana.application.locale;

progressBar

Return an object of type ProgressBar used to give the user an indication of the progress of an operation and the ability to cancel it.

var progerssBar = Banana.application.progressBar;

 

Methods

addMessage(msg [, idMsg])

Add the message msg to the application. The message is showed in the pane "Messages", and in a dialog if the application option "Show Messages" is turned on.

If idMsg is not empty, the help button calls an url with script's id and message's id (idMsg) as parameters.

Banana.application.addMessage("Hello World");

See also: Table.AddMessage, Row.AddMessage, Document.AddMessage.

clearMessages()

Clear all the messages showed in the pane "Messages".

Banana.application.clearMessages();

showMessages([show])

Enable or disable the notification of new messages through the message dialog.

Banana.application.showMessages(); // Next messages are showed to the user through the message dialog.
Banana.application.showMessages(false); // Next messages will not pop up the message dialog.

openDocument(ac2FilePath [, password] [, title])

Open the ac2 file located in filePath and return an Object of type Banana.Document or undefined if the file is not found. The path can be relative, in this case the base directory is the path of the current document.

If the path is empty or contains a "*" or a "?" an open file dialog is showed to the user, and the title is used in the caption of the file open dialog.

With this function you can also open ISO 20022 and MT940 files, in this case a cash book with the transactions of the file is returned.

var file1 = Banana.application.openDocument("*.*");
if (!file1)
   return;

var file2 = Banana.application.openDocument("c:/temp/accounting_2015.ac2");
if (!file2)
   return;

 

Banana.Application.ProgressBar is the interface to the program progress bar and can be accessed through Banana.application.progressBar. The progressBar object is used to give the user an indication of the progress of an operation and the possibility to interrupt the running process. The progress bar is showed in bottom left corner of the application windows.

Methods

finish()

Notify that the operation has been completed and close the progress bar.

progressBar.finish();

pause()

Notify that the operation has been paused, the cursor icon is set to the arrow cursor or poiting hand cursor. This is usually called before showing a dialog.

Banana.application.progressBar.pause();
var result = dialog.exec();
Banana.application.progressBar.resume();

resume()

Notify that the operation has been resumed, the cursor icon is set back to an hourglass or watch cursor. This is usually called after a dialog has been closed.

Banana.application.progressBar.pause();
var result = dialog.exec();
Banana.application.progressBar.resume();

start(maxSteps)

Start the progress indicator and define the number of steps this operation needs before being complete.

You can call several times this method to split the progress in main and sub steps. Every call of the method start() should be paired with a call of the method finish().

// Example use of a progress bar
var progressBar = Banana.application.progressBar;
progressBar.start(10);   
for (var i = 0; i < 10; i++) {
    ...
    if (!progressBar.step(1)) {
       return; // Operation canceled by the user
    }
}
progressBar.finish();           

step([stepCount])

Advance the progress indicator of stepCount steps. If stepCount is not defined it advance of one step.

Returns false if the user canceled the operation, otherwise true.

progressBar.step(1);

Example multiple steps inside a block

// Two blocks of progress bar inside a progressBar

var progressBar = Banana.application.progressBar;

progressBar.start(2);           

// Block 1
progressBar.start(10)     
for (i=0;i < 10; i++) {
     progressBar.step(1);
}
progressBar.finish();       

// Block 2
progressBar.start(10)     
for (i=0;i < 10; i++) {
     progressBar.step(1);
}
progressBar.finish();           

progressBar.finish();         

 

 

The Banana.console object is used to display debug messages.

• Debug messages are displayed on the message window
• To see debug and log messages you should enable the option Show Debug Messages under Tools -> Program Options -> Developer
• To see critical and warning messages you should enable the option Show Developer Warnings and Messages under Tools -> Program Options -> Developer

console.critical(msg)

Display the msg in the message windows as a critical.

Banana.console.critical("critical message");

console.debug(msg)

Display the msg in the message windows.

Banana.console.debug("Debug message");

console.log(msg)

Display the msg in the message windows.

Banana.console.log("Log message");

console.warn(msg)

Display the msg in the message windows as warning.

Banana.console.warn("Warning message");

 

The class Banana.Converter is a collection of methods useful to convert various formats to and from data tables (array of array).

Methods

arrayToObject( headers, arrData, skipVoid)

Converts an array of array string to an array of objects

• headers is an array of strings that will become the properties of the objects.
• arrData is an array containing array of strings
• skipVoid if true skip void lines, if not present is set to false

    // read a CSV file
    var ppData = Banana.Converter.csvToArray(string, ',');    
    // first line is header
    var headers = ppData[0];
    // remove first line
    ppData.splice(0, 1);
    // convert in array of objects
    var arraOfObjects = Banana.Converter.arrayToObject(fileData.headers, ppData, true);

csvToArray(string [, separator, textdelim])

Convert a csv file (coma separated values) to an array of array.

The parameter string contains the text to convert. The parameter separator specify the character that separates the values, default is a comma ','. The parameter textDelim specify the delimiter character for text values, default is a double quote '"'.

Example:

var text = "1, 2, 3\n4, 5, 6\n7, 8, 9";
var table = Banana.Converter.csvToArray(text);
var value = table[0][1];
value == '2'; // true

flvToArray(string, fieldLengths)

Convert a flv file (fixed length values) to an array of array.

The parameter string contains the text to convert. The parameter fieldLengths is an array with the lengths of the fields.

Example:

//               6                  20       8
var text = "120608Phone               00002345";
var table = Banana.Converter.flvToArray(text, [6,20,8]);
var value = table[0][2];
value == '00002345'; // true

mt940ToTable(string)

Converts mt940 file to a table (array of array).

naturalCompare(a, b [, caseSensitive])

Compare two string so that the string "2" is considered less then "100" as it would be with normal string compare.
This function can be passed to array.sort function.

• a first value to compare
• b second value to compare
• return value is -1 if a < b, 1 if a > b and 0 if a == b

Banana.Converter.naturalCompare(a,b);

objectArrayToCsv(headers, objArray, [separator])

Converts an array of objects (with identical schemas) into a CSV table.

• headers An array of strings with the list of properties to export
• objArray An array of objects. Each object in the array must have the same property list.
• separator The CSV  column delimiter. Defaults to a comma (,) if omitted.
• return value a string containing the CSV text.

var csvText = Banana.Converter.objectArrayToCsv(headers, objArray, ";");

stringToCamelCase(string)

Converts a text to camel case, where only the first letter every word is upper case.

Banana.Converter.stringToCamelCase("this is an example"); 
// returns "This Is An Example"

stringToLines(string)

Convert a text in an array of lines. The end line character can be '\n', \r' or a combination of both.

Banana.Converter.stringToLines("this is\nan\nexample"); 
//returns ["this is", "an", "example"]

stringToTitleCase(string)

Converts a text to title case, where only the first letter of the text is upper case.

Banana.Converter.stringToTitleCase("this is an example"); 
// returns "This is an example"

arrayToTsv(table [, defaultChar])

Converts a table (array of array) to a tsv file (tabulator separated values). If a string contains a tab it will be replaced with defaultChar or a space if defaultChar is undefined.

Banana.Converter.arrayToTsv(table);

arrayToCsv(table)

Converts a table (array of array) to a csv file (coma separated values). Doubles quotes in text are replaced by apos. Texts containing comas are inserted in doubles quotes.

Banana.Converter.arrayToCsv(table);

toDate(date[, time])

Convert a date and/or time to a javascript date object.

The parameter date is a string in the formats YYYYMMDD or YYYY-MM-DD.

The time parameter is a string in the fromats HHMM[SSZZZ] or HH:MM[:SS.ZZZ].

Banana.Converter.toDate("2015-12-31");
Banana.Converter.toDate("20151231");

toInternalDateFormat(date [, inputFormat])

Converts a date to the internal format: YYYY-MM-DD.

The parameter date  can be a string or a date object.

The parameter inputFormat specifies the date input format, if it is not specified the local date format is used.

Example: 

Banana.Converter.toInternalDateFormat("31-12-13", "dd-mm-yy");
// returns "2013-12-31"
Banana.Converter.toInternalDateFormat(new Date());
// return current date in format "yyyy-mm-dd"

toInternalNumberFormat(value [, decimalSeparator])

Converts a number to the internal format: 123456.78.The internal number format use the character '.' as decimal separator, and doesn't contain a group separator. 

The parameter value can be a string or a number object.

The parameter decimalSeparator specifies the character used to separate the decimals, if it is not specified the local decimal separator is used.

Example: 

Banana.Converter.toInternalNumberFormat("1200,25", ",");
// returns "1200.25"

toInternalTimeFormat(string)

Converts a time to the internal format: HH:MM:SS.ZZZ.

Banana.Converter.toInternalTimeFormat("11:24"); 
// returns "11:24:00"

toLocaleDateFormat(date [, format])

Converts a date to the local format.

The parameter date can be a string or  a date object.

The parameter format specifies the date ouptut format, if it is not specified the local date format is used.

Banana.Converter.toLocaleDateFormat("2014-02-24")
// returns "24.02.2014"

toLocaleNumberFormat(value [, decimals = 2, convZero = true])

Converts a number to the local format.

The parameter value can be a string or a number object.

The parameter decimals set the number of decimals.

The parameter convZero set the format returned for zero values. If false the method returns an empty string, if true it returns the zero value as string.

Example: 

Banana.Converter.toLocaleNumberFormat("1200.25") 
// returns "1'200,25"

toLocaleTimeFormat(string [, format])

Converts a time to the local format.

The parameter format specifies the time ouptut format, if it is not specified the local time format is used.

Banana.Converter.toLocaleTimeFormat("11:24:42");
// returns "11:24"

 

 

Banana.Document is the interface to a document in Banana Accounting.

Banana.Document has base methods, that apply to all documents, see Banana.Document (Base), and method that are specific to the type of documents. This page describes the methods for the accounting files.

In the table documents of the example file there are also some example code.

Methods for accounting's files

This method are available only if the Document is of type Accounting

accountDescription(account [,column])

Return the Description of the specified account.

• Account can be an account or a Group (Gr=)
• Column can be an alternative column name to retrieve.

var descriptionAccount = Banana.document.accountDescription('1000');
var descriptionGroup = Banana.document.accountDescription('Gr=10');
var gr = Banana.document.accountDescription('1000','Gr');

accountsReport([startDate, endDate])

Return the account report for the specified period. Start and end date can be a string in form 'YYYY-MM-DD' or a date object.

var report = Banana.document.accountsReport();
var report = Banana.document.accountsReport('2017-01-01', '2017-03-31');

budgetBalance(account [, startDate, endDate, function(rowObj, rowNr, table)])

Sum the amounts of opening, debit, credit, total and balance for all budget transactions for this accounts .

var budget = Banana.document.budgetBalance('1000');

See for more detail the function currentBalance.

budgetCard(account [, startDate, endDate, function(rowObj, rowNr, table)])

Return for the given account and period a Table object with the budget account card.

var card = Banana.document.budgetCard('1000');

For more ditails see currentCard.

budgetExchangeDifference( account, [date, exchangeRate])

Return the unrealized exchange rate Profit or Loss fo the account at the specified date. 

• account must be a valid account number not in base currency
• date
  • a date that is used to calculate the balance
  • if empty calculate up to the end of the period
• exchangeRate
  • if empty use the historic exchange rate for the specified date or the current if not a valid exchange rate for the date are found.
  • if "current" use the current exchange
  • if number for example "1.95" use the specified exchange rate.
• Return value
  • Positive number (debit) are exchange rate Loss.
  • Negative number (credit) are exchange rate Profit.
  • empty if no difference or if the account has not been found or not a multicurrency accounting file.

// unrealized exchange rate profit or loss for the account 1000
// last balance and current exchange rate
var exchangeRateDifference = Banana.document.budgetExchangeRateDifference('1000');

// at the end of Semptember and hystoric exchange rate
var exchangeRateDifference = Banana.document.budgetExchangeRateDifference('1000', "2017-09-31");

// at the end of Semptember and current exchange rate
var exchangeRateDifference = Banana.document.budgetExchangeRateDifference('1000', "2017-09-31", "current");

// at the end of Semptember and specified exchange rate
var exchangeRateDifference = Banana.document.budgetExchangeRateDifference('1000', "2017-09-31", "1.65");

Available from Banana version 8.05

budgetInterest( account, interestRate, [startDate, endDate, , function(rowObj, rowNr, table)])

Return the calculated interest for the budget transactions. 

For more information see the currentInterest and current Balance

// calculate the interest debit for the whole period
var interestDebit = Banana.document.budgetInterest('1000','5.75');

// calculate the interest credit for the whole period
var interestDebit = Banana.document.budgetInterest('1000','-4.75');

currentBalance(account [, startDate, endDate, function(rowObj, rowNr, table) ])

Sum the amounts of opening, debit, credit, total and balance for all transactions for this accounts.

The calculations are perfermed by traversing by creating a journal (see journal() function) with all the transactions , and selecting the transctions with the parameters specified.
The computation is usually very fast. But if you  have a file with many transactions especially the first query could take some time. 

var currentBal = Banana.document.currentBalance('1000','','');
var openingBalance = currentBal.opening;
var endBalance = currentBal.balance;

• Return value
  Is an object that has
  • opening the amount at the begining of the period (all transactions before)
  • debit the amount of debit transactions for the period
  • credit the amount of credit transactions for the period
  • total the difference between debit-credit for the period
  • balance opening + debit-credit for the period
  • amount it the "normalized" amount based on the bclass of the account or group.
    If there are multiple accounts or groups, takes the first BClass of the first.
    • for BClass 1 or 2 it return the balance (value at a specific instant).
    • for BClass 3 or 4 it return the total (value for the duration).
    • For BClass 2 and 4 the amount is inverted.
  • openingCurrency the amount at the begining of the period in the account currency
  • debitCurrency the amount of debit transactions for the period in the account currency
  • creditCurrency the amount of credit transactions for the period in the account currency
  • totalCurrency the difference between debit-credit for the period in the account currency
  • balanceCurrency opening + debit-credit for the period in the account currency
  • rowCount the number of lines that have bben found and used for this computation
  • bclass (double entry accounting only) is the bclass of the account or group used to express the amount.
    The bclass is the value entered in the columns bclass.
    It is taken in consideration the first account or group specified. If for examble you query two account that first that has bclass 2 and the second that has bclass 1. The bclass would be 2.
    The bclass is assigned by following this steps. :
    • The bclass of the specified account or group.
    • The blcass of the partent group, for the same section.
    • The blcass of the section.
• Account
  • can be an account id, a cost center or a segment.
  • can be a cobination of account and segments, separeted by the semicolon ":"
    In this case it returns all the transactions that have the indicated account and segments
    • 1000:A1:B1
  • can be differents accounts and multiple segments separated by the "|"
    In this case it include all transactions that have the one of the specified accounts and one of the specified segments
    • 1000|1001
    • 1000|1001:A1:B1
    • 1000|1001:A1|A2:B1
    • can be a wildCardMatching
      Wildcards can be used for accounts, segments, Groups or BClass and in combination
      • ?  Matches any single character.
      • *  Matches zero or more of any characters
      • [...] Set of charachtes
      • "100?" match "1001, 1002, 1003, 100A, ...)
      • "100*" Matches all accounts starting with 100
      • "100*|200*:A?" Matches all accounts starting with 100 or 200 and with segments with A and of two charachters.
      • "[1234]000" Matches "1000 2000 3000 4000"
  • Can be a group or a BClass.
    It include all the transactions where the account used belong to a specified Group o r BClass.
    It is also possible to use wildcards.
    The program first create a list of accounts and then use the account list.
    Do non mix mix groups relative to normal accounts, with groups relative to cost center or segments. Calculation could provide unexpected results.
    • BClass (for the double entry accounting only)
      • BClass=1
      • BClass=1|2
    • Gr for groups that are in Accounts table.
      • Gr=100
      • Gr=10*
      • Gr=100|101|102
    • GrC for group that are in the Category table of the income and expenses accounting type.
      • GrC=300
      • GrC=300|301
  • Contra Accounts or other fields selection
    Transactions are included only if they have also a value corresponding
    After the "&&" you can insert a field name of the table journal.
    • 1000&&JContraAccount=2000 return all transctions of the account 1000 that have a contra account 2000.
      As per accounts you can specify multiple contra accounts, BClass=, Gr= with also wildcards.
    • 1000&&JCC1=P1|P2 will use only transactions on account 1000 and that also have the CC1=.P1 or .P2
• StartDate
  • is a string in form 'YYYY-MM-DD' or a date object.
  • If startDate is empty the accounting start date is taken.
• End date:
  • is a string in form 'YYYY-MM-DD' or a date object.
  • If endDate is empty the accounting end date is taken.
• function(rowObj, rowNr, table)
  This fuction will be called for each row of the selected account.
  The function should return true if you want this row to be included in the calculation.

function exec( string) {
    // We retrive the total sales (account 4000) only for the cost center P1
    var balanceData = Banana.document.currentBalance('4000','', '', onlyCostCenter);
    // sales is a revenue so is negative and we invert the value
    var salesCC1 = -balanceData.total;
    // display the information
    Banana.Ui.showText("Sales of Project P1: " + salesCC1);
}

// this function return true only if the row has the cost center code  "P1"
function onlyCostCenter( row, rowNr, table){
   if(row.value('JCC1') === 'P1') {
      return true;
   }
   return false;
}

Examples

Banana.document.currentBalance("1000")              // Account 1000 
Banana.document.currentBalance("1000|1010")         // Account 1000 or  1010 
Banana.document.currentBalance("10*|20*")           // All account that start with 10 or with 20
Banana.document.currentBalance("Gr=10")             // Group 10
Banana.document.currentBalance("Gr=10| Gr=20")      // Group 10 or  29
Banana.document.currentBalance(".P1")               // Cost center .P1
Banana.document.currentBalance(";C01|;C02")         // Cost center ;C01 and C2
Banana.document.currentBalance(":S1|S2")            // Segment :S1  and :S2
Banana.document.currentBalance("1000:S1:T1")        // Account 1000 with segment :S1 or ::T1
Banana.document.currentBalance("1000:{}")           // Account 1000 with segment not assigned 
Banana.document.currentBalance("1000:S1|S2:T1|T2")  // Account 1000 with segment :S1 or ::S2 and ::T1 
                                                    //   or ::T
Banana.document.currentBalance("1000&&JCC1=P1")     // Account 1000 and cost center .P1

currentCard(account [, startDate, endDate, function(rowObj, rowNr, table)])

Return for the given account and period a Table object with the transactions for this account.

Row are sorted by JDate

parameters:

• account can be any accounts, cost center or segment as specifiend in currentBalance.
• startDate any date or symbol as specifiend in currentBalance.
• endDate any date or symbol as specifiend in currentBalance.

Return columns the same as for the Journal() function.

var transactions = Banana.document.currentCard('1000','2015-01-01','2015-12-31');

currentInterest( account, interestRate, [startDate, endDate, , function(rowObj, rowNr, table)])

Return the calculated interest on the specified account.
Interest is calculate on the effective number o days for 365 days in the years.

• account is the account or group (same as in the function currentBalance)
• interestRate. In percentage "5", "3.25". Decimal separator must be a "." 
  • If positive it calculate the interst on the debit amount.
  • If negative it calculate the interest on the credit amounts.
• startDate, endDate, function see the currentBalance description.
  If no parameters are specified it calculate the interest for the whole year.

// calculate the interest debit for the whole period
var interestDebit = Banana.document.currentInterest('1000','5.75');

// calculate the interest credit for the whole period
var interestDebit = Banana.document.currentInterest('1000','-4.75');

exchangeRate( currency, [date])

Return the exchange rate that convert the amount in currency in basic currency.

The exchange rate is retrieved from the Currency table, already considering the multiplier.

• If no date is specified the exchange rate without date is used.
• If a date is specified it retrieve the exchange rate with the date minor or equal the specified date.

invoicesCustomers()

Return a table with the customers invoices from the transaction table. A customer group must be defined and invoices must be numbered using the column DocInvoice.

invoicesSuppliers()

Return a table with the suppliers invoices from the transaction table. A supplier group must be defined and invoices must be numbered using the column DocInvoice.

journal([originType = ORIGINTYPE_NONE, int accountType = ACCOUNTTYPE_NONE])

Return for the given parameters a Table object with all the amount registered on the accounts.
The journal contain a row for each account used.

• originType specify the row to be filtered for
  Can be on of
  • ORIGINTYPE_NONE no filter is applied and all rows are returned (current and budget)
  • ORIGINTYPE_CURRENT only the normal transactions are returned
  • ORIGINTYPE_BUDGET only the budget transactions are returned
• accountType specify the row to be filtered for
  • ACCOUNTTYPE_NONE no filter is applyied and all rows are returned
  • ACCOUNTTYPE_NORMAL only rows for normal accounts are returned
  • ACCOUNTTYPE_CC1 only rows for Cost Center 1 are returned
  • ACCOUNTTYPE_CC2 only rows for Cost Center 2 are returned
  • ACCOUNTTYPE_CC3 only rows for Cost Center 1 are returned
  • ACCOUNTTYPE_CC Cost Center rows are returned same as using (ACCOUNTTYPE_CC1 | ACCOUNTTYPE_CC2 | ACCOUNTTYPE_CC3)

// get all transactions for normal accounts
var journal = Banana.document.journal(Banana.document.ORIGINTYPE_CURRENT, Banana.document.ACCOUNTTYPE_NORMAL );

For each account used in the transaction table (AccountDebit, AccountCredit, CC1, CC2, CC3) the program generate a Journal row with the JAccount column set with the specific account. 
For a double entry account transaction that use AccountDebit, AccountCredit, AccountVat, CC1, CC2, CC3 the Journal will contain 6 rows. If the transaction has only AccountDebit and AccountCredit only 2 rows will be generated.

The column JAmount  contains the exact amount registered on the specific account. 

The returned table has all the columns of the transaction's table plus the following columns.

The return columns are:

• JDate the date of the transction.
• JDescription the transaction's description.
• JRowOrigin the row number in the transaction's table (rows begin from 0).
• JTableOrigin the source table.
• JRepeatNumber the progressive number of the repetition of budget transactions.
• JAccount the account for this line.
  There is one row for each account (AccountDebit, AccountCredit, AccountVat, CC1, CC2, CC3).
• JAccountDescription the Description for this account.
• JAccountClass the BClass number for this account.
• JAccountGr the Gr for this account.
• JAccountGrDescription the Gr for this account.
• JAccountGrPath the whole Gr path.
• JAccountCurrency the currency of thi account.
• JAccountType as defined above (ACCOUNTTYPE_NORMAL, ACCOUNTTYPE_CC1, ...)
• JAmount the amount in basic currency registered on the account (positive is debit, negative is credit).
• JAmountAccountCurrency the amount in the account currency (positive i debit, regative is credit).
• JTransactionCurrency the transaction's currency.
• JAmountTransactionCurrency the amount in transaction's currency.
  For account with currency not in tranasctions currency the exchange rate of the transaction is used.
• JTransactionCurrencyConversionRate is the conversion rate to obtain amounts in transaction's currency. 
  Multiply the transcation's amount in basic currency with the JTransactionCurrencyConversionRate  and you will have the amount converted in transaction's currency.
  The conversion rate has 12 significant decimal so only by very large conversion should be have conversion differences.
• JVatIsVatOperation true if this row has a Vat code.
• JVatCodeWithoutSign the Vat code without the evetually preceeding '-'.  For example "-V10" becomomes "V10".
• JVatCodeDescription the Description for this Vat code.
• JVatCodeWithMinus true if the Vat code is preceeded by "-".
• JVatCodeNegative true if the Vat amount is negative (deductible).
• JVatTaxable the amount VatTaxable with the sign that follow the JVatCodeNegative
• VatTwinAccount the account where the net amount (without VAT) is being registered . 
  In case of a transaction where the Gross amount is CHF 1100, then the VAT is CHF 100 and the net amount is CHF 1000. The VatTwin account will be the account where the CHF 1000 is being registered.
  We use the name Twin for the fact that the VatTwinAccount follows the sign of the VatAccount.
  If the Vat amount is registered in debit, the VatTwinAccount will be the AccountDebit.
  If the Vat amount is registered in credit, the VatTwinAccount will be the AccountCredit.
• JContraAccount the contra account.
  The contra account is deducted based on the other accounts and the sequence in the transactions table.
• JContraAccountType one of the following value:
  • CONTRAACCOUNTTYPE_NONE  for no contra account
  • CONTRAACCOUNTTYPE_DIRECT when there is on the same line credit and debit accounts.
  • CONTRAACCOUNTTYPE_MULTIPLEFIRST the first line of a transaction on more accounts. 
    The first transactions after a line with debit and credit accounts or with a different date.
  • CONTRAACCOUNTTYPE_MULTIPLEFOLLOW the second or following line of a MULTIPLEFIRST with the same date.
  • CONTRAACCOUNTTYPE_VAT  the line for the Vat Account
• JContraAccountGroup the line number corresponding to the row number of the CONTRAACCOUNTTYPE_MULTIPLEFIRST
• JCC1 the CC1 without the preceeding sign
• JCC2 the CC2 without the preceeding sign
• JCC3 the CC3 without the preceeding sign
• JSegment1 .. JSegment10 the segment relative to the account
• JDebitAmount the amount debit in basic currency
• JCreditAmount the amount credit in basic currency
• JDebitAmountAccountCurrency the amount debit in account currency
• JCreditAmountAccountCurrency the amount credit in account currency
• JBalance the balance amount (for account card) in basic currency
• JBalanceAccountCurrency the balance amount (for account card) in account currency
• JOriginType as defined above
  • ORIGINTYPE_CURRENT
  • ORIGINTYPE_BUDGET
• JOperationType on of
  • OPERATIONTYPE_NONE = 0
  • OPERATIONTYPE_OPENING = 1
    The row is generated from the opening balance
  • OPERATIONTYPE_CARRYFORWARD = 2
    The row is used from the account card and is the balance of the account at this moment.
  • OPERATIONTYPE_TRANSACTION = 3
    The row is generated from the Transactions table if it is ORIGINTYPE_CURRENT
    or from the budget table if the row is ORIGINTYPE_BUDGET

  •  OPERATIONTYPE_INVOICESETTLEMENT = 21

     

journalCustomersSuppliers([originType = ORIGINTYPE_NONE, int accountType = ACCOUNTTYPE_NONE])

Same as journal with additional settlements rows for closing invoices and the following columns:

• JInvoiceDocType
• JInvoiceAccountId
• JInvoiceCurrency
• JInvoiceStatus
• JInvoiceDueDate
• JInvoiceDaysPastDue
• JInvoiceLastReminder
• JInvoiceLastReminderDate
• JInvoiceIssueDate
• JInvoiceExpectedDate
• JInvoicePaymentDate
• JInvoiceDuePeriod
• JInvoiceRowCustomer (1=Customer, 2=Supplier)

previousYear([nrYears])

Return the previous year as a Banana.Document object. If the previoius yeas is not defined or it is not foud it return null.

• nrYears is the number of years to go back, default is one.

var previousYearDoc = Banana.document.previousYear();
var previousTwoYearDoc = Banana.document.previousYear(2);

projectionBalance(account, projectionStartDate [, startDate, endDate, function(rowObj, rowNr, table) ])

Same as currentBalance but use the budget data starting from the projectionStartDate.

This functions calculate a projection of the end of year result (or specified period) combining the current data and the budget data for the period non yet booked.

if projectionStartDate is empty the result will be the same as currentBalance.

If you have already booked the 1. semester and would like to have a projection up to the end of the year

// We have booked the 1. semester and would like to have
// a projection up to the end of the yer
var cashProjection = Banana.document.projectionBalance('1000','2015-07-01');
var cashEnd = projection.balance;
var salesProjection = Banana.document.projectionBalance('3000','2015-07-01').total;
var salesForYear = -salesProjection.total;

projectionCard(account, projectionStartDate [, startDate, endDate, function(rowObj, rowNr, table) ])

Same as currentCard but use the budget data starting from the projectionStartDate.

If projectionStart date is empty result will be the same s currentCard.

var transactions = Banana.document.projectionCard('1000','2015-01-01','','');

endPeriod([period])

Return the end date in the form of 'YYYY-MM-DD'.

The endDate and startDate functions are used to retrieve the date of the accounting, so that you can create scripts that works on file of different years.

var dateEnd = Banana.document.endPeriod();
var dateStartFebruary = Banana.document.endPeriod('2M');

• Period:
  • If period is not present the return value is the end date of the accounting.
  • The period is added the starting account date, and than is returned the last date of the period..
  • Period (for example 2M = 2 months) is a number followed by one of the following charachters
    • D for days
    • M for months
    • Q for quarters
    • S for semesters
    • Y for years
  • Assuming that the Start accounting date is 2015-01-01
    • 1M return 2015-01-02
    • 2M return 2015-02-28
    • 2Q return 2015-06-30
    • 2S return 2015-12-31
    • 2Y return 2016-12-31

See also startDate.

startPeriod ([period])

Return the end date in the form of 'YYYY-MM-DD'.

The endPeriod and startPeriod functions are used to retrieve the date of the accounting, so that you can create scripts that works on file of different years.

var dateStart = Banana.document.endPeriod();
var dateStart3Q = Banana.document.endPeriod('3Q');

• Period:
  If period is not present return the start date.
  • Period (for example 2M = 2 months) is a number followed by one of the following charachters
    • D is for Days
    • M for Months
    • Q for Quorters
    • S for Semester
    • Y for year
  • With 1 the starting date of the accounting is returned.
  • Assuming that the Start accounting date is 2015-01-01
    • 1M return 2015-01-01
    • 2M return 2015-02-01
    • 2Q return 2015-04-01 
    • 2S return 2015-07-01
    • 2Y return 2016-01-01

See also endDate.

vatBudgetBalance(vatCode[, startDate, endDate, function(rowObj, rowNr, table) ])

Sum the vat amounts for the specified vat code and period, using the Budget data.

var vatTotal = Banana.document.vatBudgetBalance('V15');

vatCurrentCard(vatCode[, startDate, endDate, function(rowObj, rowNr, table) ])

Retrieve the transactions relative to the specified VatCode.

var vatTransactions = Banana.document.vatCurrentCard('V15');

vatCurrentBalance(vatCode[, startDate, endDate, function(rowObj, rowNr, table) ])

Sum the vat amounts for the specified vat code and period.
For more info see :

• explanations of the function currentBalance.
• Case study BananaApp for VatReport.

Example: 

var currentVat = Banana.document.vatCurrentBalance('V15','','');
var vatTaxable = currentVat.vatTaxable;
var vatPosted = currentVat.vatPosted;

• Return value:
  Is an object that has
  • vatTaxable the amount of the taxable column
    (the sign is the same as the vatAmount)
  • vatAmount the amount of vat
  • vatNotDeductible the amount not deductible
  • vatPosted VatAmount - VatNotDeductible
  • rowCount the number of lines that have bben found and used for this computation
• VatCode
  One or more VatCode defined in the tabel Vat Codes.
  Multiple vat code can be separated by "|" for example "V10|V20", or you can use vildcard "V*".

vatProjectionBalance(vatCode, projectionStartDate, [, startDate, endDate, function(rowObj, rowNr, table) ])

Same as vatCurrenBalance but use the budget data starting from the projectionStartDate.

var projectionVat = Banana.document.vatProjectionBalance('V15','','');
var vatTaxable = projectionVat.vatTaxable;
var vatPosted = projectionVat.vatPosted;

vatProjectiontCard(vatCode, projectionStartDate, [, startDate, endDate, function(rowObj, rowNr, table) ])

Same as vatCurrentCard but use the budget data starting from the projectionStartDate.

var vatTransactions = Banana.document.vatProjectiontCard('V15','2015-01-01','','');

vatReport([startDate, endDate])

Return the vat report for the specified period.

Start and end date are strings in form 'YYYY-MM-DD' or a date object. If startDate is empty the accounting start date is taken. If endDate is empty the accounting end date is taken.

var vatReport = Banana.document.vatReport('','');

 

 

Banana.Document is the interface to a document in Banana Accounting. The current opened document can be accessed through the property Banana.document. A document can be also opened with the method Banana.application.openDocument.

Properties

cursor

Return a Cursor object with the current position of the cursor and the range of the selected rows.

var currentCursor = Banana.document.cursor;

locale

Return the locale of the document in the form of "language_country", where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two- or three-letter ISO 3166 country code.

var locale = Banana.document.locale;

rounding

Return the rounding context of the current file that can be used with the SDecimal math functions.

var rounding = Banana.document.rounding;

tableNames

Return an array with the xml names of the tables in the document.

var tableNames = Banana.document.tableNames;

 

Methods

addMessage(msg[, idMsg])

Add the message msg to the document. The message is showed in the pane "Messages", and in a dialog if the application option "Show Messages" is turned on.
If idMsg is not empty, the help button calls an url with script's id and message's id (idMsg) as parameters.

See also: Application.AddMessage, Table.AddMessage, Row.AddMessage.

Banana.document.addMessage("Message text");

clearMessages()

Clear all the document's messages showed in the pane "Messages".

Banana.document.clearMessages();

getScriptSettings()

Get the settings of the script saved in the document. You use this method to get settings that are private to the running script. It is possible to save the settings of the script through the method "setScriptSettings". 

With this method Settings are saved and restored under the script id, If you change the script's id you will lose the saved settings.

Example:

// Initialise parameter
param = {
   "searchText": "",
   "matchCase": "false",
   "wholeText": "false"
};

// Readscript settings
var strData = Banana.document.getScriptSettings();
if (strData.length > 0) {
   var objData = JSON.parse(strData);
   if (objData)
      param = objData;
}

Since Banana 8.0.8

getScriptSettings(id)

Return the settings saved in the document under the id 'id'.

You use this method to get settings that are shared between scripts. As id we recommend to use a substring of the script's id. For example if you have the scripts 'ch.banana.vat.montlyreport' and 'ch.banana.vat.endofyearreport', then you can use as id 'ch.banana.vat'.

Example:

// Initialise parameter
param = {
   "searchText": "",
   "matchCase": "false",
   "wholeText": "false"
};

// Readscript settings
var strData = Banana.document.getScriptSettings('ch.banana.vat');
if (strData.length > 0) {
   var objData = JSON.parse(strData);
   if (objData)
      param = objData;
}

Since Banana 8.0.8

info(section, id)

Return the info value of the document referenced by section and id. Section and Id correspond to the xml name listed in the Info table, see command File info in menu "Tools" and set the view to complete to see the XML columns. If the value referenced by section and id doesn't exist, an object of type undefined is returned.

Example:

// Get some value of the accounting file 
var FileName = Banana.document.info("Base","FileName");
var DecimalsAmounts = Banana.document.info("Base","DecimalsAmounts");
var HeaderLeft = Banana.document.info("Base","HeaderLeft");
var HeaderRight = Banana.document.info("Base","HeaderRight");
var BasicCurrency = Banana.document.info("AccountingDataBase","BasicCurrency");

// For openingDate and closureDate use instead startDate and endDate
var openingDate = Banana.document.info("AccountingDataBase","OpeningDate");
var closureDate = Banana.document.info("AccountingDataBase","ClosureDate");

// For file accounting type
var FileType = Banana.document.info("Base","FileType");
var FileGroup = Banana.document.info("Base","FileTypeGroup");
var FileNumber = Banana.document.info("Base","FileTypeNumber");

FileTypeGroup / FileTypeNumber combinations:

• 100 Double entry accounting
  • 100 No VAT
  • 110 With VAT
  • 120 Multi Currency
  • 130 Multi Currency with VAT
• 110 Income and Expense accounting
  • 100 No VAT
  • 110 With VAT
• 130 Cash Book
  • 100 No VAT
  • 110 With VAT
• 400 Address / Labels
  • 110 Labels
  • 120 Address

scriptSaveSettings(string)

Save the settings of the script in the document. The next time the script is run, it si possible to read the saved settings with "scriptReadSettings".

With this method Settings are saved and restored under the script id, If you change the script's id you will lose the saved settings.

Example:

// Save script settings
var paramString = JSON.stringify(param);
var value = Banana.document.scriptSaveSettings(paramString);

Deprecated since Banana 8.0.8. Use setScriptSettings instead.

scriptReadSettings()

Return the saved settings of the script.

With this method Settings are saved and restored under the script id, If you change the script's id you will lose the saved settings.

Example:

// Initialise parameter
param = {
   "searchText": "",
   "matchCase": "false",
   "wholeText": "false"
};

// Readscript settings
var strData = Banana.document.scriptReadSettings();
if (strData.length > 0) {
   var objData = JSON.parse(strData);
   if (objData)
      param = objData;
}

Deprecated since Banana 8.0.8. Use getScriptSettings instead.

setScriptSettings(value)

Save the settings of the script in the document. It is possible to read the saved settings of the script with the method "getScriptSettings". 

With this method Settings are saved and restored under the script id, If you change the script's id you will lose the saved settings.

Example:

// Save script settings
var paramString = JSON.stringify(param);
var value = Banana.document.setScriptSettings(paramString);

Since Banana 8.0.8.

setScriptSettings(id, value)

Save the settings in the document under the id 'id'. It is possible to read the saved settings with "getScriptSettings(id)".

You use this method to set settings that are shared between scripts. As id we recommend to use a substring of the script's id. For example if you have the scripts 'ch.banana.vat.montlyreport' and 'ch.banana.vat.endofyearreport', then you can use as id 'ch.banana.vat'.

Example:

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

Since Banana 8.0.8.

table(xmlTableName)

Return the table referenced by the name xmlTableName as a Table object, or undefined if it doesn't exist.

Banana.document.table("Accounts");

table(xmlTableName, xmlListName)

Return the table referenced by the name xmlTableName with the rows of the list xmlListName as a Table object, or undefined if the table or the list don't exist. The default list is the 'Data' list.

Banana.document.table("Transactions", "Examples");
Banana.document.table("Transactions").list("Examples");  // alternative way

See also: Table.list, Table.listNames.

Since Banana 8.0.5

value(tableName, rowNr, columnName)

Return the value in table tableName, row rowNr and column columnName as string. If the table, row or column are not founds it return an object of type undefined.

Banana.document.value("Accounts", 5, "Description")

 

 

Banana.Document.Cursor is the interface to the cursor and can be accessed through Banana.document.cursor.

Properties

tableName

Return the xml name of the current table.

var currentTable = Banana.document.cursor.tableName;

rowNr

Return the number of the current row.

var currentRow = Banana.document.cursor.rowNr;

columnName

Return the xml name of the current column.

var currentColumn = Banana.document.cursor.columnName;

selectionTop

Return the index of the top row of the current selection.

var currentSelectionTop = Banana.document.cursor.selectionTop;

selectionBottom

Return the index of the bottom row of the current selection.

var currentSelectionBottom = Banana.document.cursor.selectionBottom;

 

Banana.Document.Row is the interface of a row.

Properties

isEmpty

Return true if the row is completly empty.

var isEmpty = tRow.isEmpty;

rowNr

Return the index of the row.

var rowNr = tRow.rowNr;

uniqueId

Return the unique id (an interger value) of the row.
Banana assign to every new row a unique id, this value is fix a will never change.

var uniqueId = tRow.uniqueId;

 

Methods

addMessage(msg [, columnName] [, idMsg])

Add the message msg to the document. The message is showed in the pane "Messages", and in a dialog if the application option "Show Messages" is turned on.

If idMsg is not empty, the help button calls an url with message's id (idMsg) as parameter.

If columnName is not empty, the message is connected to the column columnName. With a double click over message in the message pane, the cursor jump to the corresponding table, rowNr and columnName.

See also: Application.AddMessage, Table.AddMessage, Document.AddMessage.

var accountsTable = Banana.document.table("Accounts");        
var tRow = accountsTable.row(4);
tRow.addMessage("Message text");

toJSON([columnNames])

Return the row as JSON string. If the parameter columnNames is defined, only the columns in the array are included in the file.

// Return all the columns of the row
var json = tRow.toJSON();

// Return only the defined columns of the row
var json = tRow.toJSON(["Account", "Description", "Balance"]);

value(columnName)

Return the value in column columnName. If the column is not found or the object is invalid it return the value undefined.

var accountsTable = Banana.document.table("Accounts");        
var tRow = accountsTable.row(4);
tRow.value("Description");

 

Banana.Document.Table is the interface of a table.

Properties

name

Return the xml name of the table.

var table = Banana.document.table("Accounts");
var tName = table.name;

columnNames

Return the xml names of the table's columns as an array.

var table = Banana.document.table("Accounts");
var tColumnNames = table.columnNames;

listName

Return the xml name of the list that this table object reference to. The default list is the 'Data' list.
Since Banana 8.0.5

var table = Banana.document.table("Accounts");
var tListName = table.listName;

listNames

Return the xml names of the available lists as an array. The default list is the 'Data' list.
Since Banana 8.0.5

var table = Banana.document.table("Accounts");
var tListNames = table.listNames;

rowCount

Return the number of rows in the table.

var table = Banana.document.table("Accounts");
var tRowCount = table.rowCount;

rows

Return the rows of the table as an array of Row objects.

var table = Banana.document.table("Accounts");
var tRows = table.rows;

 

Methods

addMessage(msg, rowNr [, columnName] [, idMsg])

Add the message msg to the queue of the document. The message is showed in the pane "Messages", and in a dialog if the application option "Show Messages" is turned on.

If idMsg is not empty, the help button calls an url with message's id (idMsg) as parameter.

If rowNr is different than "-1" the message is connected to the row rowNr. if columnName is not empty, the message is connected to the column columnName. With a double click over message in the message pane, the cursor jump to the corresponding table, rowNr and columnName.

See also: Application.AddMessage, Row.AddMessage, Document.AddMessage.

var table = Banana.document.table("Accounts");
table.addMessage("Message string", 3, "description");

extractRows( function(rowObj, rowNr, table), tableTitle)

Extract the rows that passed the test defined by function and show them in the table "Selections". The title of the table is set to tableTitle.

findRows( function(rowObj, rowNr, table))

Return an array of Row objects that pass the test defined in function.

findRowByValue(columnName, value)

Return the first row as Row object that contains the value in the the column columnName. Or undefined if any row is found.

var cashAccountRow = Banana.document.table('Accounts').findRowByValue('Account','1000');
if (!cashAccountRow)
   //Row not found

list(xmlListName)

Return a new table object with the rows of the list xmlListName, or undefined if the list xmlListName doesn't exist.

var recurringTransactions = Banana.document.table('Transactions').list('Examples');
var archivedProducts = Banana.document.table('Products').list('Archive');

Since Banana 8.0.5

row(rowNr)

Return the Row at index rownr as Row Object, or undefined if rowNr si outside the valid range.

var table = Banana.document.table("Accounts");
var row = table.row(3);

toJSON([columnNames])

Return the table as JSON string. If the parameter columnNames is defined, only the columns in the array are included in the file.

var table = Banana.document.table("Accounts");
var json = table.toJSON();

toHtml([columnNames, formatValues])

Return the table as Html file. If the parameter columnNames is defined, only the columns in the array are included in the file. If formatValues is set to true, the values are converted to the locale format.

Example:

//Show the whole row content of the table Accounts
Banana.Ui.showText(Banana.document.table('Accounts').toHtml());

//Show some columns and format dates, amounts, ... as displayed in the program
Banana.Ui.showText(
   Banana.document.table('Accounts').toHtml(['Account','Group','Description','Balance'],true)
);

toTsv([columnNames])

Return the table as Tsv file (Tab separated values). If the parameter columnNames is defined, only the columns in the array are included in the file.

var table = Banana.document.table("Accounts");
var tsv = table.toTsv();

value(rowNr, columnName)

Return the value in row rowNr and column columnName as string. Or undefined if the row or column are not found.

var table = Banana.document.table("Accounts");
var account = table.value(3,'Account'); 
var description = table.value(3,'Description');

 

 

The Banana.IO class is used to read and write to files.

Since: Banana Accounting 8.0.7, only in Banana Experimental

Introduction

The API Banana.IO and Banana.IO.LocalFile allow a script to read or write to files in a secure way. The script can only read or writes to files that are first selected by the user though the corresponding dialogs. The script has no direct access to files on the file system. After the script finished, the permissions to write or read files are canceled.

For example to write the result of a script to a file:

var fileName = Banana.IO.getSaveFileName("Select save file", "", "Text file (*.txt);;All files (*)")
if (fileName.length) {
   var file = Banana.IO.getLocalFile(fileName)
   file.codecName = "latin1";  // Default is UTF-8
   file.write("Text to save ...");
   if (!file.errorString) {
      Banana.IO.openPath(fileContent);
   } else {
      Banana.Ui.showInformation("Write error", file.errorString);
   }
} else {
   Banana.Ui.showInformation("Info", "no file selected");
}

To read the content of a file:

var fileName = Banana.IO.getOpenFileName("Select open file", "", "Text file (*.txt);;All files (*)")
if (fileName.length) {
   var file = Banana.IO.getLocalFile(fileName)
   file.codecName = "latin1";  // Default is UTF-8
   var fileContent = file.read();
   if (!file.errorString) {
      Banana.IO.openPath(fileContent);
   } else {
      Banana.Ui.showInformation("Read error", file.errorString);
   }
} else {
   Banana.Ui.showInformation("Info", "no file selected");
}

Methods

getOpenFileName(caption, path, filter)

The method getOpenFileName returns an existing file selected by the user. If the user presses Cancel, it returns an empty string. The file selected by the user is then allowed to be readen, but not written.

The parameter caption is the caption of the dialog.

The parameter path is path inclusive the file name to be selected. If the path is relative, the current open document path or the user's document path is used.

The parameter filter set the files types to be showed. If you want multiple filters, separate them with ';;', for example: "Text file (*.txt);;All files (*)".

var fileName = Banana.IO.getOpenFileName("Select file to read", "", "Text file (*.txt);;All files (*)")

Since: Banana Accounting 8.0.7, only in Banana Experimental

getSaveFileName(caption, path, filter)

The method getSaveFileName returns an existing file selected by the user. If the user presses Cancel, it returns an empty string. The file selected by the user is then allowed to be readen and written.

The parameter caption is the caption of the dialog.

The parameter path is path inclusive the file name to be selected. If the path is relative, the current open document path or the user's document path is used.

The parameter filter set the files types to be showed. If you want multiple filters, separate them with ';;', for example: "Text file (*.txt);;All files (*)".

var fileName = Banana.IO.getSaveFileName("Select file to write", "", "Text file(*.txt);;All files (*)")

Since: Banana Accounting 8.0.7, only in Banana Experimental

getLocalFile(path)

The method getLocalFile(path) return an object of type Banana.IO.LocalFile that represent the requested file. This method always return a valid Banana.IO.LocalFile object.

The parameter path to the file. 

Since: Banana Accounting 8.0.7, only in Banana Experimental

openUrl(path)

The method openUrl(path) open the file referred by path in the system default application.

The parameter path to the file. 

Since: Banana Accounting 8.0.7, only in Banana Experimental

openPath(path)

The method openPath(path) show the folder containing the file referred by path in the system file manager.

The parameter path to the file. 

Since: Banana Accounting 8.0.7, only in Banana Experimental

The class Banana.Report enable you to create reports, preview and print in Banana Accounting.

Introduction

The report logic is similar to the HTML / CSS logic:

1. Create a Report object .
   • A report contain a list of ReportEements (paragraphs, texts, tables and other)
   • The element can contains other sub-elements
   • For each element you can add a class that is used for rendering the element
2. Create a StyleSheet
   • A stylesheet is composed of StyleElements.
3. You preview and print a report by passing the Report and the Stylesheet object.

Each report sturcture has:

• a ReportElement list
• a Header Element list
• a Footer Element list

// Report
var report = Banana.Report.newReport("Report title");
report.addParagraph("Hello World !!!", "styleHelloWorld");

// Styles
var stylesheet = Banana.Report.newStyleSheet();
var style = stylesheet.addStyle(".styleHelloWorld");
style.setAttribute("font-size", "96pt");
style.setAttribute("text-align", "center");
style.setAttribute("margin-top", "50mm");

var style2 = stylesheet.addStyle("@page");
style2.setAttribute("size", "landscape");

// Print preview
Banana.Report.preview(report, stylesheet);

 

Methods

newReport(title)

Creates a report with title 'title'. The returned object is of type Banana.Report.ReportElement.

To the report you can then add the desired elements, like paragraphs, texts, tables, and so on that construct the structure of the report.

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

 

newStyleSheet()

Creates an empty stylesheet. The returned object is of type Banana.Report.ReportStyleSheet. 

To the stylesheet you can add the styles that format the report.

var stylesheet = Banana.Report.newStyleSheet();

 

newStyleSheet(fileName)

Creates a stylesheet from a file. The file has the same syntax as CSS stylesheets. The file path is relative to the script's path. The path can't contain a '..'' (parent directory).

The returned object is of type Banana.Report.ReportStyleSheet.

You can add further styles to the returned stylesheet.

var reportStyles = Banana.Report.newStyleSheet("styles.css");

*** Content of file styles.css ***
.helloWorldStyle
{
font-size: 96pt;
text-align: center;
margin-top: 50mm;
}

@page
{
size: landscape;
}
*** End of file styles.css ***

 

preview(report, stylesheet)

Opens a print preview Dialog and shows the report with the given stylesheet. 

The page orientation is given by the stylesheet. The default size and orientation is taken from the default printer, or can be set through the stylesheet.

// Set landscape orientation
stylesheet.addStyle("@page {size: landscape}");

// Set page size and orientation
stylesheet.addStyle("@page {size: A5 lanscape}");

// Displays the report
Banana.Report.preview(report, stylesheet);

 

Example: Hello world

// Simple test script using Banana.Report
//
// @id = ch.banana.script.report.helloworld
// @api = 1.0
// @pubdate = 2017-01-02
// @publisher = Banana.ch SA
// @description = Report Hello world
// @task = app.command
// @doctype = *
// @inputdatasource = none
// @timeout = -1
//

function exec(string) {

   // Create the report
   var report = Banana.Report.newReport("Report title");
   
   // Add a paragraph to the report
   report.addParagraph("Hello World !!!", "helloWorldStyle");

   // Define some styles
   var stylesheet = Banana.Report.newStyleSheet();
   
   var style = stylesheet.addStyle(".helloWorldStyle");
   style.setAttribute("font-size", "96pt");
   style.setAttribute("text-align", "center");
   style.setAttribute("margin-top", "50mm");

   var style2 = stylesheet.addStyle("@page");
   style2.setAttribute("size", "landscape");

   // Open Preview
   Banana.Report.preview(report, stylesheet);
}

 

Exemple: an example with tables, page breaks and differents styles

Result

Script

// Test script using Banana.Report
//
// @id = ch.banana.script.report.report
// @api = 1.0
// @pubdate = 2017-01-02
// @publisher = Banana.ch SA
// @description = Test report api
// @task = app.command
// @doctype = *
// @outputformat = none
// @inputdatasource = none
// @timeout = -1
//

function exec(string) {

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

   var pageHeader = report.getHeader()
   pageHeader.addClass("header");
   pageHeader.addText("Page header");
   report.getFooter().addFieldPageNr();

   var watermark = report.getWatermark();
   watermark.addParagraph("Sample built with Script Report API");
 
   report.addParagraph("Report title", "titleStyle");
   report.addParagraph("1. Text", "chapterStyle").setOutline(1);

   report.addParagraph("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do " +
    "eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
    "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip " +
    "ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit " +
    "esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non " +
    "proident, sunt in culpa qui officia deserunt mollit anim id est laborum.");
 
   var paragraph2 = report.addParagraph();
   paragraph2.addText("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do ");
   paragraph2.addText("eiusmod tempor incididunt ut labore et dolore magna aliqua. ", "blueStyle");
   paragraph2.addText("Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ", "boldStlyle");
   paragraph2.addText("ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit ", "underlineStyle boldStyle");
   paragraph2.addText("esse cillum dolore eu fugiat nulla pariatur.");
   paragraph2.addLineBreak();
   paragraph2.addText("Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.", "italicStyle");

   report.addParagraph("2. Table", "chapterStyle").setOutline(1);

   var table = report.addTable();
   table.getCaption().addText("Table caption");
       
   var tableHeader = table.getHeader();
   var tableHeaderRow = tableHeader.addRow();
   tableHeaderRow.addCell("Description", "", 2);
   tableHeaderRow.addCell("Income");
   tableHeaderRow.addCell("Expense");
   tableHeaderRow.addCell("Balance");
 
   var tableRow = table.addRow();
   tableRow.addCell();
   tableRow.addCell("Initial balance");
   tableRow.addCell();
   tableRow.addCell();
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("157.00")).addClass("balanceStyle");

   var tableRow = table.addRow();
   tableRow.addCell(Banana.Converter.toLocaleDateFormat("2014-02-11"));
   tableRow.addCell("Transfer from post office account");
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("500.00"));
   tableRow.addCell();
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("657.00")).addClass("balanceStyle");
 
   var tableRow = table.addRow();
   tableRow.addCell(Banana.Converter.toLocaleDateFormat("2014-02-20"));
   tableRow.addCell("Various payments");
   tableRow.addCell();
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("7250.00"));
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("-6593.00")).addClass("balanceStyle negativeStyle");

   var tableRow = table.addRow("totalrowStyle");
   tableRow.addCell();
   tableRow.addCell("Total transactions");
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("500.00"));
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("7250.00"));
   tableRow.addCell(Banana.Converter.toLocaleNumberFormat("-6593.00")).addClass("balanceStyle negativeStyle");
 
   report.addParagraph("3. Bookmarks and links", "chapterStyle").setOutline(1);

   report.addParagraph("3.1 Internal links", "chapter2Style").setOutline(2);
   report.addParagraph("-> link to bookmark on page 2").setLink("bookmarkpage2");

   report.addParagraph("3.2 External links", "chapter2Style").setOutline(2);
   report.addParagraph("-> link to Banana.ch web page").setUrlLink("http://www.banana.ch");
 
   report.addPageBreak();
 
   var chapter4 = report.addParagraph("4. Pages", "chapterStyle");
   chapter4.setOutline(1);
 
   report.addParagraph("Bookmark on page 2").setBookmark("bookmarkpage2");
 

   // Styles
   var docStyles = Banana.Report.newStyleSheet();
 
   var pageStyle = docStyles.addStyle("@page");
   pageStyle.setAttribute("margin", "20mm 20mm 20mm 20mm");
 
   var headerStyle = docStyles.addStyle("phead");
   headerStyle.setAttribute("padding-bottom", "1em");
   headerStyle.setAttribute("margin-bottom", "1em");
   headerStyle.setAttribute("border-bottom", "solid black 1px");
    
   var footerStyle = docStyles.addStyle("pfoot");
   footerStyle.setAttribute("text-align", "right");
 
   var paragraphStyle = docStyles.addStyle("p");
   paragraphStyle.setAttribute("margin-top", "0.5em");

   var captionStyle = docStyles.addStyle("caption");
   captionStyle.setAttribute("margin-top", "1em");

   var titleStyle = docStyles.addStyle(".titleStyle");
   titleStyle.setAttribute("font-size", "24");
   titleStyle.setAttribute("text-align", "center");
   titleStyle.setAttribute("margin-bottom", "1.2em");

   docStyles.addStyle(".chapterStyle", "font-size:16; margin-top:2em; margin-bottom:0.2em");
   docStyles.addStyle(".chapter2Style", "font-size:12; margin-top:1.4em; margin-bottom:0.2em");
 
   var tableStyle = docStyles.addStyle("table");
   tableStyle.setAttribute("border", "2px solid red");
 
   docStyles.addStyle("td", "border: 1px dashed black; padding: 2px;");

   var tableColStyle = docStyles.addStyle(".balanceStyle");
   tableColStyle.setAttribute("background-color", "#E0EFF6");
   tableColStyle.setAttribute("text-align", "right");

   var totalRowStyle = docStyles.addStyle(".totalrowStyle");
   totalRowStyle.setAttribute("font-weight", "bold");

   var totalBalanceStyle = docStyles.addStyle(".totalrowStyle td.balanceStyle");
   totalBalanceStyle.setAttribute("text-decoration", "double-underline");

   docStyles.addStyle(".blueStyle", "color:blue");
   docStyles.addStyle(".underlineStyle", "text-decoration:underline;");
   docStyles.addStyle(".italicStyle", "font-style:italic;");
   docStyles.addStyle(".boldStyle", "font-weight:bold");

   // Open Preview
   Banana.Report.preview(report, docStyles);
}

The Banana.SDecimal (String Decimal) provide functions to do decimal math calculation that

• use decimal string in the form of '10.00' or '-10' as argument and return value
  • '.' is interpreted as the decimal separator
  • thousand separator are not allowed
• has up to 34  digits of numeric precision
• do accurate decimal rounding

You can use this functions instead of the javascript Number that use floating point arithmetic and are not very suitable for accounting calculation do the rounding differences.

var r = Banana.SDecimal.add('6.50', '3.50');   // return '10.00'
var r = Banana.SDecimal.divide('10', '2');     // return '5.00'
var r = Banana.SDecimal.divide('10', '2', ''); // return '5'
var r = Banana.SDecimal.divide('10', '2');     // return '5.00000'

Rounding context

Functions can be passed a rounding context that specify the rounding properties:

• decimals is the number of decimal digits (default value is 2)
  • null returns the value unrounded.
  • '0' returns with no decimals.
  • '1' to '33' returns the value with the indicated number o decimals.
• mode is the rounding mode (default value is HALF_UP)
  • Banana.SDecimal.HALF_UP the amount are rounded to the nearest. The 0.5 are rounded up.
  • Banana.SDecimal.HALF_EVEN the amount are rounded to the nearest. The 0.5 are rounded up or down based on the preceding digit.

If the rounding context is omitted no rounding is done.

Rounding context of the accounting file

All Banana document file have a rounding context that can be retrieved with the property Banana.document.rounding (see Banana.document).

Examples:

// no context
var r = Banana.SDecimal.divide('10', '3'); // return '3.3333333333333333333333333'

// with context
var context = {'decimals' : 4, 'mode' : Banana.SDecimal.HALF_UP};
var r = Banana.SDecimal.divide('10', '3', context);        // return '3.3333'
var r = Banana.SDecimal.divide('10', '3', {'decimals':0}); // return '3'

// use the rounding property (accunting file 2 decimals)
var r = Banana.SDecimal.divide('10', '3', Banana.document.rounding); // return '3.33'

Functions

abs(value1, [, rounding])

Returns the value1 without the sign and rounded as indicated

var r = Banana.SDecimal.abs('-10') // return '10.00'

add(value1, value2 [, rounding])

Returns the sum of value1 and value2.

var r = Banana.SDecimal.add('6.50', '3.50'); // return '10.00'

compare(value1, value2)

Returns an integer value

• 1 if value1 > value2
• 0 if value1 = value2
• -1 if value1 < value2

Banana.SDecimal.compare('3.50', '2'); // return '1'
Banana.SDecimal.compare('3.00', '3'); // return '0'

divide(value1, value2 [, rounding])

Returns value1 divided by value2.

var r = Banana.SDecimal.divide('6', '3'); // return '2.00'

isZero(value)

Returns a boolean

• true if value is zero
• false if value is not zero

var r = Banana.SDecimal.isZero('3.00'); // return 'false'

max(value1, value2 [, rounding])

Returns the max of value1 and value2.

var r = Banana.SDecimal.max('6', '3'); // return '6.00'

min(value1, value2 [, rounding])

Returns the min of value1 and value2.

var r = Banana.SDecimal.min('6', '3'); // return '3.00'

multiply(value1, value2 [, rounding])

Returns value1 multiplied by value2.

var r = Banana.SDecimal.multiply('6', '3'); // return '18.00'

remainder(value1, value2 [, rounding])

Divide value1 by value2 and returns the reminder.

var r = Banana.SDecimal.reminder('10', '3'); // return '1.00'

round(value1, [, rounding])

Returns value1 round to the spcified rounding context.

var r = Banana.SDecimal.round('6.123456'); // no context no rounding 
r = Banana.SDecimal.round('6.123456', {'decimals':2}); // return '6.12'

roundNearest(value1, nearest, [, rounding])

Returns value1 round to the specified minimal amount.

var r = Banana.SDecimal.roundNearest('6.17', '0.1'); // return '6.1'
r = Banana.SDecimal.roundNearest('6.17', '0.05', {'decimals':2}); // return '6.15'

invert(value, [, rounding])

If positive returns a negative value, if negative returns a positive value.

var a = Banana.SDecimal.invert('5'); //return '-5'
var b = Banana.SDecimal.invert('-2.50'); //return '2.50'

sign(value)

Returns an integer value

• 1 if value > 0
• 0 if  value = 0
• -1 if value < 0

var r = Banana.SDecimal.sign('-5'); // return '-1'

subtract(value1, value2 [, rounding])

Subtract value2 from value1 and returns the result.

var r = Banana.SDecimal.subtract('10', '3'); // return '7.00'

 

Locale conversion

To convert to and from the locale format use the Banana.Converter functions

• Banana.Converter.toInternalNumberFormat(value [, decimals, convZero])

• Banana.Converter.toLocaleNumberFormat(value [, decimalSeparator])

var sum = Banana.SDecimal.add('10000', '2000'); // return '12000.00'
var printValue = Banana.Converter.toLocaleNumberFormat(sum); // return "12'000.00"

 

 

Banana.Script represent the interface to the script file and can be accessed through Banana.script. It is used to get the parameters values defined in the script. For example if you want to print out in a report the publishing date of the script.

Properties

Methods

getParamValue(paramName)

Return the value definend in the script file of the parameter paramName. Return an empty string or the internal default value if the parameter is not defined. Return the first found value, if the parameter is defined multiple times.

Banana.script.getParamValue('pubdate'); // returns for example '2016-05-11'

getParamValues(paramName)

Return all the values defined in the script file of the param paramName . Return an empty array if the parameter paramName is not defined.

// Script.js example:
// ...
// @authors = Pinco
// @authors = Pallino
// ...

Banana.script.getParamValues('authors'); // returns ['Pinco', 'Pallino']

getParamLocaleValue(paramName)

Return the localized value definend in the script file of the param paramName. Return an empty string the parameter is not defined.

// Script.js example:
// ...
// @description = English desciption
// @description.it = Descrizione italiana
// @description.de = German Beschreibung
 ...

Banana.script.getParamLocaleValue('description'); // returns 'Descrizione italiana' for a system running with the locale 'italian'.

This class Banana.Ui contains methods to interact with user interface.

Methods

createUi(uiFilePath)

Read the file uiFilepath and return an object representing the dialog. The uiFileName has to be in the same directory as the running script. For details and examples see Script dialogs.

If an error occurred undefiend is returned.

Example:

@includejs = ch.banana.calculator.dialog.js;  // Define the class Calculator
                                              // that control the .ui file
...
var calculatorUi = Banana.Ui.createUi("ch.banana.calculator.dialog.ui");
var calcJs = new Calculator(calculatorUi); 
calclatorUi.exec();  //Show the dialog

getDouble(title, label [, value , min, max, decimals])

Show the user a dialog asking to insert a double. Return the inserted double or undefined if the user clicked cancel.

var a = Banana.Ui.getDouble("Title text", "Label text");
var b = Banana.Ui.getDouble("Title text", "Label text", "10.0");

getInt(title, label [, value, min, max, steps])

Show the user a dialog asking to insert a integer. Return the inserted integer or undefined if the user clicked cancel.

var a = Banana.Ui.getInt("Title text", "Label text");
var b = Banana.Ui.getInt("Title text", "Label text", "5", "1", "10","1");

getItem(title, label, items [, current, editable])

Show the user a dialog asking to select an intem from a list. Return the selected item or undefined if the user clicked cancel.

var value = Banana.Ui.getItem("Input", "Choose a value", ["a","b","c","d","e"], 2, false);

getPeriod(title, startDate, endDate [, selectionStartDate, selectionEndDate, selectionChecked])

Show the user a dialog asking to select a period like the tab Period. Return an object with the atributes 'startDate', 'endDate' and 'hasSelection' or undefined if the user clicked cancel. Date values are in the format "YYYY-MM-DD".

var period = Banana.Ui.getPeriod("Title text", "2016-01-01", "2016-12-31");
if (period) {
    var selectedStartDate = period.startDate; // return the start date of the selected period
    var selectedEndDate = period.endDate; // return the end date of the selected period
}

getText(title, label [, text])

Show the user a dialog asking to insert a text. Return the inserted text or undefined if the user clicked cancel.

var text = Banana.Ui.getText("Title text","Label text");

showHelp(uiFileName)

Show the help of a dialog. The help is loaded from the Banana.ch web site.

 

showInformation(title, msg)

Show the user an information dialog.

Banana.Ui.showInformation("Information", 'Insert here the text of the information.');

showQuestion(title, question)

Show the user a question dialog with Yes and No buttons. Return true if the user clicked Yes, otherwise false.

var answer = Banana.Ui.showQuestion("Question title", "Insert here the text of the question");

showText(text)

Show the given text in a dialog. The text can be plain text of html and span over multiple lines. If the text is in html the title is taken form the html. The dialog enable the user to save the content in the formats html, pdf, odf and txt.
The use of pixels to set  the font sizes is not supported, the text is not rendered properly.

// Normal text
Banana.Ui.showText("Insert here the text.");

// Html text
Banana.Ui.showText('<html><header><title>This is title</title></header><body>Hello world</body></html>');

showText(title, text)

This is an overloaded function.

Show the given text in a dialog with the given title. The text can be plain text of html and span over multiple lines. The dialog enable the user to save the content in the formats html, pdf, odf and txt.

showText(title, text, options)

This is an overloaded function.

Show the given text in a dialog with the given title. The text can be plain text of html and span over multiple lines. The dialog enable the user to save the content in the formats html, pdf, odf and txt.

Through the object options it is possible to set the following additional parameters:

• codecName: the name of the codec to be used in case the content will be saved as txt file. Default is 'UTF-8'
• outputFileName: the file name without path to be used in case the content will be saved. The path is current open document path or the user's document path.

var options = {
   'codecName' : "latin1", // Default is UTF-8
   'outputFileName' : "prova.txt"
}
Banana.Ui.showText("Title", "some text...", options);

Since Banana 8.0.7

The Banana.Xml class is used to parse and access xml data.​

Since: Banana Accounting 8.0.5

Introduction

The API Banana.Xml and Banana.Xml.XmlElement implement a subset of the DOM Document Object Model interface.  The most used properties and methos are implemented.

For example the list of books in the following xml file:

<Library updated="2016-10-31">
   <Book>
      <Title>Paths of colours</Title>
      <Author>Rosa Indaco</Author>
   </Book>
   <Book>
      <Title>Accounting exercises</Title>
      <Author>Su Zhang</Author>
   </Book>
</Library>

Can be retrieved with the following code:

var xmlFile = Banana.Xml.parse(xml); 
var xmlRoot = xmlFile.firstChildElement('Bookshelf'); 
var updateDate = xmlRoot.attribute('updated');
var bookNode = xmlRoot.firstChildElement('Book');  // First book
while (bookNode) { 
   // For each book in the library
   var title = xmlFile.firstChildElement('Title').text();
   var authorNode = xmlFile.firstChildElement('Author'); 
   var author = authorNode ? authorNode.text() : 'unknow';
   bookNode = bookNode.nextSiblingElement('Book');  // Next book
} 

 

Methods

parse(xml)

The method parse(xml) parses xml data and returns an object of type Banana.Xml.XmlElment that represents the parsed xml. If the xml data is not valid, this method returns null.

var xmlFile = Banana.Xml.parse(xml); 
var xmlRoot = xmlFile.firstChildElement('Bookshelf'); // The root element is named 'Bookshelf' in this example