Jam.py documentation

Forms

One of the key concepts of the framework is the concept of form.

When the user clicks the menu item of the main menu, the view method of the corresponding item is executed, which creates the view form.

This view form can have the New and Edit buttons, clicking on which the insert_record and edit_record methods will be executed. These methods create an item edit form.

Forms are based on HTML form templates that determine their layout. Form templates are defined in the Index.html file, located in the root folder of the project.

The application already has default templates for viewing and editing data, for specifying filters and report parameters.

For example, all edit forms of the Demo project use the following html template:

<div class="default-edit">
    <div class="form-body">
        <div class="edit-body"></div>
        <div class="edit-detail"></div>
    </div>
    <div class="form-footer">
        <button type="button" id="ok-btn" class="btn expanded-btn">
            <i class="icon-ok"></i> OK<small class="muted">&nbsp;[Ctrl+Enter]</small>
        </button>
        <button type="button" id="cancel-btn" class="btn expanded-btn">
            <i class="icon-remove"></i> Cancel
        </button>
    </div>
</div>

You can define your own form templates to create your own custom forms. See Form templates

When some method creates a form the application finds corresponding html template.

If container (a Jquery object) parameter is specified, the method empties it and appends the html template to it, otherwise, it creates an empty modal form and appends the template to the form.

After this it assigns item’s prefix_form attribute to the template, triggers an on_prefix_form_created events, shows the form and triggers on_prefix_form_shown events, where prefix is a type of the form (view, edit, filter, param). See Form events for details.

Below is an example of the on_edit_form_created event handler of the task:

function on_edit_form_created(item) {
    item.edit_form.find("#ok-btn").on('click.task', function() { item.apply_record() });
    item.edit_form.find("#cancel-btn").on('click.task', function(e) { item.cancel_edit(e) });

    if (!item.master && item.owner.on_edit_form_created) {
        item.owner.on_edit_form_created(item);
    }
    if (item.on_edit_form_created) {
        item.on_edit_form_created(item);
    }

    item.create_inputs(item.edit_form.find(".edit-body"));
    item.create_detail_views(item.edit_form.find(".edit-detail"));

    return true;
}

In this example, the the find method of JQuery is used to to find elements on the form.

First, we assign a JQuery click event to OK and Cancel buttons, so cancel_edit and apply_record methods will be executed when user clicks on the buttons. This methods cancel or apply changes made to the record respectively and call the close_edit_form method to close the form.

Then, if item is not a detail and has an event handler on_edit_form_created, defined in the owner’s client module, this event handler is executed.

After that, if item has an event handler on_edit_form_created, defined in the item’s client module, this event handler is executed.

In these event handlers some additional actions could be executed. For example you can assign click events to buttons or some other elements contained in your edit form template, change edit_options, create tables using the create_table method and so on.

Then the create_inputs method is called to create inputs in the element with class “edit-body”

Finally, create_detail_views method is called to create details in the element with class “edit-detail”

Note

If some elements are missing in the form template, an exception will not be raised.

The close_prefix_form, where prefix is the type of the form, closes the form of this type. But before form is closed the on_prefix_form_close_query and on_prefix_form_closed events are triggered. After form is closed it is removed from the DOM.