API availability by document type
JavaScript extensions access the open file through the Banana.document object. The methods available on this object depend on the document type: all documents share the methods of Banana.Document (Base), while accounting files and Estimates and invoices files add their own specific methods.
For the list of document types and their codes, see Documents and document types. Method names on this page are shown without parameters; see the linked API references for signatures, return values and examples.
Overview
| Document type | Code | Available APIs |
|---|---|---|
| Double-entry accounting | 100.* | Base + Accounting |
| Income and expense accounting | 110.* | Base + Accounting |
| Cash book | 130.* | Base + Accounting |
| Simple table | 400.100 | Base |
| Addresses and labels | 400.120 | Base |
| Library and collections | 400.140 | Base |
| Fixed assets register | 400.150 | Base |
| Estimates and invoices | 400.400 | Base + Invoice |
| Inventory | 400.500 | Base |
| Timesheet | 400.600 | Base |
Note: accounting methods, such as currentBalance(), budgetBalance() or vatCurrentBalance(), are available only in accounting files (100.*, 110.*, 130.*). They cannot be used in an Estimates and invoices file or in the other 400.* applications.
Within accounting files, some methods also depend on the features of the file, such as VAT, foreign currencies or budget data. See the Requirements column in the Accounting API section.
Base API (all document types)
These methods and properties are documented in Banana.Document (Base) and are available in every document type.
| Method | Purpose |
|---|---|
info() | Reads a value of the file information (menu Tools > File info), for example the file name or the file type. |
table() | Returns a table of the document, optionally with a specific row list. |
value() | Reads the value of a cell. |
addMessage(), clearMessages(), getMessages() | Manage the messages of the document. |
getScriptSettings(), setScriptSettings() | Read and save the settings of the extension in the file, optionally with an ID. |
applyDocumentChange() | Submits a DocumentChange to the user for confirmation. This is the way to modify data in the file. |
Properties: cursor, locale, rounding, tableNames, uuid.
The methods scriptReadSettings() and scriptSaveSettings() are deprecated. Use getScriptSettings() and setScriptSettings() instead.
Tables, rows and columns
The objects returned by the document have their own methods:
- Table:
addMessage(),column(),extractRows(),findRows(),findRowByValue(),list(),progressiveNumber(),row(),toJSON(),toHtml(),toTsv(),value(). - Row:
addMessage(),toJSON(),value(). - Column and Cursor: properties only.
The tables in a file depend on the document type and its features. For example, the VatCodes table exists only in files with VAT. Check that a table exists with tableNames before reading its rows.
Accounting API (100.*, 110.*, 130.*)
Accounting files add the methods documented in Banana.Document (Accounting).
| Group | Methods | Requirements |
|---|---|---|
| Periods | startPeriod(), endPeriod(), previousYear() | Any accounting file. |
| Accounts and reports | accountDescription(), accountsReport() | Any accounting file. |
| Journal | journal(), journalCustomersSuppliers() | Any accounting file. journalCustomersSuppliers() uses the customer and supplier groups. |
| Actual data | currentBalance(), currentBalances(), currentCard(), currentInterest() | Any accounting file. |
| Budget | budgetBalance(), budgetBalances(), budgetCard(), budgetInterest(), budgetExchangeDifference() | Budget data. budgetExchangeDifference() also requires a multi-currency file and an account in foreign currency; otherwise it returns an empty value. |
| Projections | projectionBalance(), projectionBalances(), projectionCard() | Budget data. Actual data are used up to the projection start date, budget data after it. |
| Customer and supplier invoices | invoicesCustomers(), invoicesSuppliers() | A customer or supplier group, and invoice numbers in the DocInvoice column. |
| Exchange rates | exchangeRate() | Multi-currency file (100.120, 100.130). |
| VAT | vatCurrentBalance(), vatCurrentBalances(), vatCurrentCard(), vatBudgetBalance(), vatBudgetBalances(), vatProjectionBalance(), vatProjectionBalances(), vatProjectiontCard(), vatReport() | File with VAT, with the VAT codes defined in the VatCodes table. |
Notes for accounting files
Double-entry accounting (100.*)
The type code indicates which feature-dependent methods can be used:
100.100: without VAT and without foreign currencies.100.110: with VAT.100.120: with foreign currencies.100.130: with VAT and foreign currencies.
Groups are selected with Gr=. Selection by BClass and the returned bclass property are available only in double-entry accounting.
Income and expense accounting (110.*)
Groups of the Categories table are selected with GrC=. VAT methods require a file with VAT, such as 110.110.
Cash book (130.*)
VAT methods require a file with VAT, such as 130.110; 130.100 is without VAT. The cash book has a simpler structure than double-entry accounting: test the accounting methods your extension uses on a cash book file.
Other applications (400.*)
The applications of group 400 are not accounting files. Accounting methods, such as currentBalance(), budgetBalance() or vatCurrentBalance(), cannot be used with them. Extensions work with their data through the Base API: they read tables, rows and values, and modify data with a DocumentChange.
The table and column names (nameXml) depend on the application. Use tableNames and the columnNames property of a table to read them, or see the nameXml in the program through the column setup.
Simple table (400.100)
A generic table for any kind of data.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table, such as
findRows(),extractRows(),findRowByValue()andtoJSON(), and of Row, such asvalue(). - Specific methods: none.
Addresses and labels (400.120)
Contacts and addresses, for example to print labels or create mailing lists.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods: none.
Library and collections (400.140)
Catalogues of books, objects or collections.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods: none.
Fixed assets register (400.150)
Register of fixed assets and their depreciation. Although it contains accounting-related data, it is not an accounting file: methods such as currentBalance() are not available. To combine its data with accounting balances, an extension must read the accounting file separately.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods: none.
Estimates and invoices (400.400)
Application for estimates and invoices, separate from accounting. This is the only application of group 400 with its own methods, documented in Banana.Document (Invoice & Estimate).
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods:
calculateInvoice(): calculates an invoice passed as a JSON string and returns the completed JSON.printInvoice(): opens the print preview for an invoice passed as a JSON string.
An Estimates and invoices file is different from the customer and supplier invoices recorded in an accounting file. Those are read in the accounting file with invoicesCustomers() and invoicesSuppliers().
Inventory (400.500)
Management of items and stock movements.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods: none.
Timesheet (400.600)
Recording of working hours and absences.
- Document:
info(),table(),value(),tableNames,cursor,locale,rounding,uuid. - Messages:
addMessage(),clearMessages(),getMessages(). - Extension settings:
getScriptSettings(),setScriptSettings(). - Changes to the data:
applyDocumentChange(). - Tables and rows: all methods of Table and Row.
- Specific methods: none.
Example: reading a table in any application
The following example works with every document type, because it uses only the Base API. It lists the tables of the open file and the number of rows of each one.
// @doctype = 400.*
function exec() {
if (!Banana.document) {
return;
}
var tableNames = Banana.document.tableNames;
for (var i = 0; i < tableNames.length; i++) {
var table = Banana.document.table(tableNames[i]);
if (table) {
Banana.console.log(tableNames[i] + ": " + table.rowCount + " rows");
}
}
}
Checking the document in an extension
The @doctype attribute declares which document types an extension is intended for; see Extension attributes. It does not add methods to Banana.document. When an extension supports several document types, check the open file before calling type-specific methods:
- To check the document type, read
FileTypeGroupwithinfo(). - To check a feature, such as VAT or foreign currencies, check that the related table exists in
tableNames.
// @doctype = 100.*;110.*;130.*
function exec() {
if (!Banana.document) {
return;
}
// Accounting methods are available only in accounting files
var fileTypeGroup = Number(Banana.document.info("Base", "FileTypeGroup"));
var isAccounting = fileTypeGroup === 100 || fileTypeGroup === 110 || fileTypeGroup === 130;
if (!isAccounting) {
return;
}
var balance = Banana.document.currentBalance("1000");
Banana.console.log("Balance: " + balance.balance);
// VAT methods require a file with VAT, which has the VatCodes table
var hasVat = Banana.document.tableNames.indexOf("VatCodes") >= 0;
if (hasVat) {
var vat = Banana.document.vatCurrentBalance("V81");
Banana.console.log("VAT amount: " + vat.vatAmount);
}
}
In the example, the account 1000 and the VAT code V81 must exist in the file.
Other extension APIs
Besides Banana.document, extensions can use other objects that do not depend on the document type, for example Banana.application, Banana.Report, Banana.Converter, Banana.SDecimal, Banana.IO, Banana.Ui, Banana.Xml and Banana.console. See Banana (Objects).