API availability by document type

Documentation •
In this article

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 typeCodeAvailable APIs
Double-entry accounting100.*Base + Accounting
Income and expense accounting110.*Base + Accounting
Cash book130.*Base + Accounting
Simple table400.100Base
Addresses and labels400.120Base
Library and collections400.140Base
Fixed assets register400.150Base
Estimates and invoices400.400Base + Invoice
Inventory400.500Base
Timesheet400.600Base

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.

MethodPurpose
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).

GroupMethodsRequirements
PeriodsstartPeriod(), endPeriod(), previousYear()Any accounting file.
Accounts and reportsaccountDescription(), accountsReport()Any accounting file.
Journaljournal(), journalCustomersSuppliers()Any accounting file. journalCustomersSuppliers() uses the customer and supplier groups.
Actual datacurrentBalance(), currentBalances(), currentCard(), currentInterest()Any accounting file.
BudgetbudgetBalance(), 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.
ProjectionsprojectionBalance(), projectionBalances(), projectionCard()Budget data. Actual data are used up to the projection start date, budget data after it.
Customer and supplier invoicesinvoicesCustomers(), invoicesSuppliers()A customer or supplier group, and invoice numbers in the DocInvoice column.
Exchange ratesexchangeRate()Multi-currency file (100.120, 100.130).
VATvatCurrentBalance(), 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() and toJSON(), and of Row, such as value().
  • 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 FileTypeGroup with info().
  • 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).

How can we help you better?

Let us know what topic we should expand or add to make this page more useful.

Send us your feedback

Share this article: Twitter | Facebook | LinkedIn | Email