open¶

open(options, callback, async)¶

domain: client

language: javascript

class Item class

Description¶

Call open to sends a request to the server for obtaining an item dataset.

The open method can have the following parameters:

options - an object that specifies the parameters of the request sent to the server
callback: if the parameter is not present, the request is sent to the server synchronously, otherwise, the request is executed asynchronously and after the dataset is received, the callback is executed
async: if its value is true, and callback parameter is missing, the request is executed asynchronously

The order of parameters doesn’t matter.

The method initializes the item fields, formulates parameters of a request, based on the options and triggers the on_before_open event handler if one is defined for the item.

After that it sends the request to the server. If callback parameter-function is specified, the request is executed asynchronously, otherwise - synchronouslly.

The server, after recieving the request, checks if the corresponding item on the server (item of the task tree with the same ID attribute) has the on_open event handler. If so it executes this event handler and returns the result of the execution to the client, otherwise generates a SELECT SQL query, based on parameters of the request, executes this query and returns the result to the client.

The client, after receiving the result of the request, changes its dataset and sets active to true, the item_state to browse mode, goes to the first record of the dataset, triggers on_after_open and on_filters_applied event handlers (if they are defined for the item), and updates controls.

Then it calls callback function if it was specified.

Options¶

The options object parameter can have the following attributes:

expanded - if the value of this attribute is true, the SELECT query, generated on the server, will have JOIN clauses to get lookup values of the lookup fields , otherwise no lookup values will be returned. The default value if true.
fields - use this parameter to specify the WHERE clause of the SELECT query. This parameter is a list of field names. If it is omitted, the fields defined by the set_fields method will be used. If the set_fields method was not called before the open method execution, all the fields created by a developer will be used.
where - use this parameter to specify how records will be filtered in the SQL query. This parameter is an object of key-value pairs, where keys are field names, that are followed, after double underscore, by a filtering symbols (see Filtering records ). If this parameter is omitted, values defined by the set_where method will be used. If the set_where method was not called before the open method execution, and where parameter is omitted, then the values of filters defined for the item will be used to filter records.
order_by - use order_by to specify sort order of the records. This parameter is a list of field names. If there is a sign ‘-’ before the field name, then on this field records will be sorted in decreasing order. If this parameter is omitted, a list defined by the set_order_by method will be used.
offset - use offset to specify the offset of the first row to return.
limit - use limit to limit the output of a SQL query to the first so-many rows.
funcs - this parameter can be a an object of key-value pairs, where key is a field name and value is function name that will be applied to the field in the SELECT Query
group_by - use group_by to specify fields to group the result of the query by. This parameter must be a list of field names.
open_empty - if this parameter is set to true, the application does not send a request to the server but just initializes an empty dataset. The default value if false.
params - use the parameter to pass some user defined options to be used in the on_open event handler on the server. This parameter must be an object of key-value pairs

Note

When the paginate attribute of the item is set to true and a table is created by the create_table method, the limit and offset parameters are set internally by the table depending on its row number and current page.

Examples¶

function get_customer_sales(task, customer_id) {
    var date1 = new Date(new Date().setYear(new Date().getFullYear() - 5)),
        date2 = new Date(),
        invoices = task.invoices.copy();

    invoices.open({
        fields: ['customer', 'invoicedate', 'total'],
        where: {customer: customer_id, invoicedate__ge: date1, invoicedate__le: date2},
        order_by: ['invoicedate']
    });
}

function get_customer_sales(task, customer_id) {
    var date1 = new Date(new Date().setYear(new Date().getFullYear() - 5)),
        date2 = new Date(),
        invoices = task.invoices.copy();

    invoices.set_fields(['customer', 'invoicedate', 'total']);
    invoices.set_where({customer: customer_id, invoicedate__ge: date1, invoicedate__le: date2});
    invoices.set_order_by(['invoicedate']);
    invoices.open();
}

function get_sales(task) {
    var sales = task.invoices.copy();

    sales.open({
        fields: ['customer', 'id', 'total'],
        funcs: {'id': 'count', 'total': 'sum'},
        group_by: ['customer'],
        order_by: ['customer']
    });
}