Jam.py documentation


All items, working with database table data have a fields attribute - a list of field objects, which are used to represent fields in item’s table records.

Every field have the following attributes:

Client Server Description
owner owner The item that owns this field.
field_name field_name The name of the field that will be used in programming code to get access to the field object.
field_caption field_caption The name of the field that appears to users.
field_type field_type Type of the field, one of the following values: text, integer, float, currency, date, datetime, boolean, blob.
field_size field_size A size of the field with type text
required required Specifies whether a nonblank value for a field is required.

To get access to the item dataset data, the Field class have the following properties:

Client Server Description
value value Use this property to get or set the field’s value of the current record. When reading the value is converted to the type of the field. So for fields of type integer, float and currency, if value for this field in database table record is NULL, value of this property is 0. To get unconverted value use the raw_value property.
text text Use this property to get or set the value of the field as text.
lookup_value lookup_value Use this property to get or set lookup value, see Lookup fields.
lookup_text lookup_text Use this property to get or set the lookup value of the field as text, see Lookup fields.
display_text display_text Represents the field’s value as it is displayed in data-aware controls. When the field is a lookup field it’s value is the lookup_text value, otherwise it is the text value, with regard of project locale parameters. This behavior can be overriden by the on_field_get_text event handler of the item that owns the field.
raw_value raw_value Use this property to get field value of the current record as it is stored in database. No conversion is used.

In addition every field is an attribute of the item that owns it. So, to get access to a field of an item use the following syntax: item.field_name


invoices.total is the reference to the Total field of the Invoices item and the invoices.total.value is the value of this field

The following on_created events handler, when executed on the server of the Demo application

def on_created(task):

    def get_field_text(field):
        if field.field_name == 'customer':
            return field.owner.firstname.lookup_value + ' ' + field.lookup_value

    invoices = task.invoices.copy()
    invoices.open(fields=['customer', 'firstname', 'billing_address', 'id',
        'invoicedate', 'total'], limit=1)
    invoices.on_field_get_text = get_field_text
    for field in invoices.fields:
        print field.field_name, field.field_type
        print '   value: ', field.value
        print '   text: ', field.text
        print '   lookup_value: ', field.lookup_value
        print '   lookup_text: ', field.lookup_text
        print '   display_text: ', field.display_text

will print:

customer integer
   value:  44
   text:  44
   lookup_value:  Hämäläinen
   lookup_text:  Hämäläinen
   display_text:  Terhi Hämäläinen
firstname integer
   value:  44
   text:  44
   lookup_value:  Terhi
   lookup_text:  Terhi
   display_text:  Terhi
billing_address integer
   value:  44
   text:  44
   lookup_value:  Porthaninkatu 9
   lookup_text:  Porthaninkatu 9
   display_text:  Porthaninkatu 9
id integer
   value:  411
   text:  411
   lookup_value:  None
   display_text:  411
invoicedate date
   value:  2016-12-16
   text:  12/16/2016
   lookup_value:  None
   display_text:  12/16/2016
total currency
   value:  16.64
   text:  16.64
   lookup_value:  None
   display_text:  $16,64

The similar code in javascript is as follows:

function on_page_loaded(task) {
    var invoices = task.invoices.copy();
    invoices.open({fields: ['customer', 'firstname', 'billing_address', 'id',
        'invoicedate', 'total'], limit: 1});
    invoices.on_field_get_text = function(field) {
        if (field.field_name == 'customer') {
            return field.owner.firstname.lookup_value + ' ' + field.lookup_value;
    invoices.each_field(function(field) {
        console.log(field.field_name, field.field_type);
        console.log('   value: ', field.value);
        console.log('   text: ', field.text);
        console.log('   lookup_value: ', field.lookup_value);
        console.log('   lookup_text: ', field.lookup_text);
        console.log('   display_text: ', field.display_text);
    //some other code