Jam.py documentation

Task tree

All objects of the framework represent a tree of objects. These object are called items.

All items of the tree have common ancestor class AbstractItem ( client reference / server reference ) and common attributes:.

  • ID - unique in the framework ID of the item
  • owner - immediate parent and owner of the item
  • task — root of the task tree
  • items — list of child items
  • item_type — type of the item — one of the following values:
    • “task”,
    • “items”,
    • “details”,
    • “reports”,
    • “item”,
    • “detail_item”,
    • “report”,
    • “detail”
  • item_name — the name of the item that will be used in programming code to get access to the item
  • item_caption — the item name that appears to users

At the root of the tree is the task item.

The task contains group items. There are three types of groups that have the following values of the item_type attribute:

  • “items” - these groups contain items with “item” item_type, that can have associated database table.
  • “details” - such groups also contain items that can have associated database tables, but they can be used to create details for other items (see Details ).
  • “reports” - these groups contain reports - items with “report” item_type, that are used to create reports.

You can create your own groups.

Items that can have associated database table can own details, that are used to store records that belong to a record of the master.

For example the task tree of the Demo project is:


At the root of the task tree is a task with the item_name demo. It has four groups: catalogs, journals, details and reports. The catalogs, journals groups have item_type “items”. The items they own are wrappers over the corresponding database tables. There is one detail item with item_name invoice_table, that also has it’s own database table, and three reports in the reports group.

The invoices journal has the invoice_table detail, which keeps a list of tracks in an customer’s invoice. So there are two items with the same name “invoice_table” (detail_item and detail). They share the same database table.

Every item is an attribute of its owner and all items, tables and reports are attibutes the task as well (they all have a unique item_name).

A task is a global object on the client. To access it, just type task anywhere in the code.

On the server, the task is not global. Jam.py is an event-driven environment. Each event has as an parameter the item (or field) that triggered the event. Functions defined in the server module of an item that can be executed from the client module using the server method have the corresponding item as the first parameter as well.

In the example below, the send_email function, defined in the client module of the Mail item in the Demo project executes send_email function defined in the server module of the Mail item:

function send_email(item) {
    var customers = task.customers.selections;
    try {
        if (!customers.length) {
        item.server('send_email', [customers, item.subject.value, item.mess.value],
            function(result, err) {
                // the code processing the result of function execution
    catch (e) {}

The send_email function on the server have the Mail item of the server task tree as the first argument and uses its task attribute to access the Customers item of the task tree:

import smtplib

def send_email(item, customers, subject, mess):
    cust = item.task.customers.copy()
    # the code sening email

Knowing an item, we can access any other item of the task tree. For example to get access to the customers catalog we can write


or just


The hierarchical structure of the project is one of the bases of the DRY (don’t repeat yourself) principle of the framework.

For example, some methods of the items, when executed, successively generate events for the task, group and the item.

This way we can define a basic behavior for all items in the event handler of the task, that can be expanded in the event handler of the group, and finally, if nessesary, can be specified in the event handler of the item itself. For more details see Form events


The Task tree video tutorial demonstrates the task tree using Demo project